These are Alyssa M's notes on the GPU kernel driver, covering the Linux kernel driver, m1n1's tracer, and the underlying firmware/hardware behavior. See also Lina's notes in docs/hw/soc/agx.md. The firmware structures change a lot between different versions, and have some extra fields for specific hardware; m1n1 handles this with the 'Ver' wrapper, the kernel uses 'versions' and the versioned GpuManager trait. Status: Alyssa is working on 14.x @ https://codeberg.org/shiz/m1n1/commits/branch/alyssa-drama - M1/G13: can initialize 14.x and run a compute shader, but it doesn't work - probably this is fixed now, but haven't re-checked - M2/G14: haven't tried yet, but hopefully a middle ground - M3/G15: most structures are understood now, bringup is WIP, basic compute shader works - M4/G16, M5/G17: future work :) == Misc notes == * M3/G15 IOUAT VA size is 43 bits * "SKU" seems to be Apple's name for the microsequences; the firmware will complain about "Unknown SKU command type" if you use the wrong command types. == Opens == * gpu.rs claims that "map_kernel_to_user" is required on G14X+ due to a new thing in the Scene structure. Is this about control_word? (Is it used?? I am so confused.) TODOs: * Use the 'Default' class for some of the m1n1 structs (now that I understand why we need it). * WorkQueue::dump_info in the kernel prints 'GPU rptr1' three times. * WaitForIdleCmd doesn't appear to be waiting for idle (it blocks even when idle?). == Initialization == You will need to configure the IOUAT, since you need to pass VAs to the firmware. There's some 'handoff' mechanism which presumably ensures that the firmware is quiescent while you do so. The CPU's TTBAT is at gpu-region-base. I believe the intention is that the OS should allocate a new TTBR1, in which case the firmware expects the L2 PTE for the shared region (underneath TTBR1) to point at the gfx-shared-l2-region-base (so that the page tables can be shared). However, both Linux and m1n1 use the first page of gfx-shared-region as TTBR1 instead; this seems to be the firmware-side TTBR1, which includes firmware-only mappings, which are useful for crash dumps, and means that both sides have a unified view. To boot the firmware, send an init message with a pointer to an InitData struct (as Lina said: reader beware, here be pointer-shaped dragons). The HWData structures are created by m1n1 and pointers are added to the device tree (/reserved-memory/{hw-cal-a, hw-cal-b, globals}). The kernel driver just copies them. The relevant m1n1 code is in 'rust/src/gpu'. For 14.x, we provisionally added a "power" region for the power fields which used to be in globals, and dropped 'hw-cal-b'. Finally, send a DC_Init message on the DevCtrl channel. Hopefully the coprocessor doesn't crash! == Contexts/GPU VMs == There are 64 contexts in the UAT. The ASC firmware uses the first one (context 0) itself; for simplicity, both m1n1 and the kernel driver also use context 0 for structures that need to be accessible by the firmware (although this is an arbitrary choice). m1n1 refers to the context ID as 'context_id', while the kernel code calls it 'vm_slot'. The kernel driver 'binds' a Vm to context IDs 1-63 as needed. There are also two Vm instances for 'kernel' structures ("kernel_lower_vm" and "kernel_vm", for the lower/upper halves of the address space of context 0). == Work == The RunWorkQueueMsg struct has a pointer to a QueueInfo struct which contains: * pointers to ringbuffer state and the ringbuffer itself (for commands) * notifier_list: linked list which points to itself and otherwise seems unused (also by macOS). It is 'list_head' in NotifierState (which the kernel driver doesn't seem to care about). * wptr (aka 'head'): The position in the ringbuffer to _write_ to. Maybe only used by SW? * event_slot: The event ID (for notifications?); see notes below. == Job submission == The hardware has 4 workqueues for 'normal' jobs, each of which has 3 channels: * Vertex ('TA') * Fragment ('3D') * Compute ('CL') Each channel has an underlying ring buffer for messages; for these workqueues, the ring buffer contains instances of RunWorkQueueMsg. The kernel driver has a QueueJob struct which contains SubQueueJob structs for each channel (sj_vtx, sj_frag, sj_comp). Queue::submit creates the commands and then calls Job::add (or Job::add_cb) for every command (on the relevant SubQueueJob). The commands can be: * Barrier (on vertex or compute channels) * RunCompute (via submit_compute in queue/compute.rs) * RunFragment and RunVertex (via submit_render in queue/render.rs) (Linux's submit_render also always adds a Barrier to the fragment queue, set to wait for the vertex command to complete.) The commands themselves basically boil down to "run this microsequence". In the kernel, we create a JobSubmission object by calling Job::submit. This writes all the pending commands into the queue's ring buffer. Finally, submission is done by calling JobSubmission::run. This creates the RunWorkQueueMsg, then calls channel.send to write the message to the ring buffer (TxChannel::put in channel.rs) and notify the firmware by sending a 'kick' command. == Event notifications == When work is complete, a value is written to a 'stamp' (32-bit word). As discussed below, events are signalled when enough completions have occurred. The hardware supports 128 events, identified by their ID (0 to 127). The Linux logic is in event.rs, which calls them 'event slots'. Each event ID is associated with values for a 'cpu-side' event stamp ('driver notification') and a firmware event stamp; the driver is responsible for allocating memory for these values. Linux stores them in two arrays in EventManagerInner. The RunVertex/RunFragment/RunCompute commands have a JobMeta struct containing: * pointers to both cpu-side and firmware stamps * an event ID ('stamp_slot'), presumably for notification * 'evctl_index'. TODO: always set to 0 by the kernel driver. What is it? * 'stamp_value', TODO * 'event_seq', TODO The Barrier command is more lightweight, but still gets: * 'wait_stamp', a pointer to the firmware event stamp * an event ID ('wait_slot'), presumably to wake them up * 'wait_value', presumably the stamp value to wait for * 'stamp_self', TODO: this is a bit odd TODO: puzzle over QueueEventInfo. seems like the kernel allocates an event slot for each WorkQueue? this ends up in SubmittedWork::value (an EventValue) where it's used internally, but also it is passed to the Job constructor * How are events signalled? EventMsg::Flag (aka FlagMsg) has a 'firing' field; each bit corresponds to an event ID. The Event channel logic calls ev_mgr.signal() for every set bit. EventManager keeps track of the owner of each event ID (aka 'slot'), and calls signal() on the owner, which is always a WorkQueue. * When are events signalled? The kernel 'NotifierState' (m1n1's "EventControl") specifies the current notification count and a threshold. Every time a command (compute, vertex or fragment) completes, the notification count is increased. When it reaches the threshold, the event is fired. == Misc notes == * Attachments: Attachments (as noted in the asahi_drm.h UAPI header) are optional. An oracle told us that leaving out attachments doesn't affect correctness and it's unclear whether they affect performance. They are used by macOS. See also "AGX coherency, caching, and TLBs": https://gist.github.com/hoshinolina/1a70f1f26b9cd3c52d61d2b8e8b27673 * Stats channel: This seems unchanged in 14.x, at least on the M1; we get the expected messages in the right format. The padding is often non-zero on the M3, but that is probably not meaningful.. == HOWTO: tracing == Pass "-m proxyclient/hv/trace_agx.py" to m1n1. Once you saw the InitData, you can pause tracing. "agx_tracer.pause_after_init = True" will do this for you. Run "pause_tracing(ctx)" to pause tracing; you can later resume it (when you're launching or running the thing you care about) using "resume_tracing(ctx)". Create a 'gfxlogs' directory first, because the resume_tracing function changes the logfile (to one in that directory). You can presumably do 'hlt 100' and 'hlt 101' to resume/pause tracing from the guest, but I didn't try it yet (TODO). == HOWTO: play with GPU firmware == Add this to trace_agx.py to get the HW init blobs (make a 'gfxblobs' directory), and run MacOS: agx_tracer.save_blobs = True (You can probably also get them from m1n1's rust code by jumping through some hoops. Or fix the m1n1 code to support creating them from Python too..) Then run 'proxyclient/experiments/agx_test14.py'. == HOWTO: port to a new firmware version / hardware variant == Lots of manual work, unfortunately. 13.x->14.x was a relatively minimal delta but it is taking a lot of time because there were a lot of little changes everywhere. But basically, add the new version to m1n1's tracer, start by fixing up InitData and then just iterate until the tracer works. Then update m1n1's HWData structures and then finally the kernel driver. You can do 'AGXTracer._reloadcls' to reload a lot of things; this is very helpful when trying to work out the contents of structs. For doing iterative/incremental work you can add little loops which will parse/print and then pop a python shell. == Random tips == * Build mesa like this (well, you don't need the tests): meson configure build -Dgallium-drivers=asahi -Dvulkan-drivers=asahi -Dbuild-tests=true -Dtools=asahi * Then export AGXDECODE to get dumps from m1n1 (from the tests and from the AGX tracer): export AGXDECODE=[...]/mesa/build/src/asahi/lib/libasahi_decode.so * Disable HDCP (in 14.x, at least): self.adt["chosen"].disable_av_content_protection = 1