From d12b97122ead40bc5092523720e974ec5da0de8e Mon Sep 17 00:00:00 2001 From: Alyssa Rosenzweig Date: Sun, 22 May 2022 17:57:34 -0400 Subject: [PATCH] docs/asahi: Add initial driver docs Emma asked for some docs on how to use wrap for when wrap gets landed. This should do :-) Signed-off-by: Alyssa Rosenzweig Part-of: --- docs/drivers/asahi.rst | 39 +++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 40 insertions(+) create mode 100644 docs/drivers/asahi.rst diff --git a/docs/drivers/asahi.rst b/docs/drivers/asahi.rst new file mode 100644 index 00000000000..c58b0405bc4 --- /dev/null +++ b/docs/drivers/asahi.rst @@ -0,0 +1,39 @@ +Asahi +===== + +The Asahi driver aims to provide an OpenGL implementation for the Apple M1. + +Testing on macOS +----------------- + +On macOS, the experimental Asahi driver may built with options: + + -Dosmesa=true -Dglx=xlib -Dgallium-drivers=asahi,swrast + +To use, set the ``DYLD_LIBRARY_PATH`` environment variable: + + DYLD_LIBRARY_PATH=/Users/nobody/mesa/build/src/gallium/targets/libgl-xlib/ glmark2 --reuse-context + +Only X11 apps are supported. XQuartz must be setup separately. + +Wrap (macOS only) +----------------- + +Mesa includes a library that wraps the key IOKit entrypoints used in the macOS +UABI for AGX. The wrapped routines print information about the kernel calls made +and dump work submitted to the GPU using agxdecode. + +This library allows debugging Mesa, particularly around the undocumented macOS +user-kernel interface. Logs from Mesa may compared to Metal to check that the +UABI is being used correcrly. + +Furthermore, it allows reverse-engineering the hardware, as glue to get at the +"interesting" GPU memory. + +The library is only built if ``-Dtools=asahi`` is passed. It builds a single +``wrap.dylib`` file, which should be inserted into a process with the +``DYLD_INSERT_LIBRARIES`` environment variable. + +For example, to trace an app ``./app``, run: + + DYLD_INSERT_LIBRARIES=~/mesa/build/src/asahi/lib/libwrap.dylib ./app diff --git a/docs/index.rst b/docs/index.rst index 76758548986..762a3eba51a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -84,6 +84,7 @@ Linux, FreeBSD, and other operating systems. :hidden: drivers/anv + drivers/asahi drivers/d3d12 drivers/freedreno drivers/lima