diff --git a/docs/developing-extensions.rst b/docs/developing-extensions.rst new file mode 100644 index 00000000000..e3c403d164b --- /dev/null +++ b/docs/developing-extensions.rst @@ -0,0 +1,155 @@ +Developing Extensions +===================== + +Drafting new MESA extensions +---------------------------- + +The Mesa project works closely with Khronos, the standards body that +governs the OpenGL, OpenCL, EGL, and Vulkan specifications. Mesa +developers are often spec authors and not just implementors. There are +several ``GL_MESA_*`` and ``VK_MESA_`` extensions which serve the unique +needs of the Linux graphics ecosystem as well as many other vendor, EXT, +and even KHR extensions extensions with Mesa developers as authors. + +There are generally two processes for developing new extensions. For +developers who work for a Khronos member company, extensions can be +developed via the normal Khronos process. This means making a merge +request to the Khronos internal repositories, responding to review feedback +from the working group, and participating in the conference calls where +in-development extensions are discussed. This process happens under the +Khronos NDA and is a little more heavy-weight than most Mesa discussions. +However, this is generally the preferred method from a Khronos perspective +because the NDA gives the hardware company representativs the freedom to be +more involved with extension review. + +Alternatively, extensions can be developed in public. This is done by +opening a pull request against the ``KhronosGroup/Vulkan-Docs`` and related +repositories on GitHub. The advantage of this process is that it is +publicly visible and more accessible to open-source developers. This makes +it the preferred process when developing something that needs broad Linux +ecosystem consensus and where we need review from people who aren't under +the Khronos NDA. The downside is that hardware company representatives are +much less likely to interact. If the extension exposes hardware and not +software details, it's better to go through the Khronos process. + +Regardless of which path is taken, any extensions bearing the MESA prefix, +need to adhere to the following policy: + + 1. The extension needs to be accompanied by a Mesa merge request and the + extension MR needs to link to the Mesa MR. For public extensions, both + merge requests should be public and they should link to each other. + For extensions developed under the Khronos NDA, the Mesa merge request + can be made in the Khronos-internal Mesa repo. + + 2. As with all other extensions, MESA extensions must be accompanied by + CTS tests to ensure we can regression test them in CI. + + 3. Before the extension gets merged and released, the Mesa implementation + must be complete, passing the relevant CTS tests, and the code + reviewed. For extensions developed under the Khronos NDA, further + review may happen when the implementation goes public. However, + developers should make a good-faith effort to get enough relevant + review while the extension is still in development to find any issues + which may impact the specification itself. + + +Implementing new extensions +--------------------------- + +Updating Khronos XML and headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When implementing a brand new extension, Mesa's copies of the relevant spec +assets may need to be updated: + +- For Vulkan, the headers are placed in ``include/vulkan/`` and the XML + description is placed in ``src/vulkan/registry/vk.xml`` + +- For SPIR-V, the headers and JSON files are placed in + ``src/compiler/spirv/``. + +- For OpenGL and OpenGL ES, the headers are placed in ``include/GL/`` or + ``include/GLES*/`` and the XML description is placed in + ``src/mesa/glapi/glapi/registry/gl.xml``. + +- For EGL, the headers are placed in ``include/EGL/`` and the XML + description is placed in ``src/egl/generate/egl.xml``. + +- For OpenCL, the headers are placed in ``include/CL/``. + +All of these must be updated with the ``khronos_update.py`` script in +``bin/``. They should not be updated manually. The script updates all +headers and XML/JSON descriptions by default but only the changes for the +relevant API need to be checked in. When updating XML or headers, provide +a descriptive commit message that specifies the new version. + + +Implementing Vulkan extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As of today, implementing Vulkan extensions is a mostly per-driver process. +Pulling a new XML and headers will automatically update all the dispatch +table and other codegen. It's then up to the driver to implement and +advertise the extension. When advertising a new extension, remember that +there are generally three places that need updating: + + - The driver's supported extensions table + - The driver's supported features table + - The driver's properties table + +The extensions and features tables are split in two: physical device and +instance. The instance tables are used for instance extensions and the +physical device tables are used for physical device extensions. Only +physical device extensions have properties. + + +Implementing SPIR-V capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SPIR-V features are typically implemented in terms of capabilities, not +extensions. While SPIR-V does have extension strings, Mesa generally +ignores them. When implementing a new SPIR-V feature, the +``implemented_capabilities`` table needs to be updated. This table only +describes the capabilities implemented by the SPIR-V parser. There is also +a ``supported_capabilities`` table that gets passed into the SPIR-V parser. + +For OpenGL or OpenCL, implementing a new SPIR-V capability requires also +updating the ``supported_capabilities`` in the relevant state tracker. For +Vulkan, ``supported_capabilities`` is automatically populated based on the +Vulkan device's physical device features. + + +Implementing OpenGL[ES] extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add a new GL extension to Mesa you have to do at least the following. + +- If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h`` + and add code like this: + + .. code-block:: c + + #ifndef GL_EXT_the_extension_name + #define GL_EXT_the_extension_name 1 + /* declare the new enum tokens */ + /* prototype the new functions */ + /* TYPEDEFS for the new functions */ + #endif + + +- In the ``src/mesa/glapi/glapi/gen/`` directory, add the new extension + functions and enums to the ``gl_API.xml`` file. Then, a bunch of + source files must be regenerated by executing the corresponding + Python scripts. +- Add a new entry to the ``gl_extensions`` struct in ``consts_exts.h`` if + the extension requires driver capabilities not already exposed by + another extension. +- Add a new entry to the ``src/mesa/main/extensions_table.h`` file. +- From this point, the best way to proceed is to find another + extension, similar to the new one, that's already implemented in Mesa + and use it as an example. +- If the new extension adds new GL state, the functions in ``get.c``, + ``enable.c`` and ``attrib.c`` will most likely require new code. +- To determine if the new extension is active in the current context, + use the auto-generated ``_mesa_has_##name_str()`` function defined in + ``src/mesa/main/extensions.h``. diff --git a/docs/devinfo.rst b/docs/devinfo.rst deleted file mode 100644 index 34921c10ca4..00000000000 --- a/docs/devinfo.rst +++ /dev/null @@ -1,37 +0,0 @@ -Development Notes -================= - -Adding Extensions ------------------ - -To add a new GL extension to Mesa you have to do at least the following. - -- If ``glext.h`` doesn't define the extension, edit ``include/GL/gl.h`` - and add code like this: - - .. code-block:: c - - #ifndef GL_EXT_the_extension_name - #define GL_EXT_the_extension_name 1 - /* declare the new enum tokens */ - /* prototype the new functions */ - /* TYPEDEFS for the new functions */ - #endif - - -- In the ``src/mesa/glapi/glapi/gen/`` directory, add the new extension - functions and enums to the ``gl_API.xml`` file. Then, a bunch of - source files must be regenerated by executing the corresponding - Python scripts. -- Add a new entry to the ``gl_extensions`` struct in ``consts_exts.h`` if - the extension requires driver capabilities not already exposed by - another extension. -- Add a new entry to the ``src/mesa/main/extensions_table.h`` file. -- From this point, the best way to proceed is to find another - extension, similar to the new one, that's already implemented in Mesa - and use it as an example. -- If the new extension adds new GL state, the functions in ``get.c``, - ``enable.c`` and ``attrib.c`` will most likely require new code. -- To determine if the new extension is active in the current context, - use the auto-generated ``_mesa_has_##name_str()`` function defined in - ``src/mesa/main/extensions.h``. diff --git a/docs/index.rst b/docs/index.rst index a1bd8a7d9ae..4448b7cbe91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -105,9 +105,9 @@ Linux, FreeBSD, and other operating systems. sourcetree utilities helpwanted - devinfo codingstyle submittingpatches + developing-extensions rust releasing release-calendar