Mesa 3D sources

mesa 3D driver/.dir-locals.el

@@ -0,0 +1,18 @@
+((nil . ((show-trailing-whitespace . t)))
+ (prog-mode
+  (indent-tabs-mode . nil)
+  (tab-width . 8)
+  (c-basic-offset . 3)
+  (c-file-style . "stroustrup")
+  (fill-column . 78)
+  (eval . (progn
+	    (c-set-offset 'case-label '0)
+	    (c-set-offset 'innamespace '0)
+	    (c-set-offset 'inline-open '0)))
+  (whitespace-style face indentation)
+  (whitespace-line-column . 79)
+  (eval ignore-errors
+        (require 'whitespace)
+        (whitespace-mode 1)))
+ (makefile-mode (indent-tabs-mode . t))
+ )

mesa 3D driver/.editorconfig

@@ -0,0 +1,44 @@
+# To use this config on you editor, follow the instructions at:
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+tab_width = 8
+
+[*.{c,h,cpp,hpp,cc,hh}]
+indent_style = space
+indent_size = 3
+max_line_length = 78
+
+[{Makefile*,*.mk}]
+indent_style = tab
+
+[{*.py,SCons*}]
+indent_style = space
+indent_size = 4
+
+[*.pl]
+indent_style = space
+indent_size = 4
+
+[*.m4]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2
+
+[*.html]
+indent_style = space
+indent_size = 2
+
+[*.patch]
+trim_trailing_whitespace = false
+
+[{meson.build,meson_options.txt}]
+indent_style = space
+indent_size = 2

mesa 3D driver/.gitignore

@@ -0,0 +1,4 @@
+*.pyc
+*.pyo
+*.out
+build

mesa 3D driver/.mailmap

@@ -0,0 +1,673 @@
+Aapo Tahkola <aet@rasterburn.org> <aapo@aapo-desktop.(none)>
+
+Adam Jackson <ajax@redhat.com> <ajax@benzedrine.nwnk.net>
+Adam Jackson <ajax@redhat.com> <ajax@freedesktop.org>
+
+Adrian Marius Negreanu <adrian.m.negreanu@intel.com> Adrian Negreanu <adrian.m.negreanu@intel.com>
+Adrian Marius Negreanu <adrian.m.negreanu@intel.com> Negreanu Marius Adrian <adrian.m.negreanu@intel.com>
+
+Alan Swanson <reiver@improbability.net> <swanson@ukfsn.org>
+
+Dave Airlie <airlied@redhat.com> <airliedfreedesktop.org>
+Dave Airlie <airlied@redhat.com> airlied <airlied@unused-12-215.bne.redhat.com>
+Dave Airlie <airlied@redhat.com> <airlied@dhcp-1-203.bne.redhat.com>
+Dave Airlie <airlied@redhat.com> <airlied@dhcp-40-204.bne.redhat.com>
+Dave Airlie <airlied@redhat.com> <airlied@gmail.com>
+Dave Airlie <airlied@redhat.com> <airlied@itt42.(none)>
+Dave Airlie <airlied@redhat.com> <airlied@linux.ie>
+Dave Airlie <airlied@redhat.com> <airlied@nx6125b.(none)>
+Dave Airlie <airlied@redhat.com> <airlied@panoply-rh.(none)>
+Dave Airlie <airlied@redhat.com> <airlied@ppcg5.localdomain>
+
+Alan Coopersmith <alan.coopersmith@oracle.com> <alan.coopersmith@sun.com>
+
+Alan Hourihane <alanh@vmware.com> <alanh@tungstengraphics.com>
+Alan Hourihane <alanh@vmware.com> <alanh@fairlite.demon.co.uk>
+Alan Hourihane <alanh@vmware.com> <alanh@jetpack.(none)>
+
+Alexander Monakov <amonakov@gmail.com> <amonakov@ispras.ru>
+
+Alexander von Gluck IV <kallisti5@unixzen.com> Alexander von Gluck <kallisti5@unixzen.com>
+
+Alexandros Frantzis <alexandros.frantzis@collabora.com> <Alexandros.Frantzis@canonical.com>
+
+Alex Corscadden <alexc@vmware.com> <alexc@alexc-dev1.prom.eng.vmware.com>
+Alex Corscadden <alexc@vmware.com> <alexc@alexc-dev1.vmware.com>
+
+Alex Deucher <alexdeucher@gmail.com> <alexander.deucher@amd.com>
+Alex Deucher <alexdeucher@gmail.com> <agd5f@yahoo.com>
+Alex Deucher <alexdeucher@gmail.com> <alex@botch2.com>
+Alex Deucher <alexdeucher@gmail.com> <alex@botch2.(none)>
+Alex Deucher <alexdeucher@gmail.com> <alex@cube.(none)>
+Alex Deucher <alexdeucher@gmail.com> <alex@samba.(none)>
+
+Alyssa Rosenzweig <alyssa.rosenzweig@collabora.com> <alyssa@rosenzweig.io>
+
+Andreas Fänger <a.faenger@e-sign.com> <a.faenger@e-sign.com>
+
+Andreas Hartmetz <ahartmetz@gmail.com> <andreas.hartmetz@kdab.com>
+
+Andre Heider <a.heider@gmail.com>
+Andreas Heider <andreas@heider.io>
+
+Andreas Pokorny <andreas.pokorny@canonical.com> <andreas.pokorny@elektrobit.com>
+
+Andres Gomez <agomez@igalia.com> <tanty@igalia.com>
+
+Andrew Randrianasulu <randrianasulu@gmail.com> <randrik_a@yahoo.com>
+Andrew Randrianasulu <randrianasulu@gmail.com> <randrik@mail.ru>
+
+Andrii Simiklit <andrii.simiklit@globallogic.com> <asimiklit.work@gmail.com>
+
+Anuj Phogat <anuj.phogat@gmail.com> <anuj.phogat@intel.com>
+
+Arthur Huillet <arthur.huillet@free.fr> Arthur HUILLET <arthur.huillet@free.fr>
+
+Axel Davy <axel.davy@ens.fr> <davyaxel0@gmail.com>
+
+Bas Nieuwenhuizen <bas@basnieuwenhuizen.nl> <basni@chromium.org>
+
+Benjamin Franzke <benjaminfranzke@googlemail.com> ben <benjaminfranzke@googlemail.com>
+
+Ben Skeggs <bskeggs@redhat.com> <darktama@beleth.(none)>
+Ben Skeggs <bskeggs@redhat.com> <darktama@iinet.net.au>
+Ben Skeggs <bskeggs@redhat.com> <darktama@nisroch.keine.ath.cx>
+Ben Skeggs <bskeggs@redhat.com> <skeggsb-at-gmail.com>
+Ben Skeggs <bskeggs@redhat.com> <skeggsb@gmail.com>
+Ben Skeggs <bskeggs@redhat.com> <skeggsb@localhost.localdomain>
+Ben Skeggs <bskeggs@redhat.com> <skeggsb@nisroch.keine.ath.cx>
+
+Ben Widawsky <benjamin.widawsky@intel.com> Ben Widawsky <ben@bwidawsk.net>
+
+Blair Sadewitz <blair.sadewitz@gmail.com> Blair Sadewitz <blair.sadewitz.gmail.com>
+
+Boris Brezillon <boris.brezillon@collabora.com> <boris.brezillon@free-electrons.com>
+
+Boris Peterbarg <reist@users.sourceforge.net> reist <reist>
+
+Brian Paul <brianp@vmware.com> Brian <brian.paul@tungstengraphics.com>
+Brian Paul <brianp@vmware.com> <brian.paul@tungstengraphics.com>
+Brian Paul <brianp@vmware.com> <brian.e.paul@gmail.com>
+Brian Paul <brianp@vmware.com> <brianp@kemper.freedesktop.org>
+Brian Paul <brianp@vmware.com> brian <brian@cvp965.(none)>
+Brian Paul <brianp@vmware.com> Brian <brian@i915.localnet.net>
+Brian Paul <brianp@vmware.com> Brian <brian@nostromo.localnet.net>
+Brian Paul <brianp@vmware.com> Brian <brian@poulsbo.localnet.net>
+Brian Paul <brianp@vmware.com> Brian <brian@ps3.localnet.net>
+Brian Paul <brianp@vmware.com> Brian <brianp@vmware.com>
+Brian Paul <brianp@vmware.com> Brian <brian@yutani.localnet.net>
+Brian Paul <brianp@vmware.com> root <brian.paul@tungstengraphics.com>
+Brian Paul <brianp@vmware.com> root <root@i915.localnet.net>
+Brian Paul <brianp@vmware.com> root <root@nostromo.localnet.net>
+Brian Paul <brianp@vmware.com> root <root@i965.localnet.net>
+
+Bruce Cherniak <bruce.cherniak@intel.com>
+
+Bruce Merry <bmerry@users.sourceforge.net> <bmerry@gmail.com>
+
+Carl-Philip Hänsch <cphaensch@googlemail.com>
+Carl-Philip Hänsch <cphaensch@googlemail.com> <s3734770@mail.zih.tu-dresden.de>
+Carl-Philip Hänsch <cphaensch@googlemail.com> <carli@carli-laptop.(none)>
+Carl-Philip Hänsch <cphaensch@googlemail.com> <Carl-Philip.Haensch@mailbox.tu-dresden.de>
+
+Chad Versace <chadversary@chromium.org> <chad@kiwitree.net>
+Chad Versace <chadversary@chromium.org> <chad@chad-versace.us>
+Chad Versace <chadversary@chromium.org> <Chad Versace chad@chad-versace.us>
+Chad Versace <chadversary@chromium.org> <chad.versace@intel.com>
+Chad Versace <chadversary@chromium.org> <chad.versace@linux.intel.com>
+Chad Versace <chadversary@chromium.org> <chadversary@google.com>
+
+Chandu Babu Namburu <chandu@amd.com>
+Chandu Babu Namburu <chandu@amd.com> <mailto:chandu@amd.com>
+
+Chenglei Ren <chenglei.ren@intel.com>
+
+Chia-I Wu <olvaffe@gmail.com> <olv@lunarg.com>
+Chia-I Wu <olvaffe@gmail.com> Chia-Wu <olvaffe@gmail.com>
+
+Chih-Wei Huang <cwhuang@linux.org.tw> Chih-Wei Huang <cwhuang@android-x86.org>
+
+Christian Gmeiner <christian.gmeiner@gmail.com> <christian.GMEINER@bachmann.info>
+
+Christian Inci <chris.bugsfd@broke-the-inter.net> <chris.pcguy.inci@gmail.com>
+
+Christian König <christian.koenig@amd.com> Christian Koenig <christian.koenig@amd.com>
+Christian König <christian.koenig@amd.com> Christian König <christian.koenig at amd.com>
+Christian König <christian.koenig@amd.com> Christian König <deathsimple@vodafone.de>
+
+Christoph Brill <egore911@egore911.de> Christoph Bill <egore@gmx.de>
+Christoph Brill <egore911@egore911.de> <egore@gmx.de>
+
+Christoph Bumiller <christoph.bumiller@speed.at> <e0425955@student.tuwien.ac.at>
+
+Christoph Haag <haagch@frickel.club> <christoph.haag@collabora.com>
+Christoph Haag <haagch@frickel.club> <haagch+mesa@frickel.club>
+Christoph Haag <haagch@frickel.club> <haagch+mesadev@frickel.club>
+
+Christopher James Halse Rogers <christopher.halse.rogers@canonical.com> Christopher James Halse Rogers <raof@ubuntu.com>
+
+Christopher Li <chrisl@vmware.com> Chris Li <chrisl@vmware.com>
+Christopher Li <chrisl@vmware.com> Qicheng Christopher Li <chrisl@vmware.com>
+
+Claudio Ciccani <klan@directfb.org> <klan@users.sf.net>
+Claudio Ciccani <klan@directfb.org> <klan@users.sourceforge.net>
+
+Colin McDonald <cjmmail10-bz@yahoo.co.uk> <cjmcdonald@qinetiq.com>
+
+Connor Abbott <cwabbott0@gmail.com> <connor.w.abbott@intel.com>
+Connor Abbott <cwabbott0@gmail.com> <connor.abbott@intel.com>
+
+Constantine Kharlamov <Hi-Angel@yandex.ru>
+
+Corbin Simpson <MostAwesomeDude@gmail.com> <mostawesomed...@gmail.com>
+Corbin Simpson <MostAwesomeDude@gmail.com> <mostawesomedude@gmail.com>
+
+Courtney Goeltzenleuchter <courtney@lunarg.com> <courtney@LunarG.com>
+
+Craig Stout <cstout@google.com>
+
+Daniel Schürmann <daniel@schuermann.dev> <daniel.schuermann@campus.tu-berlin.de>
+
+Daniel Skinner <sio@users.sourceforge.net> sio <sio>
+
+Daniel Stone <daniels@collabora.com> <daniel@fooishbar.org>
+
+Danylo Piliaiev <dpiliaiev@igalia.com> <danylo.piliaiev@globallogic.com>
+Danylo Piliaiev <dpiliaiev@igalia.com> <danylo.piliaiev@gmail.com>
+
+David Miller <davem@davemloft.net> David S. Miller <davem@davemloft.net>
+David Miller <davem@davemloft.net> Dave Miller <davem@davemloft.net>
+David Miller <davem@davemloft.net> davem69 <davem69>
+
+David Heidelberg <david@ixit.cz> David Heidelberger <david.heidelberger@ixit.cz>
+David Heidelberg <david@ixit.cz> <d.okias@gmail.com>
+
+David Reveman <reveman@chromium.org> <c99drn@cs.umu.se>
+
+Dieter Nützel <Dieter@nuetzel-hh.de> Dieter Nützel <dieter@nuetzel-hh.de>
+
+Dmitry Cherkassov <dcherkassov@gmail.com> Dmitry Cherkasov <dcherkassov@gmail.com>
+
+Dylan Baker <dylanx.c.baker@intel.com> <baker.dylan.c@gmail.com>
+Dylan Baker <dylanx.c.baker@intel.com> <dylan@pnwbakers.com>
+
+Dylan Noblesmith <nobled@dreamwidth.org>
+Dylan Noblesmith <nobled@dreamwidth.org> nobled <nobled2@nobled2-karmic.(none)>
+
+Edward O'Callaghan <funfunctor@folklore1984.net> <eocallaghan@alterapraxis.com>
+
+Eleni Maria Stea <estea@igalia.com> <elene.mst@gmail.com>
+
+Elie Tournier <tournier.elie@gmail.com>
+
+Emeric Grange <emeric.grange@gmail.com> Emeric <emeric.grange@gmail.com>
+
+Emil Velikov <emil.l.velikov@gmail.com> <emil.velikov@collabora.com>
+Emil Velikov <emil.l.velikov@gmail.com> <emil.veliko@collabora.com>
+Emil Velikov <emil.l.velikov@gmail.com> <emil.velikov@collabora.co.uk>
+Emil Velikov <emil.l.velikov@gmail.com> <emil.veliikov@collabora.com>
+Emil Velikov <emil.l.velikov@gmail.com> <emil.velikov@gmail.com>
+Emil Velikov <emil.l.velikov@gmail.com> <emmil.velikov@collabora.com>
+
+Emmanuel Gil Peyrot <linkmauve@linkmauve.fr> <emmanuel.peyrot@collabora.com>
+
+Emmanuel Vadot <manu@FreeBSD.org> Emmanuel <manu@FreeBSD.org>
+
+Eric Anholt <eric@anholt.net> Eric Anholt <anholt@FreeBSD.org>
+
+Eric Engestrom <eric@engestrom.ch> <eric.engestrom@imgtec.com>
+Eric Engestrom <eric@engestrom.ch> <eric.engestrom@intel.com>
+
+Erik Faye-Lund <kusmabite@gmail.com> <erik.faye-lund@collabora.com>
+
+Eugeni Dodonov <eugeni.dodonov@intel.com> <eugeni@mandriva.com>
+
+Fabian Bieler <der.fabe@gmx.net> <fabianbieler@fastmail.fm>
+Fabian Bieler <der.fabe@gmx.net> <&lt;der.fabe@gmx.net&gt>
+
+Feng, Haitao <haitao.feng@intel.com> Haitao Feng <haitao.feng@intel.com>
+
+Francesco Ansanelli <francians@gmail.com>
+
+Frank Binns <frank.binns@imgtec.com> <francisbinns@gmail.com>
+
+Frank Henigman <fjhenigman@google.com> <fjhenigman@chromium.org>
+
+George Sapountzis <gsapountzis@gmail.com> George Sapountzis <gsap7@yahoo.gr>
+
+Gert Wollny <gert.wollny@collabora.com> <gw.fossdev@gmail.com>
+
+Gurchetan Singh <gurchetansingh@chromium.org>
+
+Gwenole Beauchesne <gwenole.beauchesne@intel.com> <gb.devel@gmail.com>
+
+Haihao Xiang <haihao.xiang@intel.com>
+
+Hamish Marson <hmarson@users.sourceforge.net> hmarson <hmarson>
+
+Hans de Goede <hdegoede@redhat.com> Hans de Goede <j.w..r..degoede@hhs.nl>
+
+Harish Krupo <harish.krupo.kps@intel.com> <harishkrupo@gmail.com>
+
+Heinrich Fink <heinrich.fink@daqri.com>
+
+Henri Verbeet <hverbeet@gmail.com>
+
+Homer Hsing <dongsheng.xing@intel.com> <homer.hsing@gmail.com>
+
+Hui Qi Tay <hqtay@vmware.com> <tayhuiqithq@gmail.com>
+
+Iago Toral Quiroga <itoral@igalia.com> Iago Toral <itoral@igalia.com>
+
+Ian Romanick <ian.d.romanick@intel.com> <idr@freedesktop.org>
+Ian Romanick <ian.d.romanick@intel.com> <idr@us.ibm.com>
+
+Icecream95 <ixn@disroot.org> <ixn@keemail.me>
+
+Igor Gnatenko <i.gnatenko.brain@gmail.com> <ignatenko@redhat.com>
+
+Illia Iorin <illia.iorin@globallogic.com> <illia.iorin@gmail.com>
+
+Indrajit Das <indrajit-kumar.das@amd.com> Indrajit Kumar Das <indrajit-kumar.das@amd.com>
+
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob@vmware.com>
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob@aurora.(none)>
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob@aurora.walkyrie.se>
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob@tungstengraphics.com>
+Jakob Bornecrantz <wallbraker@gmail.com> <wallbraker 'at' gmail 'dot' com>
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob.bornecrantz@collabora.com>
+Jakob Bornecrantz <wallbraker@gmail.com> <jakob@collabora.com>
+
+Jakub Bogusz <qboosh@pld-linux.org> <gboosh@pld-linux.org>
+
+James Legg <jlegg@feralinteractive.com> <lankyleggy@gmail.com>
+
+James Xiong <james.xiong@intel.com> Xiong, James <james.xiong@intel.com>
+
+James Zhu <James.Zhu@amd.com>
+
+Jan Beich <jbeich@freebsd.org> <jbeich@FreeBSD.org>
+
+Jan Vesely <jano.vesely@gmail.com> Jan Vesely <jan.vesely@rutgers.edu>
+
+Jan Zielinski <jan.zielinski@intel.com> jzielins <jan.zielinski@intel.com>
+
+Jason Ekstrand <jason@jlekstrand.net> <jason.ekstrand@intel.com>
+
+Jeremy Huddleston <jeremyhu@apple.com>
+Jeremy Huddleston <jeremyhu@apple.com> <jeremyhu@freedesktop.org>
+Jeremy Huddleston <jeremyhu@apple.com> <jeremy@tifa.local>
+Jeremy Huddleston <jeremyhu@apple.com> <jeremy@vincent.local>
+Jeremy Huddleston <jeremyhu@apple.com> <jeremy@yuffie.local>
+
+Jeremy Kolb <jkolb@freedesktop.org> <jkolb@brandeis.edu>
+
+Jerome Glisse <jglisse@redhat.com> <glisse@freedesktop.org>
+Jerome Glisse <jglisse@redhat.com> <glisse@kemper.freedesktop.org>
+Jerome Glisse <jglisse@redhat.com> John Doe <glisse@barney.(none)>
+Jerome Glisse <jglisse@redhat.com> John Doe <glisse@localhost.localdomain>
+
+Jesse Barnes <jesse.barnes@intel.com> <jbarnes@hobbes.lan>
+Jesse Barnes <jesse.barnes@intel.com> <jbarnes@hobbes.(none)>
+Jesse Barnes <jesse.barnes@intel.com> <jbarnes@jbarnes-desktop.localdomain>
+Jesse Barnes <jesse.barnes@intel.com> <jbarnes@jbarnes-t61.(none)>
+Jesse Barnes <jesse.barnes@intel.com> <jbarnes@virtuousgeek.org>
+
+Joakim Sindholt <bacn@zhasha.com> <opensource@zhasha.com>
+Joakim Sindholt <bacn@zhasha.com> <zhasha@gallium-dev.(none)>
+
+Jochen Gerlach <jtg@users.sourceforge.net> jtg <jtg>
+
+Joel Bosveld <joel.bosveld@gmail.com> <Joel.Bosveld@gmail.com>
+
+Jonathan Adamczewski <jadamcze@utas.edu.au> <jadamcze@utas.edu.a>
+
+Jon Turney <jon.turney@dronecode.org.uk> Jon TURNEY <jon.turney@dronecode.org.uk>
+
+José Fonseca <jfonseca@vmware.com> Jose Fonseca <jfonseca@vmware.com>
+José Fonseca <jfonseca@vmware.com> Jose Fonseca <jrfonseca@tungstengraphics.com>
+José Fonseca <jfonseca@vmware.com> <jfonseca@pegasus.(none)>
+José Fonseca <jfonseca@vmware.com> <jfonseca@titan.(none)>
+José Fonseca <jfonseca@vmware.com> <jose.r.fonseca@gmail.com>
+José Fonseca <jfonseca@vmware.com> <jrfonseca@tungstengraphics.com>
+José Fonseca <jfonseca@vmware.com> <j_r_fonseca@yahoo.co.uk>
+
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> Jouk Jansen <jouk@hrem.nano.tudelft.nl>
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> Jouk Jansen <joukj@hrem.stm.tudelft.nl>
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> joukj <joukj@tarantella.(none)>
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> Jouk <joukj@tarantella.nano.tudelft.nl>
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> Jouk <joukj@tarantella.(none)>
+Jouk Jansen <joukj@hrem.nano.tudelft.nl> J.Jansen <joukj@tarantella.nano.tudelft.nl>
+
+Juan Zhao <juan.j.zhao@intel.com> <juan.j.zhao@linux.intel.com>
+
+Julien Cristau <jcristau@debian.org> <julien.cristau@logilab.fr>
+
+Julien Isorce <j.isorce@samsung.com> <julien.isorce@gmail.com>
+Julien Isorce <j.isorce@samsung.com> <jisorce@oblong.com>
+
+Kalyan Kondapally <kalyan.kondapally@intel.com> <kondapallykalyancontribute@gmail.com>
+
+Karl Schultz <karl.w.schultz@gmail.com> Karl Schultze <k.w.schultz@comcast.net>
+Karl Schultz <karl.w.schultz@gmail.com> unknown <kwschult@.na.qualcomm.com>
+Karl Schultz <karl.w.schultz@gmail.com> <k.w.schultz@comcast.net>
+Karl Schultz <karl.w.schultz@gmail.com> <Karl.W.Schultz@gmail.com>
+Karl Schultz <karl.w.schultz@gmail.com> <kschultz@freedesktop.org>
+
+Karol Herbst <kherbst@redhat.com> <git@karolherbst.de>
+Karol Herbst <kherbst@redhat.com> <karolherbst@gmail.com>
+Karol Herbst <kherbst@redhat.com> <nouveau@karolherbst.de>
+
+Keith Harrison <sio2@users.sourceforge.net> sio2 <sio2>
+
+Keith Packard <keithp@keithp.com> <keithp@koto.keithp.com>
+Keith Packard <keithp@keithp.com> <keithp@neko.keithp.com>
+
+Keith Whitwell <keithw@vmware.com> <keith@tungstengraphics.com>
+Keith Whitwell <keithw@vmware.com> keithw <keithw@keithw-laptop.(none)>
+
+Kevin Rogovin <kevin.rogovin@intel.com> <kevin.rogovin@gmail.com>
+
+Kristian Høgsberg <krh@bitplanet.net> <krh@redhat.com>
+Kristian Høgsberg <krh@bitplanet.net> <krh@hinata.boston.redhat.com>
+Kristian Høgsberg <krh@bitplanet.net> <krh@sasori.boston.redhat.com>
+Kristian Høgsberg <krh@bitplanet.net> <krh@temari.boston.redhat.com>
+Kristian Høgsberg <krh@bitplanet.net> <kristian.h.kristensen@intel.com>
+Kristian Høgsberg <krh@bitplanet.net> <hoegsberg@chromium.org>
+Kristian Høgsberg <krh@bitplanet.net> <hoegsberg@google.com>
+Kristian Høgsberg <krh@bitplanet.net> <hoegsberg@gmail.com>
+Kristian Høgsberg <krh@bitplanet.net> <krh@sweater.jf.intel.com>
+Kristian Høgsberg <krh@bitplanet.net> <krh@bitplanet.net>
+Kristian Høgsberg <krh@bitplanet.net> <krh@owl.jf.intel.com>
+
+Krzesimir Nowak <qdlacz@gmail.com> <krzesimir@kinvolk.io>
+
+Li Peng <peng.li@intel.com> <peng.li@linux.intel.com>
+
+Lin Johnson <johnson.lin@intel.com> Johnson Lin <johnson.lin@intel.com>
+
+Lionel Landwerlin <lionel.g.landwerlin@intel.com> <llandwerlin@gmail.com>
+
+Liviu Prodea <liviuprodea@yahoo.com>
+
+Lucas Stach <dev@lynxeye.de> <l.stach@pengutronix.de>
+
+Maarten Lankhorst <maarten.lankhorst@ubuntu.com> <dev@mblankhorst.nl>
+Maarten Lankhorst <maarten.lankhorst@ubuntu.com> <m.b.lankhorst@gmail.com>
+Maarten Lankhorst <maarten.lankhorst@ubuntu.com> <maarten.lankhorst@canonical.com>
+
+Maciej Cencora <m.cencora@gmail.com> <maciej@osiris.(none)>
+
+Marc-André Lureau <marcandre.lureau@gmail.com> <marcandre.lureau@gmail.com>
+Marc-André Lureau <marcandre.lureau@gmail.com> <marcandre.lureau@redhat.com>
+
+Marc Dietrich <marvin24@gmx.de> Marc <marvin24@gmx.de>
+Marc Dietrich <marvin24@gmx.de> marvin24 <marvin24@gmx.de>
+
+Marcin Ślusarz <marcin.slusarz@gmail.com> Marcin Slusarz <marcin.slusarz@gmail.com>
+
+Marek Olšák <maraeo@gmail.com> <marek.olsak@amd.com>
+
+Mario Kleiner <mario.kleiner.de@gmail.com> kleinerm <mario.kleiner@tuebingen.mpg.de>
+Mario Kleiner <mario.kleiner.de@gmail.com> <mario.kleiner@tuebingen.mpg.de>
+
+Mark Menzynski <mmenzyns@redhat.com> mmenzyns <mmenzyns@redhat.com>
+
+Mark Mueller <markkmueller@gmail.com> <MarkKMueller@gmail.com>
+
+Marta Lofstedt <marta.lofstedt@intel.com> <marta.lofstedt@linux.intel.com>
+
+Martin Peres <martin.peres@linux.intel.com> <martin.peres@labri.fr>
+
+Mathias Fröhlich <mathias.froehlich@gmx.net> Mathias Froehlich <Mathias.Froehlich@gmx.net>
+Mathias Fröhlich <mathias.froehlich@gmx.net> Mathias Froehlich <Mathias.Froehlich@web.de>
+Mathias Fröhlich <mathias.froehlich@gmx.net> Mathias Frohlich <M.Froehlich@science-computing.de>
+Mathias Fröhlich <mathias.froehlich@gmx.net> <frohlich8@users.sourceforge.net>
+Mathias Fröhlich <mathias.froehlich@gmx.net> <Mathias.Froehlich@gmx.net>
+Mathias Fröhlich <mathias.froehlich@gmx.net> <Mathias.Froehlich@web.de>
+Mathias Fröhlich <mathias.froehlich@gmx.net> M.Froehlich@science-computing.de <M.Froehlich@science-computing.de>
+
+Matthias Groß <grmat@sub.red>
+
+Matthias Hopf <mhopf@suse.de> Mathias Hopf <mhopf@suse.de>
+
+Matthias Lorenz <oschowa@web.de> Oschowa <oschowa@web.de>
+
+Matthew W. S. Bell <matthew@bells23.org.uk> Matthew Bell <matthew@bells23.org.uk>
+
+Maxence Le Doré <maxence.ledore@gmail.com> Maxence Le Dore <maxence.ledore@gmail.com>
+
+Maya Rashish <coypu@sdf.org> coypu <coypu@sdf.org>
+
+Micah Fedke <micah.fedke@collabora.co.uk> <M.Fedke@Astronautics.com>
+
+Michal Krol <michal@vmware.com> <michal@tungstengraphics.com>
+Michal Krol <michal@vmware.com> Michal Krol <michal@ubuntu-vbox.(none)>
+Michal Krol <michal@vmware.com> Michal Krol <mjkrol@gmail.org>
+Michal Krol <michal@vmware.com> michal <michal@capacitor.(none)>
+Michal Krol <michal@vmware.com> michal <michal@michal-laptop.(none)>
+Michal Krol <michal@vmware.com> michal <michal@quad.(none)>
+Michal Krol <michal@vmware.com> michal <michal@transistor.(none)>
+Michal Krol <michal@vmware.com> Michal <michal@tungstengraphics.com>
+Michal Krol <michal@vmware.com> michal <michal@wmvare.com>
+
+Michel Dänzer <michel@daenzer.net> <michel.daenzer@amd.com>
+Michel Dänzer <michel@daenzer.net> <daenzer@vmware.com>
+Michel Dänzer <michel@daenzer.net> <michel@tungstengraphics.com>
+Michel Dänzer <michel@daenzer.net> Michel Daenzer <michel.daenzer@amd.com>
+Michel Dänzer <michel@daenzer.net> Michel Daenzer <daenzer@localhost.(none)>
+Michel Dänzer <michel@daenzer.net> <mdaenzer@redhat.com>
+
+Mike Kaplinskiy <mike.kaplinskiy@gmail.com> Mike Kaplinksiy <mike.kaplinskiy@gmail.com>
+Mike Kaplinskiy <mike.kaplinskiy@gmail.com> <mike.kaplinskiy@gmai.com>
+
+Mike Stroyan <mike@lunarg.com> <mike@LunarG.com>
+
+Mun Gwan-gyeong <elongbug@gmail.com> Gwan-gyeong Mun <elongbug@gmail.com>
+
+Neha Bhende <bhenden@vmware.com> <nbhende@vmware.com>
+
+Neil Roberts <nroberts@igalia.com> <neil@linux.intel.com>
+
+Nian Wu <nian.wu@intel.com>
+Nian Wu <nian.wu@intel.com> <nian@graphics.(none)>
+Nian Wu <nian.wu@intel.com> <nian@tinderbox.sh.intel.com>
+
+Nicholas Bishop <nbishop@neverware.com> <nicholasbishop@gmail.com>
+
+Nick Bowler <nbowler@draconx.ca>
+
+Nick Sarnie <commendsarnex@gmail.com>
+
+Nicolai Hähnle <nicolai.haehnle@amd.com>
+Nicolai Hähnle <nicolai.haehnle@amd.com> <nhaehnle@gmail.com>
+Nicolai Hähnle <nicolai.haehnle@amd.com> <prefect_@gmx.net>
+Nicolai Hähnle <nicolai.haehnle@amd.com> <prefect@upb.de>
+
+Nigel Stewart <nigels@users.sourceforge.net> <nigels@sourceforge.net>
+Nigel Stewart <nigels@users.sourceforge.net> <nstewart@nvidia.com>
+
+nobled <nobled@dreamwidth.org> <nobled2@nobled2-karmic.(none)>
+
+Oliver McFadden <oliver.mcfadden@linux.intel.com> <z3ro.geek@gmail.com>
+
+Owain Ainsworth <zerooa@googlemail.com> Owain G. Ainsworth <oga@openbsd.org>
+
+Owen W. Taylor <otaylor@fishsoup.net> Owen Taylor <otaylor@snell.localdomain>
+
+Patrice Mandin <patmandin@gmail.com> <patrice@manoir.racoon.city>
+Patrice Mandin <patmandin@gmail.com> <pmandin@caramail.com>
+Patrice Mandin <patmandin@gmail.com> <pmandin@freedesktop.org>
+
+Pauli Nieminen <pauli.nieminen@linux.intel.com> <suokkos@gmail.com>
+
+Paulo Zanoni <paulo.r.zanoni@intel.com> Paulo Zanoni <pzanoni@mandriva.com>
+
+Paul Seidler <sepek@exherbo.org> Paul Seidler <pl.seidler@googlemail.com>
+
+Pekka Paalanen <pekka.paalanen@collabora.co.uk> <ppaalanen@gmail.com>
+Pekka Paalanen <pekka.paalanen@collabora.co.uk> <pq@iki.fi>
+
+Peter Hutterer <peter.hutterer@who-t.net> <peter@cs.unisa.edu.au>
+
+Philipp Zabel <p.zabel@pengutronix.de> <philipp.zabel@gmail.com>
+
+Pierre-Eric Pelloux-Prayer <pelloux@gmail.com> <pelloux@gmail.com>
+Pierre-Eric Pelloux-Prayer <pelloux@gmail.com> <pierre-eric.pelloux-prayer@amd.com>
+
+Pierre Willenbrock <pierre@pirsoft.de> Pierre Willenbrok <pierre@pirsoft.de>
+
+Plamena Manolova <plamena.manolova@intel.com> <plamena.n.manolova@gmail.com>
+
+Qiang Yu <yuq825@gmail.com> <Qiang.Yu@amd.com>
+
+Quentin Glidic <sardemff7+git@sardemff7.net> <sardemff7@sardemff7.net>
+
+Randy Xu <randy.xu@intel.com>
+
+RALOVICH, Kristóf <tade60@freemail.hu> <kristof.ralovich@gmail.com>
+
+Renato Caldas <seventhguardian@gmail.com>
+
+Richard Li <richardradeon@gmail.com> <RichardZ.Li@amd.com>
+# The next ones are not 100% sure
+Richard Li <richardradeon@gmail.com> richard <richard@richard-desktop3.(none)>
+Richard Li <richardradeon@gmail.com> richard <richard@richard-desktop.(none)>
+Richard Li <richardradeon@gmail.com> root <root@richard-desktop.(none)>
+
+Richard Sandiford <rsandifo@linux.vnet.ibm.com> <r.sandiford@uk.ibm.com>
+
+Rob Clark <robclark@freedesktop.org> <Rob Clark robdclark@freedesktop.org>
+Rob Clark <robclark@freedesktop.org> <robdclark@gmail.com>
+Rob Clark <robclark@freedesktop.org> <robdclark@chromium.org>
+
+Robert Bragg <robert@sixbynine.org> <robert@linux.intel.com>
+
+Robert Ellison <papillo@vmware.com> <papillo@i965-laptop.(none)>
+Robert Ellison <papillo@vmware.com> <papillo@tungstengraphics.com>
+
+Robert Hooker <sarvatt@ubuntu.com> <robert.hooker@canonical.com>
+
+Rodrigo Vivi <rodrigo.vivi@intel.com> <rodrigo.vivi@gmail.com>
+
+Roland Scheidegger <sroland@vmware.com> <rscheidegger@gmx.ch>
+Roland Scheidegger <sroland@vmware.com> <sroland@tungstengraphics.com>
+
+Roy Spliet <rspliet@eclipso.eu> <r.spliet@student.tudelft.nl>
+
+Rune Petersen <rune@megahurts.dk> Rune Peterson <rune@megahurts.dk>
+
+Ryan Houdek <sonicadvance1@gmail.com> <Sonicadvance1@gmail.com>
+
+Sam Hocevar <sam@hocevar.net> Sam Hocevar <sam@zoy.org>
+
+Samuel Iglesias Gonsálvez <siglesias@igalia.com> Samuel Iglesias Gonsalvez <siglesias@igalia.com>
+
+Samuel Li <samuel.li@amd.com> <Samuel.Li@amd.com>
+
+Satyeshwar Singh <satyeshwar.singh@intel.com> Singh, Satyeshwar <satyeshwar.singh@intel.com>
+
+Sean D'Epagnier <sean@depagnier.com> <geckosenator@freedesktop.org>
+
+Serge Martin <edb+mesa@sigluy.net> Serge Martin (EdB) <edb+mesa@sigluy.net>
+Serge Martin <edb+mesa@sigluy.net> EdB <edb+mesa@sigluy.net>
+
+Sergii Romantsov <sergii.romantsov@globallogic.com> <sergii.romantsov@gmail.com>
+
+Sinclair Yeh <syeh@vmware.com> <sinclair.yeh@intel.com>
+
+Sonny Jiang <sonny.jiang@amd.com>
+
+Stefan Brüns <stefan.bruens@rwth-aachen.de> <Stefan.Bruens@rwth-aachen.de>
+
+Steinar H. Gunderson <sgunderson@bigfoot.com> <sesse@google.com>
+Steinar H. Gunderson <sgunderson@bigfoot.com> <steinar+mesa@gunderson.no>
+
+Stéphane Marchesin <marcheu@chromium.org> Stephane Marchesin <marchesin@icps.u-strasbg.fr>
+Stéphane Marchesin <marcheu@chromium.org> Stephane Marchesin <stephane.marchesin@gmail.com>
+
+Suresh Guttula <suresh.guttula@amd.com>
+Suresh Guttula <suresh.guttula@amd.com> <Suresh.Guttula@amd.com>
+
+Sven M. Hallberg <pesco@users.sourceforge.net> pesco <pesco>
+
+Tapani Pälli <tapani.palli@intel.com> <tapani.palli@gmail.com>
+Tapani Pälli <tapani.palli@intel.com> Tapani <tapani.palli@intel.com>
+
+Thierry Reding <treding@nvidia.com> <thierry@gilfi.de>
+Thierry Reding <treding@nvidia.com> <thierry.reding@avionic-design.de>
+Thierry Reding <treding@nvidia.com> <thierry.reding@gmail.com>
+
+Thierry Vignaud <thierry.vignaud@gmail.com> <tvignaud@mandriva.com>
+
+Thomas Balling Sørensen <tball@io.dk> <tball@tball-laptop.(none)>
+
+Thomas Hellstrom <thellstrom@vmware.com> Thomas <thellstrom@vmware.com>
+Thomas Hellstrom <thellstrom@vmware.com> Thomas Hellstrom <thellstrom-at-vmware-dot-com>
+Thomas Hellstrom <thellstrom@vmware.com> Thomas Hellstrom <thomas-at-tungstengraphics-dot-com>
+Thomas Hellstrom <thellstrom@vmware.com> Thomas Hellstrom <thomas@tungstengraphics.com>
+Thomas Hellstrom <thellstrom@vmware.com> Thomas Hellström <thomas@tungstengraphics.com>
+
+Thomas Tanner <tanner@gmx.net> tanner <tanner>
+
+Tilman Sauerbeck <tilman@code-monkey.de> <tilman@freedesktop.org>
+
+Tim Wiederhake <twied@gmx.net>
+
+Timo Aaltonen <tjaalton@debian.org> <tjaalton@cc.hut.fi>
+
+Timothy Arceri <tarceri@itsqueeze.com> <tarceri@localhost.localdomain>
+Timothy Arceri <tarceri@itsqueeze.com> <timothy.arceri@collabora.com>
+Timothy Arceri <tarceri@itsqueeze.com> <t_arceri@yahoo.com.au>
+Timothy Arceri <tarceri@itsqueeze.com> Timothy <t_arceri@yahoo.com.au>
+
+Tom Fogal <tfogal@alumni.unh.edu> <tfogal@sci.utah.edu>
+
+Tom Stellard <thomas.stellard@amd.com> <tstellar@gmail.com>
+Tom Stellard <thomas.stellard@amd.com> Thomas Stellard <tom.stellard@amd.com>
+Tom Stellard <thomas.stellard@amd.com> <tstellar@redhat.com>
+
+Tomasz Figa <tfiga@chromium.org> <tomasz.figa@gmail.com>
+
+Tomeu Vizoso <tomeu.vizoso@collabora.com> <tomeu@tomeuvizoso.net>
+
+Topi Pohjolainen <topi.pohjolainen@intel.com> <topi.pohjolainen@gmail.com>
+
+Tormod Volden <debian.tormod@gmail.com> <lists.tormod@gmail.com>
+
+Török Edwin <edwin+mesa@etorok.net> Török Edvin <edwintorok@gmail.com>
+Török Edwin <edwin+mesa@etorok.net> <edwintorok@gmail.com>
+
+Vadym Shovkoplias <vadym.shovkoplias@globallogic.com>
+Vadym Shovkoplias <vadym.shovkoplias@globallogic.com> <vadim.shovkoplias@gmail.com>
+
+Varad Gautam <varad.gautam@collabora.com> <varadgautam@gmail.com>
+
+Ville Syrjälä <ville.syrjala@linux.intel.com> Ville Syrjala <syrjala@freedesktop.org>
+Ville Syrjälä <ville.syrjala@linux.intel.com> Ville Syrjala <syrjala@sci.fi>
+
+Vincent Lejeune <vljn@ovi.com> <peluche.canard@gmail.com>
+
+Vinson Lee <vlee@freedesktop.org> <vlee@vmware.com>
+
+Vivek Kasireddy <vivek.kasireddy@intel.com>
+
+Yaakov Selkowitz <yselkowi@redhat.com> <yselkowitz@users.sourceforge.net>
+
+Yogesh Mohan Marimuthu <yogesh.mohanmarimuthu@amd.com> Yogesh mohan marimuthu <yogesh.mohanmarimuthu@amd.com>
+
+Wladimir J. van der Laan <laanwj@gmail.com>
+
+Xavier Bouchoux <xavierb@gmail.com>
+
+Zhaowei Yuan <zhaowei.yuan@samsung.com>
+
+Zhenyu Wang <zhenyuw@linux.intel.com> Wang Zhenyu <zhenyu.z.wang@intel.com>
+
+Zhongmin Wu <zhongmin.wu@intel.com>
+
+Zack Rusin <zackr@vmware.com> <zack@kde.org>
+Zack Rusin <zackr@vmware.com> <zack@pixel.(none)>
+Zack Rusin <zackr@vmware.com> <zack@tungstengraphics.com>
+
+Zhang <zxpmyth@yahoo.com.cn> zhang <zxpmyth@yahoo.com.cn>

mesa 3D driver/.travis.yml

@@ -0,0 +1,52 @@
+language: c
+
+os: osx
+
+cache:
+  ccache: true
+
+env:
+  global:
+    - PKG_CONFIG_PATH=""
+
+matrix:
+  include:
+    - env:
+      - BUILD=meson
+
+before_install:
+  - HOMEBREW_NO_AUTO_UPDATE=1 brew install expat gettext
+  - if test "x$BUILD" = xmeson; then
+      HOMEBREW_NO_AUTO_UPDATE=1 brew install ninja;
+    fi
+
+  # Set PATH for homebrew pip3 installs
+  - PYTHON_VERSION=$(python3 -V | awk '{print $2}' | cut -d. -f1-2)
+  - PATH="$HOME/Library/Python/$PYTHON_VERSION/bin:${PATH}"
+  # Set PKG_CONFIG_PATH for keg-only expat
+  - PKG_CONFIG_PATH="/usr/local/opt/expat/lib/pkgconfig:${PKG_CONFIG_PATH}"
+  # Set PATH for keg-only gettext
+  - PATH="/usr/local/opt/gettext/bin:${PATH}"
+
+  # Install xquartz for prereqs ...
+  - XQUARTZ_VERSION="2.7.11"
+  - wget -nv https://dl.bintray.com/xquartz/downloads/XQuartz-${XQUARTZ_VERSION}.dmg
+  - hdiutil attach XQuartz-${XQUARTZ_VERSION}.dmg
+  - sudo installer -pkg /Volumes/XQuartz-${XQUARTZ_VERSION}/XQuartz.pkg -target /
+  - hdiutil detach /Volumes/XQuartz-${XQUARTZ_VERSION}
+  # ... and set paths
+  - PKG_CONFIG_PATH="/opt/X11/share/pkgconfig:/opt/X11/lib/pkgconfig:${PKG_CONFIG_PATH}"
+
+install:
+  - if test "x$BUILD" = xmeson; then
+      pip3 install --user meson;
+      pip3 install --user mako;
+    fi
+
+script:
+  - if test "x$BUILD" = xmeson; then
+      meson _build -Dbuild-tests=true;
+      ninja -C _build || travis_terminate 1;
+      ninja -C _build test || travis_terminate 1;
+      ninja -C _build install || travis_terminate 1;
+    fi

mesa 3D driver/Android.common.mk

@@ -0,0 +1,133 @@
+# Mesa 3-D graphics library
+#
+# Copyright (C) 2010-2011 Chia-I Wu <olvaffe@gmail.com>
+# Copyright (C) 2010-2011 LunarG Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+ifeq ($(LOCAL_IS_HOST_MODULE),true)
+LOCAL_CFLAGS += -D_GNU_SOURCE
+endif
+
+LOCAL_C_INCLUDES += \
+	$(MESA_TOP)/src \
+	$(MESA_TOP)/include
+
+MESA_VERSION := $(shell cat $(MESA_TOP)/VERSION)
+LOCAL_CFLAGS += \
+	-Wno-error \
+	-Werror=incompatible-pointer-types \
+	-Wno-unused-parameter \
+	-Wno-pointer-arith \
+	-Wno-missing-field-initializers \
+	-Wno-initializer-overrides \
+	-Wno-mismatched-tags \
+	-DPACKAGE_VERSION=\"$(MESA_VERSION)\" \
+	-DPACKAGE_BUGREPORT=\"https://gitlab.freedesktop.org/mesa/mesa/-/issues\"
+
+# XXX: The following __STDC_*_MACROS defines should not be needed.
+# It's likely due to a bug elsewhere, but let's temporarily add them
+# here to fix the radeonsi build.
+LOCAL_CFLAGS += \
+	-DANDROID_API_LEVEL=$(PLATFORM_SDK_VERSION) \
+	-DENABLE_SHADER_CACHE \
+	-D__STDC_CONSTANT_MACROS \
+	-D__STDC_LIMIT_MACROS \
+	-DHAVE___BUILTIN_EXPECT \
+	-DHAVE___BUILTIN_FFS \
+	-DHAVE___BUILTIN_FFSLL \
+	-DHAVE_DLFCN_H \
+	-DHAVE_FUNC_ATTRIBUTE_FLATTEN \
+	-DHAVE_FUNC_ATTRIBUTE_UNUSED \
+	-DHAVE_FUNC_ATTRIBUTE_FORMAT \
+	-DHAVE_FUNC_ATTRIBUTE_PACKED \
+	-DHAVE_FUNC_ATTRIBUTE_ALIAS \
+	-DHAVE_FUNC_ATTRIBUTE_NORETURN \
+	-DHAVE_FUNC_ATTRIBUTE_RETURNS_NONNULL \
+	-DHAVE_FUNC_ATTRIBUTE_WARN_UNUSED_RESULT \
+	-DHAVE___BUILTIN_CTZ \
+	-DHAVE___BUILTIN_POPCOUNT \
+	-DHAVE___BUILTIN_POPCOUNTLL \
+	-DHAVE___BUILTIN_CLZ \
+	-DHAVE___BUILTIN_CLZLL \
+	-DHAVE___BUILTIN_UNREACHABLE \
+	-DHAVE_PTHREAD=1 \
+	-DHAVE_DLADDR \
+	-DHAVE_DL_ITERATE_PHDR \
+	-DHAVE_LINUX_FUTEX_H \
+	-DHAVE_ENDIAN_H \
+	-DHAVE_ZLIB \
+	-DHAVE_COMPRESSION \
+	-DMAJOR_IN_SYSMACROS \
+	-DVK_USE_PLATFORM_ANDROID_KHR \
+	-fvisibility=hidden \
+	-fno-math-errno \
+	-fno-trapping-math \
+	-Wno-sign-compare
+
+LOCAL_CPPFLAGS += \
+	-D__STDC_CONSTANT_MACROS \
+	-D__STDC_FORMAT_MACROS \
+	-D__STDC_LIMIT_MACROS \
+	-Wno-error=non-virtual-dtor \
+	-Wno-non-virtual-dtor
+
+# mesa requires at least c99 compiler
+LOCAL_CONLYFLAGS += \
+	-std=c99
+
+# c11 timespec_get is part of bionic as well
+# https://android-review.googlesource.com/c/718518
+# This means releases from P and earlier won't need this
+ifeq ($(filter 5 6 7 8 9, $(MESA_ANDROID_MAJOR_VERSION)),)
+LOCAL_CFLAGS += -DHAVE_TIMESPEC_GET
+endif
+
+# Android's libc began supporting shm in Oreo
+ifeq ($(shell test $(PLATFORM_SDK_VERSION) -ge 26 && echo true),true)
+LOCAL_CFLAGS += -DHAVE_SYS_SHM_H
+endif
+
+ifeq ($(TARGET_ARCH),x86)
+LOCAL_CFLAGS += \
+	-DUSE_X86_ASM
+endif
+ifeq ($(ARCH_ARM_HAVE_NEON),true)
+LOCAL_CFLAGS_arm += -DUSE_ARM_ASM
+endif
+LOCAL_CFLAGS_arm64 += -DUSE_AARCH64_ASM
+
+ifneq ($(LOCAL_IS_HOST_MODULE),true)
+LOCAL_CFLAGS += -DHAVE_LIBDRM
+LOCAL_SHARED_LIBRARIES += libdrm
+endif
+
+LOCAL_CFLAGS_32 += -DDEFAULT_DRIVER_DIR=\"/vendor/lib/$(MESA_DRI_MODULE_REL_PATH)\"
+LOCAL_CFLAGS_64 += -DDEFAULT_DRIVER_DIR=\"/vendor/lib64/$(MESA_DRI_MODULE_REL_PATH)\"
+LOCAL_PROPRIETARY_MODULE := true
+
+# uncomment to keep the debug symbols
+#LOCAL_STRIP_MODULE := false
+
+ifeq ($(strip $(LOCAL_MODULE_TAGS)),)
+LOCAL_MODULE_TAGS := optional
+endif
+
+# Quiet down the build system and remove any .h files from the sources
+LOCAL_SRC_FILES := $(patsubst %.h, , $(LOCAL_SRC_FILES))

mesa 3D driver/Android.mk

@@ -0,0 +1,124 @@
+# Mesa 3-D graphics library
+#
+# Copyright (C) 2010-2011 Chia-I Wu <olvaffe@gmail.com>
+# Copyright (C) 2010-2011 LunarG Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+# BOARD_GPU_DRIVERS should be defined.  The valid values are
+#
+#   classic drivers: i915 i965
+#   gallium drivers: swrast freedreno i915g nouveau kmsro r300g r600g radeonsi vc4 virgl vmwgfx etnaviv iris lima panfrost
+#
+# The main target is libGLES_mesa.  For each classic driver enabled, a DRI
+# module will also be built.  DRI modules will be loaded by libGLES_mesa.
+
+MESA_TOP := $(call my-dir)
+
+MESA_ANDROID_MAJOR_VERSION := $(word 1, $(subst ., , $(PLATFORM_VERSION)))
+ifneq ($(filter 2 4, $(MESA_ANDROID_MAJOR_VERSION)),)
+$(error "Android 4.4 and earlier not supported")
+endif
+
+MESA_DRI_MODULE_REL_PATH := dri
+MESA_DRI_MODULE_PATH := $(TARGET_OUT_SHARED_LIBRARIES)/$(MESA_DRI_MODULE_REL_PATH)
+MESA_DRI_MODULE_UNSTRIPPED_PATH := $(TARGET_OUT_SHARED_LIBRARIES_UNSTRIPPED)/$(MESA_DRI_MODULE_REL_PATH)
+MESA_DRI_LDFLAGS := -Wl,--build-id=sha1
+
+MESA_COMMON_MK := $(MESA_TOP)/Android.common.mk
+MESA_PYTHON2 := python
+MESA_PYTHON3 := python3
+ifeq ($(filter 5 6 7 8 9 10, $(MESA_ANDROID_MAJOR_VERSION)),)
+MESA_LEX     := M4=$(M4) $(LEX)
+else
+MESA_LEX     := $(LEX)
+endif
+
+# Lists to convert driver names to boolean variables
+# in form of <driver name>.<boolean make variable>
+classic_drivers := i915.HAVE_I915_DRI i965.HAVE_I965_DRI
+gallium_drivers := \
+	swrast.HAVE_GALLIUM_SOFTPIPE \
+	freedreno.HAVE_GALLIUM_FREEDRENO \
+	i915g.HAVE_GALLIUM_I915 \
+	nouveau.HAVE_GALLIUM_NOUVEAU \
+	kmsro.HAVE_GALLIUM_KMSRO \
+	r300g.HAVE_GALLIUM_R300 \
+	r600g.HAVE_GALLIUM_R600 \
+	radeonsi.HAVE_GALLIUM_RADEONSI \
+	vmwgfx.HAVE_GALLIUM_VMWGFX \
+	vc4.HAVE_GALLIUM_VC4 \
+	virgl.HAVE_GALLIUM_VIRGL \
+	etnaviv.HAVE_GALLIUM_ETNAVIV \
+	iris.HAVE_GALLIUM_IRIS \
+	lima.HAVE_GALLIUM_LIMA \
+	panfrost.HAVE_GALLIUM_PANFROST
+
+ifeq ($(BOARD_GPU_DRIVERS),all)
+MESA_BUILD_CLASSIC := $(filter HAVE_%, $(subst ., , $(classic_drivers)))
+MESA_BUILD_GALLIUM := $(filter HAVE_%, $(subst ., , $(gallium_drivers)))
+else
+# Warn if we have any invalid driver names
+$(foreach d, $(BOARD_GPU_DRIVERS), \
+	$(if $(findstring $(d).,$(classic_drivers) $(gallium_drivers)), \
+		, \
+		$(warning invalid GPU driver: $(d)) \
+	) \
+)
+MESA_BUILD_CLASSIC := $(strip $(foreach d, $(BOARD_GPU_DRIVERS), $(patsubst $(d).%,%, $(filter $(d).%, $(classic_drivers)))))
+MESA_BUILD_GALLIUM := $(strip $(foreach d, $(BOARD_GPU_DRIVERS), $(patsubst $(d).%,%, $(filter $(d).%, $(gallium_drivers)))))
+endif
+ifeq ($(filter x86%,$(TARGET_ARCH)),)
+	MESA_BUILD_CLASSIC :=
+endif
+
+$(foreach d, $(MESA_BUILD_CLASSIC) $(MESA_BUILD_GALLIUM), $(eval $(d) := true))
+
+ifneq ($(filter true, $(HAVE_GALLIUM_RADEONSI)),)
+MESA_ENABLE_LLVM := true
+endif
+
+define mesa-build-with-llvm
+  $(if $(filter $(MESA_ANDROID_MAJOR_VERSION), 4 5 6 7), \
+    $(warning Unsupported LLVM version in Android $(MESA_ANDROID_MAJOR_VERSION)),) \
+  $(eval LOCAL_CFLAGS += -DLLVM_AVAILABLE -DDRAW_LLVM_AVAILABLE -DLLVM_IS_SHARED=1 -DMESA_LLVM_VERSION_STRING=\"3.9\") \
+  $(eval LOCAL_SHARED_LIBRARIES += libLLVM)
+endef
+
+# add subdirectories
+SUBDIRS := \
+	src/etnaviv \
+	src/freedreno \
+	src/gbm \
+	src/loader \
+	src/mapi \
+	src/compiler \
+	src/mesa \
+	src/util \
+	src/egl \
+	src/amd \
+	src/broadcom \
+	src/intel \
+	src/mesa/drivers/dri \
+	src/vulkan \
+	src/panfrost \
+
+INC_DIRS := $(call all-named-subdir-makefiles,$(SUBDIRS))
+INC_DIRS += $(call all-named-subdir-makefiles,src/gallium)
+include $(INC_DIRS)

mesa 3D driver/CleanSpec.mk

@@ -0,0 +1,16 @@
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/obj/STATIC_LIBRARIES/libmesa_*_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/obj/SHARED_LIBRARIES/i9*5_dri_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/obj/SHARED_LIBRARIES/libglapi_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/obj/SHARED_LIBRARIES/libGLES_mesa_intermediates)
+$(call add-clean-step, rm -rf $(OUT_DIR)/host/$(HOST_OS)-$(HOST_ARCH)/obj/EXECUTABLES/mesa_*_intermediates)
+$(call add-clean-step, rm -rf $(OUT_DIR)/host/$(HOST_OS)-$(HOST_ARCH)/obj/EXECUTABLES/glsl_compiler_intermediates)
+$(call add-clean-step, rm -rf $(OUT_DIR)/host/$(HOST_OS)-$(HOST_ARCH)/obj/STATIC_LIBRARIES/libmesa_glsl_utils_intermediates)
+
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/*/STATIC_LIBRARIES/libmesa_*_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/*/SHARED_LIBRARIES/i9?5_dri_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/*/SHARED_LIBRARIES/libglapi_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/*/SHARED_LIBRARIES/libGLES_mesa_intermediates)
+$(call add-clean-step, rm -rf $(HOST_OUT)/*/EXECUTABLES/mesa_*_intermediates)
+$(call add-clean-step, rm -rf $(HOST_OUT)/*/EXECUTABLES/glsl_compiler_intermediates)
+$(call add-clean-step, rm -rf $(HOST_OUT)/*/STATIC_LIBRARIES/libmesa_*_intermediates)
+$(call add-clean-step, rm -rf $(PRODUCT_OUT)/*/SHARED_LIBRARIES/*_dri_intermediates)

mesa 3D driver/README.rst

@@ -0,0 +1,59 @@
+`Mesa <https://mesa3d.org>`_ - The 3D Graphics Library
+======================================================
+
+
+Source
+------
+
+This repository lives at https://gitlab.freedesktop.org/mesa/mesa.
+Other repositories are likely forks, and code found there is not supported.
+
+
+Build & install
+---------------
+
+You can find more information in our documentation (`docs/install.rst
+<https://mesa3d.org/install.html>`_), but the recommended way is to use
+Meson (`docs/meson.rst <https://mesa3d.org/meson.html>`_):
+
+.. code-block:: sh
+
+  $ mkdir build
+  $ cd build
+  $ meson ..
+  $ sudo ninja install
+
+
+Support
+-------
+
+Many Mesa devs hang on IRC; if you're not sure which channel is
+appropriate, you should ask your question on `Freenode's #dri-devel
+<irc://chat.freenode.net#dri-devel>`_, someone will redirect you if
+necessary.
+Remember that not everyone is in the same timezone as you, so it might
+take a while before someone qualified sees your question.
+To figure out who you're talking to, or which nick to ping for your
+question, check out `Who's Who on IRC
+<https://dri.freedesktop.org/wiki/WhosWho/>`_.
+
+The next best option is to ask your question in an email to the
+mailing lists: `mesa-dev\@lists.freedesktop.org
+<https://lists.freedesktop.org/mailman/listinfo/mesa-dev>`_
+
+
+Bug reports
+-----------
+
+If you think something isn't working properly, please file a bug report
+(`docs/bugs.rst <https://mesa3d.org/bugs.html>`_).
+
+
+Contributing
+------------
+
+Contributions are welcome, and step-by-step instructions can be found in our
+documentation (`docs/submittingpatches.rst
+<https://mesa3d.org/submittingpatches.html>`_).
+
+Note that Mesa uses gitlab for patches submission, review and discussions.

mesa 3D driver/REVIEWERS

@@ -0,0 +1,114 @@
+Overview:
+
+	This file is similar in syntax (or more precisly a subset) of what is
+	used by the MAINTAINERS file in the linux kernel.
+	The purpose is not exactly the same the MAINTAINERS file in the linux
+	kernel, as there are not official/formal maintainers of different
+	subsystems in mesa, but is meant to give an idea of who to CC for
+	various patches for review.
+
+Descriptions of section entries:
+
+	R: Designated reviewer: FullName <address@domain>
+	   These reviewers should be CCed on patches.
+	F: Files and directories with wildcard patterns.
+	   A trailing slash includes all files and subdirectory files.
+	   F:	drivers/net/	all files in and below drivers/net
+	   F:	drivers/net/*	all files in drivers/net, but not below
+	   F:	*/net/*		all files in "any top level directory"/net
+	   One pattern per line.  Multiple F: lines acceptable.
+
+Maintainers List (try to look for most precise areas first)
+
+Note: this is an opt-in system, I have not tried to add anyone who hasn't
+either asked me or sent a patch to add themselves.
+
+		-----------------------------------
+
+NIR
+R:	Jason Ekstrand <jason@jlekstrand.net>
+F:	src/compiler/nir/
+
+DOCUMENTATION
+R: Emil Velikov <emil.l.velikov@gmail.com>
+R: Eric Engestrom <eric@engestrom.ch>
+F: docs/
+
+COMPATIBILITY HEADERS
+R: Emil Velikov <emil.l.velikov@gmail.com>
+F: include/c99*
+
+DRI LOADER
+R: Emil Velikov <emil.l.velikov@gmail.com>
+F: src/loader/
+
+EGL
+R: Eric Engestrom <eric@engestrom.ch>
+R: Emil Velikov <emil.l.velikov@gmail.com>
+F: src/egl/
+F: include/EGL/
+
+HAIKU
+R: Alexander von Gluck IV <kallisti5@unixzen.com>
+F: include/HaikuGL/
+F: src/egl/drivers/haiku/
+F: src/gallium/state_trackers/hgl/
+F: src/gallium/targets/haiku-softpipe/
+F: src/gallium/winsys/sw/hgl/
+F: src/hgl/
+
+GALLIUM LOADER
+R: Emil Velikov <emil.l.velikov@gmail.com>
+F: src/gallium/auxiliary/pipe-loader/
+F: src/gallium/auxiliary/target-helpers/
+
+GALLIUM TARGETS
+R: Emil Velikov <emil.l.velikov@gmail.com>
+F: src/gallium/targets/
+
+ANDROID BUILD
+R: Emil Velikov <emil.l.velikov@gmail.com>
+R: Rob Herring <robh@kernel.org>
+F: CleanSpec.mk
+F: */Android.*mk
+F: */Makefile.sources
+
+MESON BUILD
+R: Dylan Baker <dylan@pnwbakers.com>
+R: Eric Engestrom <eric@engestrom.ch>
+F: */meson.build
+F: meson.build
+F: meson_options.txt
+
+ANDROID EGL SUPPORT
+R: Rob Herring <robh@kernel.org>
+R: Tomasz Figa <tfiga@chromium.org>
+F: src/egl/drivers/dri2/platform_android.c
+
+WAYLAND EGL SUPPORT
+R: Daniel Stone <daniels@collabora.com>
+F: src/egl/wayland/*
+F: src/egl/drivers/dri2/platform_wayland.c
+
+FREEDRENO
+R:	Rob Clark <robclark@freedesktop.org>
+F:	src/gallium/drivers/freedreno/
+
+GLX
+R: Adam Jackson <ajax@redhat.com>
+F: src/glx/
+
+VULKAN
+R: Eric Engestrom <eric@engestrom.ch>
+F: src/vulkan/
+F: include/vulkan/
+
+VMWARE DRIVER
+R: Brian Paul <brianp@vmware.com>
+R: Charmaine Lee <charmainel@vmware.com>
+F: src/gallium/drivers/svga/
+
+VMWARE WINSYS CODE
+R: Thomas Hellstrom <thellstrom@vmware.com>
+R: Deepak Rawat <drawat@vmware.com>
+F: src/gallium/winsys/svga/

mesa 3D driver/VERSION

@@ -0,0 +1 @@
+21.2.0-devel

mesa 3D driver/bin/.editorconfig

@@ -0,0 +1,2 @@
+[*.sh]
+indent_style = tab

mesa 3D driver/bin/commit_in_branch.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+
+import argparse
+import subprocess
+import sys
+
+
+def print_(args: argparse.Namespace, success: bool, message: str) -> None:
+    """
+    Print function with extra coloring when supported and/or requested,
+    and with a "quiet" switch
+    """
+
+    COLOR_SUCCESS = '\033[32m'
+    COLOR_FAILURE = '\033[31m'
+    COLOR_RESET = '\033[0m'
+
+    if args.quiet:
+        return
+
+    if args.color == 'auto':
+        use_colors = sys.stdout.isatty()
+    else:
+        use_colors = args.color == 'always'
+
+    s = ''
+    if use_colors:
+        if success:
+            s += COLOR_SUCCESS
+        else:
+            s += COLOR_FAILURE
+
+    s += message
+
+    if use_colors:
+        s += COLOR_RESET
+
+    print(s)
+
+
+def is_commit_valid(commit: str) -> bool:
+    ret = subprocess.call(['git', 'cat-file', '-e', commit],
+                          stdout=subprocess.DEVNULL,
+                          stderr=subprocess.DEVNULL)
+    return ret == 0
+
+
+def branch_has_commit(upstream: str, branch: str, commit: str) -> bool:
+    """
+    Returns True if the commit is actually present in the branch
+    """
+    ret = subprocess.call(['git', 'merge-base', '--is-ancestor',
+                           commit, upstream + '/' + branch],
+                          stdout=subprocess.DEVNULL,
+                          stderr=subprocess.DEVNULL)
+    return ret == 0
+
+
+def branch_has_backport_of_commit(upstream: str, branch: str, commit: str) -> str:
+    """
+    Returns the commit hash if the commit has been backported to the branch,
+    or an empty string if is hasn't
+    """
+    out = subprocess.check_output(['git', 'log', '--format=%H',
+                                   branch + '-branchpoint..' + upstream + '/' + branch,
+                                   '--grep', 'cherry picked from commit ' + commit],
+                                  stderr=subprocess.DEVNULL)
+    return out.decode().strip()
+
+
+def canonicalize_commit(commit: str) -> str:
+    """
+    Takes a commit-ish and returns a commit sha1 if the commit exists
+    """
+
+    # Make sure input is valid first
+    if not is_commit_valid(commit):
+        raise argparse.ArgumentTypeError('invalid commit identifier: ' + commit)
+
+    out = subprocess.check_output(['git', 'rev-parse', commit],
+                                  stderr=subprocess.DEVNULL)
+    return out.decode().strip()
+
+
+def validate_branch(branch: str) -> str:
+    if '/' not in branch:
+        raise argparse.ArgumentTypeError('must be in the form `remote/branch`')
+
+    out = subprocess.check_output(['git', 'remote', '--verbose'],
+                                  stderr=subprocess.DEVNULL)
+    remotes = out.decode().splitlines()
+    (upstream, _) = branch.split('/')
+    valid_remote = False
+    for line in remotes:
+        if line.startswith(upstream + '\t'):
+            valid_remote = True
+
+    if not valid_remote:
+        raise argparse.ArgumentTypeError('Invalid remote: ' + upstream)
+
+    if not is_commit_valid(branch):
+        raise argparse.ArgumentTypeError('Invalid branch: ' + branch)
+
+    return branch
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="""
+    Returns 0 if the commit is present in the branch,
+    1 if it's not,
+    and 2 if it couldn't be determined (eg. invalid commit)
+    """)
+    parser.add_argument('commit',
+                        type=canonicalize_commit,
+                        help='commit sha1')
+    parser.add_argument('branch',
+                        type=validate_branch,
+                        help='branch to check, in the form `remote/branch`')
+    parser.add_argument('--quiet',
+                        action='store_true',
+                        help='suppress all output; exit code can still be used')
+    parser.add_argument('--color',
+                        choices=['auto', 'always', 'never'],
+                        default='auto',
+                        help='colorize output (default: true if stdout is a terminal)')
+    args = parser.parse_args()
+
+    (upstream, branch) = args.branch.split('/')
+
+    if branch_has_commit(upstream, branch, args.commit):
+        print_(args, True, 'Commit ' + args.commit + ' is in branch ' + branch)
+        exit(0)
+
+    backport = branch_has_backport_of_commit(upstream, branch, args.commit)
+    if backport:
+        print_(args, True,
+               'Commit ' + args.commit + ' was backported to branch ' + branch + ' as commit ' + backport)
+        exit(0)
+
+    print_(args, False, 'Commit ' + args.commit + ' is NOT in branch ' + branch)
+    exit(1)

mesa 3D driver/bin/commit_in_branch_test.py

@@ -0,0 +1,116 @@
+import argparse
+import pytest  # type: ignore
+import subprocess
+
+from .commit_in_branch import (
+    is_commit_valid,
+    branch_has_commit,
+    branch_has_backport_of_commit,
+    canonicalize_commit,
+    validate_branch,
+)
+
+
+def get_upstream() -> str:
+    # Let's assume main is bound to the upstream remote and not a fork
+    out = subprocess.check_output(['git', 'for-each-ref',
+                                   '--format=%(upstream)',
+                                   'refs/heads/main'],
+                                  stderr=subprocess.DEVNULL)
+    return out.decode().strip().split('/')[2]
+
+
+@pytest.mark.parametrize(
+    'commit, expected',
+    [
+        ('20.1-branchpoint', True),
+        ('main', True),
+        ('e58a10af640ba58b6001f5c5ad750b782547da76', True),
+        ('d043d24654c851f0be57dbbf48274b5373dea42b', True),
+        ('dd2bd68fa69124c86cd008b256d06f44fab8e6cd', True),
+        ('0000000000000000000000000000000000000000', False),
+        ('not-even-a-valid-commit-format', False),
+    ])
+def test_canonicalize_commit(commit: str, expected: bool) -> None:
+    if expected:
+        assert canonicalize_commit(commit)
+    else:
+        try:
+            assert canonicalize_commit(commit)
+        except argparse.ArgumentTypeError:
+            return
+        assert False
+
+
+@pytest.mark.parametrize(
+    'commit, expected',
+    [
+        (get_upstream() + '/20.1', True),
+        (get_upstream() + '/main', True),
+        ('20.1', False),
+        ('main', False),
+        ('e58a10af640ba58b6001f5c5ad750b782547da76', False),
+        ('d043d24654c851f0be57dbbf48274b5373dea42b', False),
+        ('dd2bd68fa69124c86cd008b256d06f44fab8e6cd', False),
+        ('0000000000000000000000000000000000000000', False),
+        ('not-even-a-valid-commit-format', False),
+    ])
+def test_validate_branch(commit: str, expected: bool) -> None:
+    if expected:
+        assert validate_branch(commit)
+    else:
+        try:
+            assert validate_branch(commit)
+        except argparse.ArgumentTypeError:
+            return
+        assert False
+
+
+@pytest.mark.parametrize(
+    'commit, expected',
+    [
+        ('main', True),
+        ('20.1-branchpoint', True),
+        ('20.1', False),
+        (get_upstream() + '/20.1', True),
+        ('e58a10af640ba58b6001f5c5ad750b782547da76', True),
+        ('d043d24654c851f0be57dbbf48274b5373dea42b', True),
+        ('dd2bd68fa69124c86cd008b256d06f44fab8e6cd', True),
+        ('0000000000000000000000000000000000000000', False),
+        ('not-even-a-valid-commit-format', False),
+    ])
+def test_is_commit_valid(commit: str, expected: bool) -> None:
+    assert is_commit_valid(commit) == expected
+
+
+@pytest.mark.parametrize(
+    'branch, commit, expected',
+    [
+        ('20.1', '20.1-branchpoint', True),
+        ('20.1', '20.0', False),
+        ('20.1', 'main', False),
+        ('20.1', 'e58a10af640ba58b6001f5c5ad750b782547da76', True),
+        ('20.1', 'd043d24654c851f0be57dbbf48274b5373dea42b', True),
+        ('20.1', 'dd2bd68fa69124c86cd008b256d06f44fab8e6cd', False),
+        ('main', 'dd2bd68fa69124c86cd008b256d06f44fab8e6cd', True),
+        ('20.0', 'd043d24654c851f0be57dbbf48274b5373dea42b', False),
+    ])
+def test_branch_has_commit(branch: str, commit: str, expected: bool) -> None:
+    upstream = get_upstream()
+    assert branch_has_commit(upstream, branch, commit) == expected
+
+
+@pytest.mark.parametrize(
+    'branch, commit, expected',
+    [
+        ('20.1', 'dd2bd68fa69124c86cd008b256d06f44fab8e6cd', 'd043d24654c851f0be57dbbf48274b5373dea42b'),
+        ('20.1', '20.1-branchpoint', ''),
+        ('20.1', '20.0', ''),
+        ('20.1', '20.2', ''),
+        ('20.1', 'main', ''),
+        ('20.1', 'd043d24654c851f0be57dbbf48274b5373dea42b', ''),
+        ('20.0', 'dd2bd68fa69124c86cd008b256d06f44fab8e6cd', ''),
+    ])
+def test_branch_has_backport_of_commit(branch: str, commit: str, expected: bool) -> None:
+    upstream = get_upstream()
+    assert branch_has_backport_of_commit(upstream, branch, commit) == expected

mesa 3D driver/bin/gen_calendar_entries.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+
+# Copyright © 2021 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Helper script for manipulating the release calendar."""
+
+from __future__ import annotations
+import argparse
+import csv
+import contextlib
+import datetime
+import pathlib
+import subprocess
+import typing
+
+if typing.TYPE_CHECKING:
+    import _csv
+    from typing_extensions import Protocol
+
+    class RCArguments(Protocol):
+        """Typing information for release-candidate command arguments."""
+
+        manager: str
+
+    class FinalArguments(Protocol):
+        """Typing information for release command arguments."""
+
+        series: str
+        manager: str
+        zero_released: bool
+
+    class ExtendArguments(Protocol):
+        """Typing information for extend command arguments."""
+
+        series: str
+        count: int
+
+
+    CalendarRowType = typing.Tuple[typing.Optional[str], str, str, str, typing.Optional[str]]
+
+
+_ROOT = pathlib.Path(__file__).parent.parent
+CALENDAR_CSV = _ROOT / 'docs' / 'release-calendar.csv'
+VERSION = _ROOT / 'VERSION'
+LAST_RELEASE = 'This is the last planned release of the {}.x series.'
+OR_FINAL = 'Or {}.0 final.'
+
+
+def read_calendar() -> typing.List[CalendarRowType]:
+    """Read the calendar and return a list of it's rows."""
+    with CALENDAR_CSV.open('r') as f:
+        return [typing.cast('CalendarRowType', tuple(r)) for r in csv.reader(f)]
+
+
+def commit(message: str) -> None:
+    """Commit the changes the the release-calendar.csv file."""
+    subprocess.run(['git', 'commit', str(CALENDAR_CSV), '--message', message])
+
+
+
+def _calculate_release_start(major: str, minor: str) -> datetime.date:
+    """Calclulate the start of the release for release candidates.
+
+    This is quarterly, on the second wednesday, in Januray, April, July, and Octobor.
+    """
+    quarter = datetime.date.fromisoformat(f'20{major}-0{[1, 4, 7, 10][int(minor)]}-01')
+
+    # Wednesday is 3
+    day = quarter.isoweekday()
+    if day > 3:
+        # this will walk back into the previous month, it's much simpler to
+        # duplicate the 14 than handle the calculations for the month and year
+        # changing.
+        return quarter.replace(day=quarter.day - day + 3 + 14)
+    elif day < 3:
+        quarter = quarter.replace(day=quarter.day + 3 - day)
+    return quarter.replace(day=quarter.day + 14)
+
+
+def release_candidate(args: RCArguments) -> None:
+    """Add release candidate entries."""
+    with VERSION.open('r') as f:
+        version = f.read().rstrip('-devel')
+    major, minor, _ = version.split('.')
+    date = _calculate_release_start(major, minor)
+
+    data = read_calendar()
+
+    with CALENDAR_CSV.open('w') as f:
+        writer = csv.writer(f)
+        writer.writerows(data)
+
+        writer.writerow([f'{major}.{minor}', date.isoformat(), f'{major}.{minor}.0-rc1', args.manager])
+        for row in range(2, 4):
+            date = date + datetime.timedelta(days=7)
+            writer.writerow([None, date.isoformat(), f'{major}.{minor}.0-rc{row}', args.manager])
+        date = date + datetime.timedelta(days=7)
+        writer.writerow([None, date.isoformat(), f'{major}.{minor}.0-rc4', args.manager, OR_FINAL.format(f'{major}.{minor}')])
+
+    commit(f'docs: Add calendar entries for {major}.{minor} release candidates.')
+
+
+def _calculate_next_release_date(next_is_zero: bool) -> datetime.date:
+    """Calculate the date of the next release.
+
+    If the next is .0, we have the release in seven days, if the next is .1,
+    then it's in 14
+    """
+    date = datetime.date.today()
+    day = date.isoweekday()
+    if day < 3:
+        delta = 3 - day
+    elif day > 3:
+        # this will walk back into the previous month, it's much simpler to
+        # duplicate the 14 than handle the calculations for the month and year
+        # changing.
+        delta = (3 - day)
+    else:
+        delta = 0
+    delta += 7
+    if not next_is_zero:
+        delta += 7
+    return date + datetime.timedelta(days=delta)
+
+
+def final_release(args: FinalArguments) -> None:
+    """Add final release entries."""
+    data = read_calendar()
+    date = _calculate_next_release_date(not args.zero_released)
+
+    with CALENDAR_CSV.open('w') as f:
+        writer = csv.writer(f)
+        writer.writerows(data)
+
+        base = 1 if args.zero_released else 0
+
+        writer.writerow([args.series, date.isoformat(), f'{args.series}.{base}', args.manager])
+        for row in range(base + 1, 3):
+            date = date + datetime.timedelta(days=14)
+            writer.writerow([None, date.isoformat(), f'{args.series}.{row}', args.manager])
+        date = date + datetime.timedelta(days=14)
+        writer.writerow([None, date.isoformat(), f'{args.series}.3', args.manager, LAST_RELEASE.format(args.series)])
+
+    commit(f'docs: Add calendar entries for {args.series} release.')
+
+
+def extend(args: ExtendArguments) -> None:
+    """Extend a release."""
+    @contextlib.contextmanager
+    def write_existing(writer: _csv._writer, current: typing.List[CalendarRowType]) -> typing.Iterator[CalendarRowType]:
+        """Write the orinal file, yield to insert new entries.
+
+        This is a bit clever, basically what happens it writes out the
+        original csv file until it reaches the start of the release after the
+        one we're appending, then it yields the last row. When control is
+        returned it writes out the rest of the original calendar data.
+        """
+        last_row: typing.Optional[CalendarRowType] = None
+        in_wanted = False
+        for row in current:
+            if in_wanted and row[0]:
+                in_wanted = False
+                assert last_row is not None
+                yield last_row
+            if row[0] == args.series:
+                in_wanted = True
+            if in_wanted and len(row) >= 5 and row[4] in {LAST_RELEASE.format(args.series), OR_FINAL.format(args.series)}:
+                # If this was the last planned release and we're adding more,
+                # then we need to remove that message and add it elsewhere
+                r = list(row)
+                r[4] = None
+                # Mypy can't figure this out…
+                row = typing.cast('CalendarRowType', tuple(r))
+            last_row = row
+            writer.writerow(row)
+        # If this is the only entry we can hit a case where the contextmanager
+        # hasn't yielded
+        if in_wanted:
+            yield row
+
+    current = read_calendar()
+
+    with CALENDAR_CSV.open('w') as f:
+        writer = csv.writer(f)
+        with write_existing(writer, current) as row:
+            # Get rid of -rcX as well
+            if '-rc' in row[2]:
+                first_point = int(row[2].split('rc')[-1]) + 1
+                template = '{}.0-rc{}'
+                days = 7
+            else:
+                first_point = int(row[2].split('-')[0].split('.')[-1]) + 1
+                template = '{}.{}'
+                days = 14
+
+            date = datetime.date.fromisoformat(row[1])
+            for i in range(first_point, first_point + args.count):
+                date = date + datetime.timedelta(days=days)
+                r = [None, date.isoformat(), template.format(args.series, i), row[3], None]
+                if i == first_point + args.count - 1:
+                    if days == 14:
+                        r[4] = LAST_RELEASE.format(args.series)
+                    else:
+                        r[4] = OR_FINAL.format(args.series)
+                writer.writerow(r)
+
+    commit(f'docs: Extend calendar entries for {args.series} by {args.count} releases.')
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers()
+
+    rc = sub.add_parser('release-candidate', aliases=['rc'], help='Generate calendar entries for a release candidate.')
+    rc.add_argument('manager', help="the name of the person managing the release.")
+    rc.set_defaults(func=release_candidate)
+
+    fr = sub.add_parser('release', help='Generate calendar entries for a final release.')
+    fr.add_argument('manager', help="the name of the person managing the release.")
+    fr.add_argument('series', help='The series to extend, such as "29.3" or "30.0".')
+    fr.add_argument('--zero-released', action='store_true', help='The .0 release was today, the next release is .1')
+    fr.set_defaults(func=final_release)
+
+    ex = sub.add_parser('extend', help='Generate additional entries for a release.')
+    ex.add_argument('series', help='The series to extend, such as "29.3" or "30.0".')
+    ex.add_argument('count', type=int, help='The number of new entries to add.')
+    ex.set_defaults(func=extend)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

mesa 3D driver/bin/gen_calendar_entries_test.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT
+
+# Copyright © 2021 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import annotations
+from unittest import mock
+import argparse
+import csv
+import contextlib
+import datetime
+import tempfile
+import os
+import pathlib
+import typing
+
+import pytest
+
+from . import gen_calendar_entries
+
+
+@contextlib.contextmanager
+def mock_csv(data: typing.List[gen_calendar_entries.CalendarRowType]) -> typing.Iterator[None]:
+    """Replace the actual CSV data with our test data."""
+    with tempfile.TemporaryDirectory() as d:
+        c = os.path.join(d, 'calendar.csv')
+        with open(c, 'w') as f:
+            writer = csv.writer(f)
+            writer.writerows(data)
+
+        with mock.patch('bin.gen_calendar_entries.CALENDAR_CSV', pathlib.Path(c)):
+            yield
+
+
+@pytest.fixture(autouse=True, scope='module')
+def disable_git_commits() -> None:
+    """Mock out the commit function so no git commits are made durring testing."""
+    with mock.patch('bin.gen_calendar_entries.commit', mock.Mock()):
+        yield
+
+
+class TestReleaseStart:
+
+    def test_first_is_wednesday(self) -> None:
+        d = gen_calendar_entries._calculate_release_start('20', '0')
+        assert d.day == 15
+        assert d.month == 1
+        assert d.year == 2020
+
+    def test_first_is_before_wednesday(self) -> None:
+        d = gen_calendar_entries._calculate_release_start('19', '0')
+        assert d.day == 16
+        assert d.month == 1
+        assert d.year == 2019
+
+    def test_first_is_after_wednesday(self) -> None:
+        d = gen_calendar_entries._calculate_release_start('21', '0')
+        assert d.day == 13
+        assert d.month == 1
+        assert d.year == 2021
+
+
+class TestNextReleaseDate:
+
+    @contextlib.contextmanager
+    def _patch_date(date: datetime.date) -> typing.Iterator[None]:
+        mdate = mock.Mock()
+        mdate.today = mock.Mock(return_value=date)
+        with mock.patch('bin.gen_calendar_entries.datetime.date', mdate):
+            yield
+
+    class TestIsWeds:
+
+        @pytest.fixture(scope='class', autouse=True)
+        def data(self) -> None:
+            date = datetime.date(2021, 1, 6)
+            with TestNextReleaseDate._patch_date(date):
+                yield
+
+        @pytest.mark.parametrize(
+            'is_zero, expected',
+            [
+                (True, 13),
+                (False, 20),
+            ],
+        )
+        def test(self, is_zero: bool, expected: int) -> None:
+            date = gen_calendar_entries._calculate_next_release_date(is_zero)
+            assert date.day == expected
+
+    class TestBeforeWeds:
+
+        @pytest.fixture(scope='class', autouse=True)
+        def data(self) -> None:
+            date = datetime.date(2021, 1, 5)
+            with TestNextReleaseDate._patch_date(date):
+                yield
+
+        @pytest.mark.parametrize(
+            'is_zero, expected',
+            [
+                (True, 13),
+                (False, 20),
+            ],
+        )
+        def test(self, is_zero: bool, expected: int) -> None:
+            date = gen_calendar_entries._calculate_next_release_date(is_zero)
+            assert date.day == expected
+
+    class TestAfterWeds:
+
+        @pytest.fixture(scope='class', autouse=True)
+        def data(self) -> None:
+            date = datetime.date(2021, 1, 8)
+            with TestNextReleaseDate._patch_date(date):
+                yield
+
+        @pytest.mark.parametrize(
+            'is_zero, expected',
+            [
+                (True, 13),
+                (False, 20),
+            ],
+        )
+        def test(self, is_zero: bool, expected: int) -> None:
+            date = gen_calendar_entries._calculate_next_release_date(is_zero)
+            assert date.day == expected
+
+
+class TestRC:
+
+    ORIGINAL_DATA = [
+        ('20.3', '2021-01-13', '20.3.3', 'Dylan Baker', ''),
+        ('',     '2021-01-27', '20.3.4', 'Dylan Baker', 'Last planned release of the 20.3.x series'),
+    ]
+
+    @pytest.fixture(autouse=True, scope='class')
+    def mock_version(self) -> None:
+        """Keep the version set at a specific value."""
+        with tempfile.TemporaryDirectory() as d:
+            v = os.path.join(d, 'version')
+            with open(v, 'w') as f:
+                f.write('21.0.0-devel\n')
+
+            with mock.patch('bin.gen_calendar_entries.VERSION', pathlib.Path(v)):
+                yield
+
+    @pytest.fixture(autouse=True)
+    def csv(self) -> None:
+        """inject our test data.."""
+        with mock_csv(self.ORIGINAL_DATA):
+            yield
+
+    def test_basic(self) -> None:
+        args: gen_calendar_entries.RCArguments = argparse.Namespace()
+        args.manager = "Dylan Baker"
+        gen_calendar_entries.release_candidate(args)
+
+        expected = self.ORIGINAL_DATA.copy()
+        expected.append(('21.0', '2021-01-13', f'21.0.0-rc1', 'Dylan Baker'))
+        expected.append((    '', '2021-01-20', f'21.0.0-rc2', 'Dylan Baker'))
+        expected.append((    '', '2021-01-27', f'21.0.0-rc3', 'Dylan Baker'))
+        expected.append((    '', '2021-02-03', f'21.0.0-rc4', 'Dylan Baker', 'Or 21.0.0 final.'))
+
+        actual = gen_calendar_entries.read_calendar()
+
+        assert actual == expected
+
+
+class TestExtend:
+
+    def test_one_release(self) -> None:
+        data = [
+            ('20.3', '2021-01-13', '20.3.3', 'Dylan Baker', ''),
+            ('',     '2021-01-27', '20.3.4', 'Dylan Baker', 'This is the last planned release of the 20.3.x series.'),
+        ]
+
+        args: gen_calendar_entries.ExtendArguments = argparse.Namespace()
+        args.series = '20.3'
+        args.count = 2
+
+        with mock_csv(data):
+            gen_calendar_entries.extend(args)
+            actual = gen_calendar_entries.read_calendar()
+
+        expected = [
+            data[0],
+            ('', '2021-01-27', '20.3.4', 'Dylan Baker', ''),
+            ('', '2021-02-10', '20.3.5', 'Dylan Baker', ''),
+            ('', '2021-02-24', '20.3.6', 'Dylan Baker', 'This is the last planned release of the 20.3.x series.'),
+        ]
+
+        assert actual == expected
+    def test_one_release(self) -> None:
+        data = [
+            ('20.3', '2021-01-13', '20.3.3', 'Dylan Baker', ''),
+            ('',     '2021-01-27', '20.3.4', 'Dylan Baker', 'This is the last planned release of the 20.3.x series.'),
+            ('21.0', '2021-01-13', '21.0.1', 'Dylan Baker', ''),
+            ('',     '2021-01-27', '21.0.2', 'Dylan Baker', ''),
+            ('',     '2021-02-10', '21.0.3', 'Dylan Baker', ''),
+            ('',     '2021-02-24', '21.0.4', 'Dylan Baker', 'This is the last planned release of the 21.0.x series.'),
+        ]
+
+        args: gen_calendar_entries.ExtendArguments = argparse.Namespace()
+        args.series = '21.0'
+        args.count = 1
+
+        with mock_csv(data):
+            gen_calendar_entries.extend(args)
+            actual = gen_calendar_entries.read_calendar()
+
+        expected = data.copy()
+        d = list(data[-1])
+        d[-1] = ''
+        expected[-1] = tuple(d)
+        expected.extend([
+            ('',     '2021-03-10', '21.0.5', 'Dylan Baker', 'This is the last planned release of the 21.0.x series.'),
+        ])
+
+        assert actual == expected
+
+    def test_rc(self) -> None:
+        data = [
+            ('20.3', '2021-01-13', '20.3.3', 'Dylan Baker', ''),
+            ('',     '2021-01-27', '20.3.4', 'Dylan Baker', 'This is the last planned release of the 20.3.x series.'),
+            ('21.0', '2021-01-13', '21.0.0-rc1', 'Dylan Baker', ''),
+            ('',     '2021-01-20', '21.0.0-rc2', 'Dylan Baker', gen_calendar_entries.OR_FINAL.format('21.0')),
+        ]
+
+        args: gen_calendar_entries.ExtendArguments = argparse.Namespace()
+        args.series = '21.0'
+        args.count = 2
+
+        with mock_csv(data):
+            gen_calendar_entries.extend(args)
+            actual = gen_calendar_entries.read_calendar()
+
+        expected = data.copy()
+        d = list(expected[-1])
+        d[-1] = ''
+        expected[-1] = tuple(d)
+        expected.extend([
+            ('', '2021-01-27', '21.0.0-rc3', 'Dylan Baker', ''),
+            ('', '2021-02-03', '21.0.0-rc4', 'Dylan Baker', gen_calendar_entries.OR_FINAL.format('21.0')),
+        ])
+
+        assert actual == expected
+
+
+class TestFinal:
+
+    @pytest.fixture(autouse=True, scope='class')
+    def _patch_date(self) -> typing.Iterator[None]:
+        mdate = mock.Mock()
+        mdate.today = mock.Mock(return_value=datetime.date(2021, 1, 6))
+        with mock.patch('bin.gen_calendar_entries.datetime.date', mdate):
+            yield
+
+    ORIGINAL_DATA = [
+        ('20.3', '2021-01-13', '20.3.3', 'Dylan Baker', ''),
+        ('',     '2021-01-27', '20.3.4', 'Dylan Baker', 'Last planned release of the 20.3.x series'),
+    ]
+
+    @pytest.fixture(autouse=True)
+    def csv(self) -> None:
+        """inject our test data.."""
+        with mock_csv(self.ORIGINAL_DATA):
+            yield
+
+    def test_zero_released(self) -> None:
+        args: gen_calendar_entries.FinalArguments = argparse.Namespace()
+        args.manager = "Dylan Baker"
+        args.zero_released = True
+        args.series = '21.0'
+        gen_calendar_entries.final_release(args)
+
+        expected = self.ORIGINAL_DATA.copy()
+        expected.append(('21.0', '2021-01-20', f'21.0.1', 'Dylan Baker'))
+        expected.append((    '', '2021-02-03', f'21.0.2', 'Dylan Baker'))
+        expected.append((    '', '2021-02-17', f'21.0.3', 'Dylan Baker', gen_calendar_entries.LAST_RELEASE.format(args.series)))
+
+        actual = gen_calendar_entries.read_calendar()
+
+        assert actual == expected
+
+    def test_zero_not_released(self) -> None:
+        args: gen_calendar_entries.FinalArguments = argparse.Namespace()
+        args.manager = "Dylan Baker"
+        args.zero_released = False
+        args.series = '21.0'
+        gen_calendar_entries.final_release(args)
+
+        expected = self.ORIGINAL_DATA.copy()
+        expected.append(('21.0', '2021-01-13', f'21.0.0', 'Dylan Baker'))
+        expected.append((    '', '2021-01-27', f'21.0.1', 'Dylan Baker'))
+        expected.append((    '', '2021-02-10', f'21.0.2', 'Dylan Baker'))
+        expected.append((    '', '2021-02-24', f'21.0.3', 'Dylan Baker', gen_calendar_entries.LAST_RELEASE.format(args.series)))
+
+        actual = gen_calendar_entries.read_calendar()
+
+        assert actual == expected

mesa 3D driver/bin/gen_release_notes.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Generates release notes for a given version of mesa."""
+
+import asyncio
+import datetime
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import textwrap
+import typing
+import urllib.parse
+
+import aiohttp
+from mako.template import Template
+from mako import exceptions
+
+import docutils.utils
+import docutils.parsers.rst.states as states
+
+CURRENT_GL_VERSION = '4.6'
+CURRENT_VK_VERSION = '1.2'
+
+TEMPLATE = Template(textwrap.dedent("""\
+    ${header}
+    ${header_underline}
+
+    %if not bugfix:
+    Mesa ${this_version} is a new development release. People who are concerned
+    with stability and reliability should stick with a previous release or
+    wait for Mesa ${this_version[:-1]}1.
+    %else:
+    Mesa ${this_version} is a bug fix release which fixes bugs found since the ${previous_version} release.
+    %endif
+
+    Mesa ${this_version} implements the OpenGL ${gl_version} API, but the version reported by
+    glGetString(GL_VERSION) or glGetIntegerv(GL_MAJOR_VERSION) /
+    glGetIntegerv(GL_MINOR_VERSION) depends on the particular driver being used.
+    Some drivers don't support all the features required in OpenGL ${gl_version}. OpenGL
+    ${gl_version} is **only** available if requested at context creation.
+    Compatibility contexts may report a lower version depending on each driver.
+
+    Mesa ${this_version} implements the Vulkan ${vk_version} API, but the version reported by
+    the apiVersion property of the VkPhysicalDeviceProperties struct
+    depends on the particular driver being used.
+
+    SHA256 checksum
+    ---------------
+
+    ::
+
+        TBD.
+
+
+    New features
+    ------------
+
+    %for f in features:
+    - ${rst_escape(f)}
+    %endfor
+
+
+    Bug fixes
+    ---------
+
+    %for b in bugs:
+    - ${rst_escape(b)}
+    %endfor
+
+
+    Changes
+    -------
+    %for c, author_line in changes:
+      %if author_line:
+
+    ${rst_escape(c)}
+
+      %else:
+    - ${rst_escape(c)}
+      %endif
+    %endfor
+    """))
+
+
+# copied from https://docutils.sourceforge.io/sandbox/xml2rst/xml2rstlib/markup.py
+class Inliner(states.Inliner):
+    """
+    Recognizer for inline markup. Derive this from the original inline
+    markup parser for best results.
+    """
+
+    # Copy static attributes from super class
+    vars().update(vars(states.Inliner))
+
+    def quoteInline(self, text):
+        """
+        `text`: ``str``
+          Return `text` with inline markup quoted.
+        """
+        # Method inspired by `states.Inliner.parse`
+        self.document = docutils.utils.new_document("<string>")
+        self.document.settings.trim_footnote_reference_space = False
+        self.document.settings.character_level_inline_markup = False
+        self.document.settings.pep_references = False
+        self.document.settings.rfc_references = False
+
+        self.init_customizations(self.document.settings)
+
+        self.reporter = self.document.reporter
+        self.reporter.stream = None
+        self.language = None
+        self.parent = self.document
+        remaining = docutils.utils.escape2null(text)
+        checked = ""
+        processed = []
+        unprocessed = []
+        messages = []
+        while remaining:
+            original = remaining
+            match = self.patterns.initial.search(remaining)
+            if match:
+                groups = match.groupdict()
+                method = self.dispatch[groups['start'] or groups['backquote']
+                                       or groups['refend'] or groups['fnend']]
+                before, inlines, remaining, sysmessages = method(self, match, 0)
+                checked += before
+                if inlines:
+                    assert len(inlines) == 1, "More than one inline found"
+                    inline = original[len(before)
+                                      :len(original) - len(remaining)]
+                    rolePfx = re.search("^:" + self.simplename + ":(?=`)",
+                                        inline)
+                    refSfx = re.search("_+$", inline)
+                    if rolePfx:
+                        # Prefixed roles need to be quoted in the middle
+                        checked += (inline[:rolePfx.end()] + "\\"
+                                    + inline[rolePfx.end():])
+                    elif refSfx and not re.search("^`", inline):
+                        # Pure reference markup needs to be quoted at the end
+                        checked += (inline[:refSfx.start()] + "\\"
+                                    + inline[refSfx.start():])
+                    else:
+                        # Quote other inlines by prefixing
+                        checked += "\\" + inline
+            else:
+                checked += remaining
+                break
+        # Quote all original backslashes
+        checked = re.sub('\x00', "\\\x00", checked)
+        return docutils.utils.unescape(checked, 1)
+
+inliner = Inliner();
+
+
+async def gather_commits(version: str) -> str:
+    p = await asyncio.create_subprocess_exec(
+        'git', 'log', '--oneline', f'mesa-{version}..', '--grep', r'Closes: \(https\|#\).*',
+        stdout=asyncio.subprocess.PIPE)
+    out, _ = await p.communicate()
+    assert p.returncode == 0, f"git log didn't work: {version}"
+    return out.decode().strip()
+
+
+async def gather_bugs(version: str) -> typing.List[str]:
+    commits = await gather_commits(version)
+
+    issues: typing.List[str] = []
+    for commit in commits.split('\n'):
+        sha, message = commit.split(maxsplit=1)
+        p = await asyncio.create_subprocess_exec(
+            'git', 'log', '--max-count', '1', r'--format=%b', sha,
+            stdout=asyncio.subprocess.PIPE)
+        _out, _ = await p.communicate()
+        out = _out.decode().split('\n')
+        for line in reversed(out):
+            if line.startswith('Closes:'):
+                bug = line.lstrip('Closes:').strip()
+                break
+        else:
+            raise Exception('No closes found?')
+        if bug.startswith('h'):
+            # This means we have a bug in the form "Closes: https://..."
+            issues.append(os.path.basename(urllib.parse.urlparse(bug).path))
+        else:
+            issues.append(bug.lstrip('#'))
+
+    loop = asyncio.get_event_loop()
+    async with aiohttp.ClientSession(loop=loop) as session:
+        results = await asyncio.gather(*[get_bug(session, i) for i in issues])
+    typing.cast(typing.Tuple[str, ...], results)
+    bugs = list(results)
+    if not bugs:
+        bugs = ['None']
+    return bugs
+
+
+async def get_bug(session: aiohttp.ClientSession, bug_id: str) -> str:
+    """Query gitlab to get the name of the issue that was closed."""
+    # Mesa's gitlab id is 176,
+    url = 'https://gitlab.freedesktop.org/api/v4/projects/176/issues'
+    params = {'iids[]': bug_id}
+    async with session.get(url, params=params) as response:
+        content = await response.json()
+    return content[0]['title']
+
+
+async def get_shortlog(version: str) -> str:
+    """Call git shortlog."""
+    p = await asyncio.create_subprocess_exec('git', 'shortlog', f'mesa-{version}..',
+                                             stdout=asyncio.subprocess.PIPE)
+    out, _ = await p.communicate()
+    assert p.returncode == 0, 'error getting shortlog'
+    assert out is not None, 'just for mypy'
+    return out.decode()
+
+
+def walk_shortlog(log: str) -> typing.Generator[typing.Tuple[str, bool], None, None]:
+    for l in log.split('\n'):
+        if l.startswith(' '): # this means we have a patch description
+            yield l.lstrip(), False
+        elif l.strip():
+            yield l, True
+
+
+def calculate_next_version(version: str, is_point: bool) -> str:
+    """Calculate the version about to be released."""
+    if '-' in version:
+        version = version.split('-')[0]
+    if is_point:
+        base = version.split('.')
+        base[2] = str(int(base[2]) + 1)
+        return '.'.join(base)
+    return version
+
+
+def calculate_previous_version(version: str, is_point: bool) -> str:
+    """Calculate the previous version to compare to.
+
+    In the case of -rc to final that verison is the previous .0 release,
+    (19.3.0 in the case of 20.0.0, for example). for point releases that is
+    the last point release. This value will be the same as the input value
+    for a point release, but different for a major release.
+    """
+    if '-' in version:
+        version = version.split('-')[0]
+    if is_point:
+        return version
+    base = version.split('.')
+    if base[1] == '0':
+        base[0] = str(int(base[0]) - 1)
+        base[1] = '3'
+    else:
+        base[1] = str(int(base[1]) - 1)
+    return '.'.join(base)
+
+
+def get_features(is_point_release: bool) -> typing.Generator[str, None, None]:
+    p = pathlib.Path(__file__).parent.parent / 'docs' / 'relnotes' / 'new_features.txt'
+    if p.exists():
+        if is_point_release:
+            print("WARNING: new features being introduced in a point release", file=sys.stderr)
+        with p.open('rt') as f:
+            for line in f:
+                yield line
+            else:
+                yield "None"
+        p.unlink()
+    else:
+        yield "None"
+
+
+async def main() -> None:
+    v = pathlib.Path(__file__).parent.parent / 'VERSION'
+    with v.open('rt') as f:
+        raw_version = f.read().strip()
+    is_point_release = '-rc' not in raw_version
+    assert '-devel' not in raw_version, 'Do not run this script on -devel'
+    version = raw_version.split('-')[0]
+    previous_version = calculate_previous_version(version, is_point_release)
+    this_version = calculate_next_version(version, is_point_release)
+    today = datetime.date.today()
+    header = f'Mesa {this_version} Release Notes / {today}'
+    header_underline = '=' * len(header)
+
+    shortlog, bugs = await asyncio.gather(
+        get_shortlog(previous_version),
+        gather_bugs(previous_version),
+    )
+
+    final = pathlib.Path(__file__).parent.parent / 'docs' / 'relnotes' / f'{this_version}.rst'
+    with final.open('wt') as f:
+        try:
+            f.write(TEMPLATE.render(
+                bugfix=is_point_release,
+                bugs=bugs,
+                changes=walk_shortlog(shortlog),
+                features=get_features(is_point_release),
+                gl_version=CURRENT_GL_VERSION,
+                this_version=this_version,
+                header=header,
+                header_underline=header_underline,
+                previous_version=previous_version,
+                vk_version=CURRENT_VK_VERSION,
+                rst_escape=inliner.quoteInline,
+            ))
+        except:
+            print(exceptions.text_error_template().render())
+
+    subprocess.run(['git', 'add', final])
+    subprocess.run(['git', 'commit', '-m',
+                    f'docs: add release notes for {this_version}'])
+
+
+if __name__ == "__main__":
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())

mesa 3D driver/bin/gen_release_notes_test.py

@@ -0,0 +1,60 @@
+# Copyright © 2019 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import pytest
+
+from .gen_release_notes import *
+
+
+@pytest.mark.parametrize(
+    'current, is_point, expected',
+    [
+        ('19.2.0', True, '19.2.1'),
+        ('19.3.6', True, '19.3.7'),
+        ('20.0.0-rc4', False, '20.0.0'),
+    ])
+def test_next_version(current: str, is_point: bool, expected: str) -> None:
+    assert calculate_next_version(current, is_point) == expected
+
+
+@pytest.mark.parametrize(
+    'current, is_point, expected',
+    [
+        ('19.3.6', True, '19.3.6'),
+        ('20.0.0-rc4', False, '19.3.0'),
+    ])
+def test_previous_version(current: str, is_point: bool, expected: str) -> None:
+    assert calculate_previous_version(current, is_point) == expected
+
+
+@pytest.mark.asyncio
+async def test_get_shortlog():
+    # Certainly not perfect, but it's something
+    version = '19.2.0'
+    out = await get_shortlog(version)
+    assert out
+
+
+@pytest.mark.asyncio
+async def test_gather_commits():
+    # Certainly not perfect, but it's something
+    version = '19.2.0'
+    out = await gather_commits(version)
+    assert out

mesa 3D driver/bin/git_sha1_gen.py

@@ -0,0 +1,50 @@
+"""
+Generate the contents of the git_sha1.h file.
+"""
+
+import argparse
+import os
+import os.path
+import subprocess
+import sys
+
+
+def get_git_sha1():
+    """Try to get the git SHA1 with git rev-parse."""
+    git_dir = os.path.join(os.path.dirname(sys.argv[0]), '..', '.git')
+    try:
+        git_sha1 = subprocess.check_output([
+            'git',
+            '--git-dir=' + git_dir,
+            'rev-parse',
+            'HEAD',
+        ], stderr=open(os.devnull, 'w')).decode("ascii")
+    except Exception:
+        # don't print anything if it fails
+        git_sha1 = ''
+    return git_sha1
+
+
+def write_if_different(contents):
+    """
+    Avoid touching the output file if it doesn't need modifications
+    Useful to avoid triggering rebuilds when nothing has changed.
+    """
+    if os.path.isfile(args.output):
+        with open(args.output, 'r') as file:
+            if file.read() == contents:
+                return
+    with open(args.output, 'w') as file:
+        file.write(contents)
+
+
+parser = argparse.ArgumentParser()
+parser.add_argument('--output', help='File to write the #define in',
+                    required=True)
+args = parser.parse_args()
+
+git_sha1 = os.environ.get('MESA_GIT_SHA1_OVERRIDE', get_git_sha1())[:10]
+if git_sha1:
+    write_if_different('#define MESA_GIT_SHA1 " (git-' + git_sha1 + ')"')
+else:
+    write_if_different('#define MESA_GIT_SHA1 ""')

mesa 3D driver/bin/install_megadrivers.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# encoding=utf-8
+# Copyright 2017-2018 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Script to install megadriver symlinks for meson."""
+
+from __future__ import print_function
+import argparse
+import os
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('megadriver')
+    parser.add_argument('libdir')
+    parser.add_argument('drivers', nargs='+')
+    args = parser.parse_args()
+
+    if os.path.isabs(args.libdir):
+        destdir = os.environ.get('DESTDIR')
+        if destdir:
+            to = os.path.join(destdir, args.libdir[1:])
+        else:
+            to = args.libdir
+    else:
+        to = os.path.join(os.environ['MESON_INSTALL_DESTDIR_PREFIX'], args.libdir)
+
+    master = os.path.join(to, os.path.basename(args.megadriver))
+
+    if not os.path.exists(to):
+        if os.path.lexists(to):
+            os.unlink(to)
+        os.makedirs(to)
+
+    for driver in args.drivers:
+        abs_driver = os.path.join(to, driver)
+
+        if os.path.lexists(abs_driver):
+            os.unlink(abs_driver)
+        print('installing {} to {}'.format(args.megadriver, abs_driver))
+        os.link(master, abs_driver)
+
+        try:
+            ret = os.getcwd()
+            os.chdir(to)
+
+            name, ext = os.path.splitext(driver)
+            while ext != '.so':
+                if os.path.lexists(name):
+                    os.unlink(name)
+                os.symlink(driver, name)
+                name, ext = os.path.splitext(name)
+        finally:
+            os.chdir(ret)
+
+    # Remove meson-created master .so and symlinks
+    os.unlink(master)
+    name, ext = os.path.splitext(master)
+    while ext != '.so':
+        if os.path.lexists(name):
+            os.unlink(name)
+        name, ext = os.path.splitext(name)
+
+
+if __name__ == '__main__':
+    main()

mesa 3D driver/bin/khronos-update.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+
+import argparse
+import base64
+import pathlib
+import requests
+import subprocess
+import typing
+
+
+def error(msg: str) -> None:
+    print('\033[31m' + msg + '\033[0m')
+
+
+class Source:
+    def __init__(self, filename: str, url: typing.Optional[str]):
+        self.file = pathlib.Path(filename)
+        self.url = url
+
+    def sync(self) -> None:
+        if self.url is None:
+            return
+
+        print('Syncing {}...'.format(self.file), end=' ', flush=True)
+        req = requests.get(self.url)
+
+        if not req.ok:
+            error('Failed to retrieve file: {} {}'.format(req.status_code, req.reason))
+            return
+
+        # Gitiles returns base64-encoded strings.
+        # Google has been resisting for years to the idea of allowing plain text: https://github.com/google/gitiles/issues/7
+        if 'format=TEXT' in self.url:
+            content = base64.b64decode(req.content)
+        else:
+            content = req.content
+
+        with open(self.file, 'wb') as f:
+            f.write(content)
+
+        print('Done')
+
+
+# a URL of `None` means there is no upstream, because *we* are the upstream
+SOURCES = [
+    {
+        'api': 'khr',
+        'inc_folder': 'KHR',
+        'sources': [
+            Source('include/KHR/khrplatform.h',    'https://github.com/KhronosGroup/EGL-Registry/raw/master/api/KHR/khrplatform.h'),
+        ],
+    },
+
+    {
+        'api': 'egl',
+        'inc_folder': 'EGL',
+        'sources': [
+            Source('src/egl/generate/egl.xml',     'https://github.com/KhronosGroup/EGL-Registry/raw/master/api/egl.xml'),
+            Source('include/EGL/egl.h',            'https://github.com/KhronosGroup/EGL-Registry/raw/master/api/EGL/egl.h'),
+            Source('include/EGL/eglplatform.h',    'https://github.com/KhronosGroup/EGL-Registry/raw/master/api/EGL/eglplatform.h'),
+            Source('include/EGL/eglext.h',         'https://github.com/KhronosGroup/EGL-Registry/raw/master/api/EGL/eglext.h'),
+            Source('include/EGL/eglextchromium.h', 'https://chromium.googlesource.com/chromium/src/+/refs/heads/master/ui/gl/EGL/eglextchromium.h?format=TEXT'),
+            Source('include/EGL/eglext_angle.h',   'https://chromium.googlesource.com/angle/angle/+/refs/heads/master/include/EGL/eglext_angle.h?format=TEXT'),
+            Source('include/EGL/eglmesaext.h',     None),
+        ],
+    },
+
+    {
+        'api': 'gl',
+        'inc_folder': 'GL',
+        'sources': [
+            Source('src/mapi/glapi/registry/gl.xml', 'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/xml/gl.xml'),
+            Source('include/GL/glcorearb.h',         'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GL/glcorearb.h'),
+            Source('include/GL/glext.h',             'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GL/glext.h'),
+            Source('include/GL/glxext.h',            'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GL/glxext.h'),
+            Source('include/GL/wglext.h',            'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GL/wglext.h'),
+            Source('include/GL/gl.h',                None),  # FIXME: I don't know what the canonical source is
+            Source('include/GL/glx.h',               None),  # FIXME: I don't know what the canonical source is
+            Source('include/GL/internal/',           None),
+            Source('include/GL/mesa_glinterop.h',    None),
+            Source('include/GL/osmesa.h',            None),
+        ],
+    },
+
+    {
+        'api': 'gles1',
+        'inc_folder': 'GLES',
+        'sources': [
+            Source('include/GLES/gl.h',         'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES/gl.h'),
+            Source('include/GLES/glplatform.h', 'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES/glplatform.h'),
+            Source('include/GLES/glext.h',      'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES/glext.h'),
+            Source('include/GLES/egl.h',        'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES/egl.h'),
+        ],
+    },
+
+    {
+        'api': 'gles2',
+        'inc_folder': 'GLES2',
+        'sources': [
+            Source('include/GLES2/gl2.h',         'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES2/gl2.h'),
+            Source('include/GLES2/gl2platform.h', 'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES2/gl2platform.h'),
+            Source('include/GLES2/gl2ext.h',      'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES2/gl2ext.h'),
+        ],
+    },
+
+    {
+        'api': 'gles3',
+        'inc_folder': 'GLES3',
+        'sources': [
+            Source('include/GLES3/gl3.h',         'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES3/gl3.h'),
+            Source('include/GLES3/gl31.h',        'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES3/gl31.h'),
+            Source('include/GLES3/gl32.h',        'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES3/gl32.h'),
+            Source('include/GLES3/gl3platform.h', 'https://github.com/KhronosGroup/OpenGL-Registry/raw/master/api/GLES3/gl3platform.h'),
+            Source('include/GLES3/gl3ext.h',      None),  # FIXME: I don't know what the canonical source is
+        ],
+    },
+
+    {
+        'api': 'opencl',
+        'inc_folder': 'CL',
+        'sources': [
+            Source('include/CL/opencl.h',                        'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/opencl.h'),
+            Source('include/CL/cl.h',                            'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl.h'),
+            Source('include/CL/cl_platform.h',                   'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_platform.h'),
+            Source('include/CL/cl_gl.h',                         'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_gl.h'),
+            Source('include/CL/cl_gl_ext.h',                     'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_gl_ext.h'),
+            Source('include/CL/cl_ext.h',                        'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_ext.h'),
+            Source('include/CL/cl_version.h',                    'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_version.h'),
+            Source('include/CL/cl_icd.h',                        'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_icd.h'),
+            Source('include/CL/cl_egl.h',                        'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_egl.h'),
+            Source('include/CL/cl_d3d10.h',                      'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_d3d10.h'),
+            Source('include/CL/cl_d3d11.h',                      'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_d3d11.h'),
+            Source('include/CL/cl_dx9_media_sharing.h',          'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_dx9_media_sharing.h'),
+            Source('include/CL/cl_dx9_media_sharing_intel.h',    'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_dx9_media_sharing_intel.h'),
+            Source('include/CL/cl_ext_intel.h',                  'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_ext_intel.h'),
+            Source('include/CL/cl_va_api_media_sharing_intel.h', 'https://github.com/KhronosGroup/OpenCL-Headers/raw/master/CL/cl_va_api_media_sharing_intel.h'),
+
+            Source('include/CL/cl.hpp',                          'https://github.com/KhronosGroup/OpenCL-CLHPP/raw/master/include/CL/cl.hpp'),
+            Source('include/CL/cl2.hpp',                         'https://github.com/KhronosGroup/OpenCL-CLHPP/raw/master/include/CL/cl2.hpp'),
+        ],
+    },
+
+    {
+        'api': 'spirv',
+        'sources': [
+            Source('src/compiler/spirv/spirv.h',                    'https://github.com/KhronosGroup/SPIRV-Headers/raw/master/include/spirv/unified1/spirv.h'),
+            Source('src/compiler/spirv/spirv.core.grammar.json',    'https://github.com/KhronosGroup/SPIRV-Headers/raw/master/include/spirv/unified1/spirv.core.grammar.json'),
+            Source('src/compiler/spirv/OpenCL.std.h',               'https://github.com/KhronosGroup/SPIRV-Headers/raw/master/include/spirv/unified1/OpenCL.std.h'),
+            Source('src/compiler/spirv/GLSL.std.450.h',             'https://github.com/KhronosGroup/SPIRV-Headers/raw/master/include/spirv/unified1/GLSL.std.450.h'),
+            Source('src/compiler/spirv/GLSL.ext.AMD.h',             'https://github.com/KhronosGroup/glslang/raw/master/SPIRV/GLSL.ext.AMD.h'),  # FIXME: is this the canonical source?
+        ],
+    },
+
+    {
+        'api': 'vulkan',
+        'inc_folder': 'vulkan',
+        'sources': [
+            Source('src/vulkan/registry/vk.xml',                'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/registry/vk.xml'),
+            Source('include/vulkan/vulkan.h',                   'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan.h'),
+            Source('include/vulkan/vulkan_core.h',              'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_core.h'),
+            Source('include/vulkan/vulkan_beta.h',              'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_beta.h'),
+            Source('include/vulkan/vk_icd.h',                   'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vk_icd.h'),
+            Source('include/vulkan/vk_layer.h',                 'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vk_layer.h'),
+            Source('include/vulkan/vk_platform.h',              'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vk_platform.h'),
+            Source('include/vulkan/vulkan_android.h',           'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_android.h'),
+            Source('include/vulkan/vulkan_fuchsia.h',           'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_fuchsia.h'),
+            Source('include/vulkan/vulkan_ggp.h',               'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_ggp.h'),
+            Source('include/vulkan/vulkan_ios.h',               'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_ios.h'),
+            Source('include/vulkan/vulkan_macos.h',             'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_macos.h'),
+            Source('include/vulkan/vulkan_metal.h',             'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_metal.h'),
+            Source('include/vulkan/vulkan_vi.h',                'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_vi.h'),
+            Source('include/vulkan/vulkan_wayland.h',           'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_wayland.h'),
+            Source('include/vulkan/vulkan_win32.h',             'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_win32.h'),
+            Source('include/vulkan/vulkan_xcb.h',               'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_xcb.h'),
+            Source('include/vulkan/vulkan_xlib.h',              'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_xlib.h'),
+            Source('include/vulkan/vulkan_xlib_xrandr.h',       'https://github.com/KhronosGroup/Vulkan-Headers/raw/master/include/vulkan/vulkan_xlib_xrandr.h'),
+            Source('include/vulkan/vk_android_native_buffer.h', 'https://android.googlesource.com/platform/frameworks/native/+/master/vulkan/include/vulkan/vk_android_native_buffer.h?format=TEXT'),
+            Source('include/vulkan/.editorconfig',              None),
+        ],
+    },
+]
+
+
+if __name__ == '__main__':
+    git_toplevel = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'],
+                                           stderr=subprocess.DEVNULL).decode("ascii").strip()
+    if not pathlib.Path(git_toplevel).resolve() == pathlib.Path('.').resolve():
+        error('Please run this script from the root folder ({})'.format(git_toplevel))
+        exit(1)
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument('apis', nargs='*',
+                        # the `[[]]` here is a workaround for python bug 9625
+                        # where having `choices` breaks `nargs='*'`:
+                        # https://bugs.python.org/issue9625
+                        choices=[group['api'] for group in SOURCES] + [[]],
+                        help='Only update the APIs specified.')
+    args = parser.parse_args()
+
+    # These APIs all depend on the KHR header
+    depend_on_khr = set(['egl', 'gl', 'gles', 'gles2', 'gles3'])
+    if args.apis and 'khr' not in args.apis and depend_on_khr.intersection(set(args.apis)):
+        args.apis = ['khr'] + args.apis
+
+    for group in SOURCES:
+        if args.apis and group['api'] not in args.apis:
+            continue
+
+        for source in group['sources']:
+            source.sync()
+
+        # Make sure all the API files are handled by this script
+        if 'inc_folder' in group:
+            for file in pathlib.Path('include/' + group['inc_folder']).iterdir():
+                if file not in [source.file for source in group['sources']]:
+                    error('{} is unknown, please add it to SOURCES'.format(file))

mesa 3D driver/bin/meson-cmd-extract.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+# Copyright © 2019 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""This script reads a meson build directory and gives back the command line it
+was configured with.
+
+This only works for meson 0.49.0 and newer.
+"""
+
+import argparse
+import ast
+import configparser
+import pathlib
+import sys
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse arguments."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        'build_dir',
+        help='Path the meson build directory')
+    args = parser.parse_args()
+    return args
+
+
+def load_config(path: pathlib.Path) -> configparser.ConfigParser:
+    """Load config file."""
+    conf = configparser.ConfigParser()
+    with path.open() as f:
+        conf.read_file(f)
+    return conf
+
+
+def build_cmd(conf: configparser.ConfigParser) -> str:
+    """Rebuild the command line."""
+    args = []
+    for k, v in conf['options'].items():
+        if ' ' in v:
+            args.append(f'-D{k}="{v}"')
+        else:
+            args.append(f'-D{k}={v}')
+
+    cf = conf['properties'].get('cross_file')
+    if cf:
+        args.append('--cross-file={}'.format(cf))
+    nf = conf['properties'].get('native_file')
+    if nf:
+        # this will be in the form "['str', 'str']", so use ast.literal_eval to
+        # convert it to a list of strings.
+        nf = ast.literal_eval(nf)
+        args.extend(['--native-file={}'.format(f) for f in nf])
+    return ' '.join(args)
+
+
+def main():
+    args = parse_args()
+    path = pathlib.Path(args.build_dir, 'meson-private', 'cmd_line.txt')
+    if not path.exists():
+        print('Cannot find the necessary file to rebuild command line. '
+              'Is your meson version >= 0.49.0?', file=sys.stderr)
+        sys.exit(1)
+
+    conf = load_config(path)
+    cmd = build_cmd(conf)
+    print(cmd)
+
+
+if __name__ == '__main__':
+    main()

mesa 3D driver/bin/meson-options.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+
+from os import get_terminal_size
+from textwrap import wrap
+from mesonbuild import coredata
+from mesonbuild import optinterpreter
+
+(COLUMNS, _) = get_terminal_size()
+
+def describe_option(option_name: str, option_default_value: str,
+                    option_type: str, option_message: str) -> None:
+    print('name:    ' + option_name)
+    print('default: ' + option_default_value)
+    print('type:    ' + option_type)
+    for line in wrap(option_message, width=COLUMNS - 9):
+        print('         ' + line)
+    print('---')
+
+oi = optinterpreter.OptionInterpreter('')
+oi.process('meson_options.txt')
+
+for (name, value) in oi.options.items():
+    if isinstance(value, coredata.UserStringOption):
+        describe_option(name,
+                        value.value,
+                        'string',
+                        "You can type what you want, but make sure it makes sense")
+    elif isinstance(value, coredata.UserBooleanOption):
+        describe_option(name,
+                        'true' if value.value else 'false',
+                        'boolean',
+                        "You can set it to 'true' or 'false'")
+    elif isinstance(value, coredata.UserIntegerOption):
+        describe_option(name,
+                        str(value.value),
+                        'integer',
+                        "You can set it to any integer value between '{}' and '{}'".format(value.min_value, value.max_value))
+    elif isinstance(value, coredata.UserUmaskOption):
+        describe_option(name,
+                        str(value.value),
+                        'umask',
+                        "You can set it to 'preserve' or a value between '0000' and '0777'")
+    elif isinstance(value, coredata.UserComboOption):
+        choices = '[' + ', '.join(["'" + v + "'" for v in value.choices]) + ']'
+        describe_option(name,
+                        value.value,
+                        'combo',
+                        "You can set it to any one of those values: " + choices)
+    elif isinstance(value, coredata.UserArrayOption):
+        choices = '[' + ', '.join(["'" + v + "'" for v in value.choices]) + ']'
+        value = '[' + ', '.join(["'" + v + "'" for v in value.value]) + ']'
+        describe_option(name,
+                        value,
+                        'array',
+                        "You can set it to one or more of those values: " + choices)
+    elif isinstance(value, coredata.UserFeatureOption):
+        describe_option(name,
+                        value.value,
+                        'feature',
+                        "You can set it to 'auto', 'enabled', or 'disabled'")
+    else:
+        print(name + ' is an option of a type unknown to this script')
+        print('---')

mesa 3D driver/bin/meson.build

@@ -0,0 +1,23 @@
+# Copyright © 2017 Eric Engestrom
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+git_sha1_gen_py = files('git_sha1_gen.py')
+symbols_check = find_program('symbols-check.py')
+install_megadrivers_py = find_program('install_megadrivers.py')

mesa 3D driver/bin/meson_get_version.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+# encoding=utf-8
+# Copyright © 2017 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import print_function
+import os
+
+
+def main():
+    filename = os.path.join(os.environ['MESON_SOURCE_ROOT'], 'VERSION')
+    with open(filename) as f:
+        version = f.read().strip()
+    print(version, end='')
+
+
+if __name__ == '__main__':
+    main()

mesa 3D driver/bin/perf-annotate-jit.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python
+#
+# Copyright 2012 VMware Inc
+# Copyright 2008-2009 Jose Fonseca
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+
+"""Perf annotate for JIT code.
+
+Linux `perf annotate` does not work with JIT code.  This script takes the data
+produced by `perf script` command, plus the diassemblies outputed by gallivm
+into /tmp/perf-XXXXX.map.asm and produces output similar to `perf annotate`.
+
+See docs/llvmpipe.rst for usage instructions.
+
+The `perf script` output parser was derived from the gprof2dot.py script.
+"""
+
+
+import sys
+import os.path
+import re
+import optparse
+import subprocess
+
+
+class Parser:
+    """Parser interface."""
+
+    def __init__(self):
+        pass
+
+    def parse(self):
+        raise NotImplementedError
+
+
+class LineParser(Parser):
+    """Base class for parsers that read line-based formats."""
+
+    def __init__(self, file):
+        Parser.__init__(self)
+        self._file = file
+        self.__line = None
+        self.__eof = False
+        self.line_no = 0
+
+    def readline(self):
+        line = self._file.readline()
+        if not line:
+            self.__line = ''
+            self.__eof = True
+        else:
+            self.line_no += 1
+        self.__line = line.rstrip('\r\n')
+
+    def lookahead(self):
+        assert self.__line is not None
+        return self.__line
+
+    def consume(self):
+        assert self.__line is not None
+        line = self.__line
+        self.readline()
+        return line
+
+    def eof(self):
+        assert self.__line is not None
+        return self.__eof
+
+
+mapFile = None
+
+def lookupMap(filename, matchSymbol):
+    global mapFile
+    mapFile = filename
+    stream = open(filename, 'rt')
+    for line in stream:
+        start, length, symbol = line.split()
+
+        start = int(start, 16)
+        length = int(length,16)
+
+        if symbol == matchSymbol:
+            return start
+
+    return None
+
+def lookupAsm(filename, desiredFunction):
+    stream = open(filename + '.asm', 'rt')
+    while stream.readline() != desiredFunction + ':\n':
+        pass
+
+    asm = []
+    line = stream.readline().strip()
+    while line:
+        addr, instr = line.split(':', 1)
+        addr = int(addr)
+        asm.append((addr, instr))
+        line = stream.readline().strip()
+
+    return asm
+
+
+
+samples = {}
+
+
+class PerfParser(LineParser):
+    """Parser for linux perf callgraph output.
+
+    It expects output generated with
+
+        perf record -g
+        perf script
+    """
+
+    def __init__(self, infile, symbol):
+        LineParser.__init__(self, infile)
+        self.symbol = symbol
+
+    def readline(self):
+        # Override LineParser.readline to ignore comment lines
+        while True:
+            LineParser.readline(self)
+            if self.eof() or not self.lookahead().startswith('#'):
+                break
+
+    def parse(self):
+        # read lookahead
+        self.readline()
+
+        while not self.eof():
+            self.parse_event()
+
+        asm = lookupAsm(mapFile, self.symbol)
+
+        addresses = samples.keys()
+        addresses.sort()
+        total_samples = 0
+
+        sys.stdout.write('%s:\n' % self.symbol)
+        for address, instr in asm:
+            try:
+                sample = samples.pop(address)
+            except KeyError:
+                sys.stdout.write(6*' ')
+            else:
+                sys.stdout.write('%6u' % (sample))
+                total_samples += sample
+            sys.stdout.write('%6u: %s\n' % (address, instr))
+        print 'total:', total_samples
+        assert len(samples) == 0
+
+        sys.exit(0)
+
+    def parse_event(self):
+        if self.eof():
+            return
+
+        line = self.consume()
+        assert line
+
+        callchain = self.parse_callchain()
+        if not callchain:
+            return
+
+    def parse_callchain(self):
+        callchain = []
+        while self.lookahead():
+            function = self.parse_call(len(callchain) == 0)
+            if function is None:
+                break
+            callchain.append(function)
+        if self.lookahead() == '':
+            self.consume()
+        return callchain
+
+    call_re = re.compile(r'^\s+(?P<address>[0-9a-fA-F]+)\s+(?P<symbol>.*)\s+\((?P<module>[^)]*)\)$')
+
+    def parse_call(self, first):
+        line = self.consume()
+        mo = self.call_re.match(line)
+        assert mo
+        if not mo:
+            return None
+
+        if not first:
+            return None
+
+        function_name = mo.group('symbol')
+        if not function_name:
+            function_name = mo.group('address')
+
+        module = mo.group('module')
+
+        function_id = function_name + ':' + module
+
+        address = mo.group('address')
+        address = int(address, 16)
+
+        if function_name != self.symbol:
+            return None
+
+        start_address = lookupMap(module, function_name)
+        address -= start_address
+
+        #print function_name, module, address
+
+        samples[address] = samples.get(address, 0) + 1
+
+        return True
+
+
+def main():
+    """Main program."""
+
+    optparser = optparse.OptionParser(
+        usage="\n\t%prog [options] symbol_name")
+    (options, args) = optparser.parse_args(sys.argv[1:])
+    if len(args) != 1:
+        optparser.error('wrong number of arguments')
+
+    symbol = args[0]
+
+    p = subprocess.Popen(['perf', 'script'], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    parser = PerfParser(p.stdout, symbol)
+    parser.parse()
+
+
+if __name__ == '__main__':
+    main()
+
+
+# vim: set sw=4 et:

mesa 3D driver/bin/pick-ui.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+import asyncio
+
+import urwid
+
+from pick.ui import UI, PALETTE
+
+if __name__ == "__main__":
+    u = UI()
+    evl = urwid.AsyncioEventLoop(loop=asyncio.get_event_loop())
+    loop = urwid.MainLoop(u.render(), PALETTE, event_loop=evl, handle_mouse=False)
+    u.mainloop = loop
+    loop.run()

mesa 3D driver/bin/pick/core.py

@@ -0,0 +1,379 @@
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Core data structures and routines for pick."""
+
+import asyncio
+import enum
+import json
+import pathlib
+import re
+import subprocess
+import typing
+
+import attr
+
+if typing.TYPE_CHECKING:
+    from .ui import UI
+
+    import typing_extensions
+
+    class CommitDict(typing_extensions.TypedDict):
+
+        sha: str
+        description: str
+        nominated: bool
+        nomination_type: typing.Optional[int]
+        resolution: typing.Optional[int]
+        main_sha: typing.Optional[str]
+        because_sha: typing.Optional[str]
+
+IS_FIX = re.compile(r'^\s*fixes:\s*([a-f0-9]{6,40})', flags=re.MULTILINE | re.IGNORECASE)
+# FIXME: I dislike the duplication in this regex, but I couldn't get it to work otherwise
+IS_CC = re.compile(r'^\s*cc:\s*["\']?([0-9]{2}\.[0-9])?["\']?\s*["\']?([0-9]{2}\.[0-9])?["\']?\s*\<?mesa-stable',
+                   flags=re.MULTILINE | re.IGNORECASE)
+IS_REVERT = re.compile(r'This reverts commit ([0-9a-f]{40})')
+
+# XXX: hack
+SEM = asyncio.Semaphore(50)
+
+COMMIT_LOCK = asyncio.Lock()
+
+git_toplevel = subprocess.check_output(['git', 'rev-parse', '--show-toplevel'],
+                                       stderr=subprocess.DEVNULL).decode("ascii").strip()
+pick_status_json = pathlib.Path(git_toplevel) / '.pick_status.json'
+
+
+class PickUIException(Exception):
+    pass
+
+
+@enum.unique
+class NominationType(enum.Enum):
+
+    CC = 0
+    FIXES = 1
+    REVERT = 2
+
+
+@enum.unique
+class Resolution(enum.Enum):
+
+    UNRESOLVED = 0
+    MERGED = 1
+    DENOMINATED = 2
+    BACKPORTED = 3
+    NOTNEEDED = 4
+
+
+async def commit_state(*, amend: bool = False, message: str = 'Update') -> bool:
+    """Commit the .pick_status.json file."""
+    async with COMMIT_LOCK:
+        p = await asyncio.create_subprocess_exec(
+            'git', 'add', pick_status_json.as_posix(),
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        v = await p.wait()
+        if v != 0:
+            return False
+
+        if amend:
+            cmd = ['--amend', '--no-edit']
+        else:
+            cmd = ['--message', f'.pick_status.json: {message}']
+        p = await asyncio.create_subprocess_exec(
+            'git', 'commit', *cmd,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        v = await p.wait()
+        if v != 0:
+            return False
+    return True
+
+
+@attr.s(slots=True)
+class Commit:
+
+    sha: str = attr.ib()
+    description: str = attr.ib()
+    nominated: bool = attr.ib(False)
+    nomination_type: typing.Optional[NominationType] = attr.ib(None)
+    resolution: Resolution = attr.ib(Resolution.UNRESOLVED)
+    main_sha: typing.Optional[str] = attr.ib(None)
+    because_sha: typing.Optional[str] = attr.ib(None)
+
+    def to_json(self) -> 'CommitDict':
+        d: typing.Dict[str, typing.Any] = attr.asdict(self)
+        if self.nomination_type is not None:
+            d['nomination_type'] = self.nomination_type.value
+        if self.resolution is not None:
+            d['resolution'] = self.resolution.value
+        return typing.cast('CommitDict', d)
+
+    @classmethod
+    def from_json(cls, data: 'CommitDict') -> 'Commit':
+        c = cls(data['sha'], data['description'], data['nominated'], main_sha=data['main_sha'], because_sha=data['because_sha'])
+        if data['nomination_type'] is not None:
+            c.nomination_type = NominationType(data['nomination_type'])
+        if data['resolution'] is not None:
+            c.resolution = Resolution(data['resolution'])
+        return c
+
+    async def apply(self, ui: 'UI') -> typing.Tuple[bool, str]:
+        # FIXME: This isn't really enough if we fail to cherry-pick because the
+        # git tree will still be dirty
+        async with COMMIT_LOCK:
+            p = await asyncio.create_subprocess_exec(
+                'git', 'cherry-pick', '-x', self.sha,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, err = await p.communicate()
+
+        if p.returncode != 0:
+            return (False, err.decode())
+
+        self.resolution = Resolution.MERGED
+        await ui.feedback(f'{self.sha} ({self.description}) applied successfully')
+
+        # Append the changes to the .pickstatus.json file
+        ui.save()
+        v = await commit_state(amend=True)
+        return (v, '')
+
+    async def abort_cherry(self, ui: 'UI', err: str) -> None:
+        await ui.feedback(f'{self.sha} ({self.description}) failed to apply\n{err}')
+        async with COMMIT_LOCK:
+            p = await asyncio.create_subprocess_exec(
+                'git', 'cherry-pick', '--abort',
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+            )
+            r = await p.wait()
+        await ui.feedback(f'{"Successfully" if r == 0 else "Failed to"} abort cherry-pick.')
+
+    async def denominate(self, ui: 'UI') -> bool:
+        self.resolution = Resolution.DENOMINATED
+        ui.save()
+        v = await commit_state(message=f'Mark {self.sha} as denominated')
+        assert v
+        await ui.feedback(f'{self.sha} ({self.description}) denominated successfully')
+        return True
+
+    async def backport(self, ui: 'UI') -> bool:
+        self.resolution = Resolution.BACKPORTED
+        ui.save()
+        v = await commit_state(message=f'Mark {self.sha} as backported')
+        assert v
+        await ui.feedback(f'{self.sha} ({self.description}) backported successfully')
+        return True
+
+    async def resolve(self, ui: 'UI') -> None:
+        self.resolution = Resolution.MERGED
+        ui.save()
+        v = await commit_state(amend=True)
+        assert v
+        await ui.feedback(f'{self.sha} ({self.description}) committed successfully')
+
+
+async def get_new_commits(sha: str) -> typing.List[typing.Tuple[str, str]]:
+    # Try to get the authoritative upstream main
+    p = await asyncio.create_subprocess_exec(
+        'git', 'for-each-ref', '--format=%(upstream)', 'refs/heads/main',
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL)
+    out, _ = await p.communicate()
+    upstream = out.decode().strip()
+
+    p = await asyncio.create_subprocess_exec(
+        'git', 'log', '--pretty=oneline', f'{sha}..{upstream}',
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL)
+    out, _ = await p.communicate()
+    assert p.returncode == 0, f"git log didn't work: {sha}"
+    return list(split_commit_list(out.decode().strip()))
+
+
+def split_commit_list(commits: str) -> typing.Generator[typing.Tuple[str, str], None, None]:
+    if not commits:
+        return
+    for line in commits.split('\n'):
+        v = tuple(line.split(' ', 1))
+        assert len(v) == 2, 'this is really just for mypy'
+        yield typing.cast(typing.Tuple[str, str], v)
+
+
+async def is_commit_in_branch(sha: str) -> bool:
+    async with SEM:
+        p = await asyncio.create_subprocess_exec(
+            'git', 'merge-base', '--is-ancestor', sha, 'HEAD',
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await p.wait()
+    return p.returncode == 0
+
+
+async def full_sha(sha: str) -> str:
+    async with SEM:
+        p = await asyncio.create_subprocess_exec(
+            'git', 'rev-parse', sha,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        out, _ = await p.communicate()
+    if p.returncode:
+        raise PickUIException(f'Invalid Sha {sha}')
+    return out.decode().strip()
+
+
+async def resolve_nomination(commit: 'Commit', version: str) -> 'Commit':
+    async with SEM:
+        p = await asyncio.create_subprocess_exec(
+            'git', 'log', '--format=%B', '-1', commit.sha,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        _out, _ = await p.communicate()
+        assert p.returncode == 0, f'git log for {commit.sha} failed'
+    out = _out.decode()
+
+    # We give precedence to fixes and cc tags over revert tags.
+    # XXX: not having the walrus operator available makes me sad :=
+    m = IS_FIX.search(out)
+    if m:
+        # We set the nomination_type and because_sha here so that we can later
+        # check to see if this fixes another staged commit.
+        try:
+            commit.because_sha = fixed = await full_sha(m.group(1))
+        except PickUIException:
+            pass
+        else:
+            commit.nomination_type = NominationType.FIXES
+            if await is_commit_in_branch(fixed):
+                commit.nominated = True
+                return commit
+
+    m = IS_CC.search(out)
+    if m:
+        if m.groups() == (None, None) or version in m.groups():
+            commit.nominated = True
+            commit.nomination_type = NominationType.CC
+            return commit
+
+    m = IS_REVERT.search(out)
+    if m:
+        # See comment for IS_FIX path
+        try:
+            commit.because_sha = reverted = await full_sha(m.group(1))
+        except PickUIException:
+            pass
+        else:
+            commit.nomination_type = NominationType.REVERT
+            if await is_commit_in_branch(reverted):
+                commit.nominated = True
+                return commit
+
+    return commit
+
+
+async def resolve_fixes(commits: typing.List['Commit'], previous: typing.List['Commit']) -> None:
+    """Determine if any of the undecided commits fix/revert a staged commit.
+
+    The are still needed if they apply to a commit that is staged for
+    inclusion, but not yet included.
+
+    This must be done in order, because a commit 3 might fix commit 2 which
+    fixes commit 1.
+    """
+    shas: typing.Set[str] = set(c.sha for c in previous if c.nominated)
+    assert None not in shas, 'None in shas'
+
+    for commit in reversed(commits):
+        if not commit.nominated and commit.nomination_type is NominationType.FIXES:
+            commit.nominated = commit.because_sha in shas
+
+        if commit.nominated:
+            shas.add(commit.sha)
+
+    for commit in commits:
+        if (commit.nomination_type is NominationType.REVERT and
+                commit.because_sha in shas):
+            for oldc in reversed(commits):
+                if oldc.sha == commit.because_sha:
+                    # In this case a commit that hasn't yet been applied is
+                    # reverted, we don't want to apply that commit at all
+                    oldc.nominated = False
+                    oldc.resolution = Resolution.DENOMINATED
+                    commit.nominated = False
+                    commit.resolution = Resolution.DENOMINATED
+                    shas.remove(commit.because_sha)
+                    break
+
+
+async def gather_commits(version: str, previous: typing.List['Commit'],
+                         new: typing.List[typing.Tuple[str, str]], cb) -> typing.List['Commit']:
+    # We create an array of the final size up front, then we pass that array
+    # to the "inner" co-routine, which is turned into a list of tasks and
+    # collected by asyncio.gather. We do this to allow the tasks to be
+    # asynchronously gathered, but to also ensure that the commits list remains
+    # in order.
+    m_commits: typing.List[typing.Optional['Commit']] = [None] * len(new)
+    tasks = []
+
+    async def inner(commit: 'Commit', version: str,
+                    commits: typing.List[typing.Optional['Commit']],
+                    index: int, cb) -> None:
+        commits[index] = await resolve_nomination(commit, version)
+        cb()
+
+    for i, (sha, desc) in enumerate(new):
+        tasks.append(asyncio.ensure_future(
+            inner(Commit(sha, desc), version, m_commits, i, cb)))
+
+    await asyncio.gather(*tasks)
+    assert None not in m_commits
+    commits = typing.cast(typing.List[Commit], m_commits)
+
+    await resolve_fixes(commits, previous)
+
+    for commit in commits:
+        if commit.resolution is Resolution.UNRESOLVED and not commit.nominated:
+            commit.resolution = Resolution.NOTNEEDED
+
+    return commits
+
+
+def load() -> typing.List['Commit']:
+    if not pick_status_json.exists():
+        return []
+    with pick_status_json.open('r') as f:
+        raw = json.load(f)
+        return [Commit.from_json(c) for c in raw]
+
+
+def save(commits: typing.Iterable['Commit']) -> None:
+    commits = list(commits)
+    with pick_status_json.open('wt') as f:
+        json.dump([c.to_json() for c in commits], f, indent=4)
+
+    asyncio.ensure_future(commit_state(message=f'Update to {commits[0].sha}'))

mesa 3D driver/bin/pick/core_test.py

@@ -0,0 +1,470 @@
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Tests for pick's core data structures and routines."""
+
+from unittest import mock
+import textwrap
+import typing
+
+import attr
+import pytest
+
+from . import core
+
+
+class TestCommit:
+
+    @pytest.fixture
+    def unnominated_commit(self) -> 'core.Commit':
+        return core.Commit('abc123', 'sub: A commit', main_sha='45678')
+
+    @pytest.fixture
+    def nominated_commit(self) -> 'core.Commit':
+        return core.Commit('abc123', 'sub: A commit', True,
+                           core.NominationType.CC, core.Resolution.UNRESOLVED)
+
+    class TestToJson:
+
+        def test_not_nominated(self, unnominated_commit: 'core.Commit'):
+            c = unnominated_commit
+            v = c.to_json()
+            assert v == {'sha': 'abc123', 'description': 'sub: A commit', 'nominated': False,
+                         'nomination_type': None, 'resolution': core.Resolution.UNRESOLVED.value,
+                         'main_sha': '45678', 'because_sha': None}
+
+        def test_nominated(self, nominated_commit: 'core.Commit'):
+            c = nominated_commit
+            v = c.to_json()
+            assert v == {'sha': 'abc123',
+                         'description': 'sub: A commit',
+                         'nominated': True,
+                         'nomination_type': core.NominationType.CC.value,
+                         'resolution': core.Resolution.UNRESOLVED.value,
+                         'main_sha': None,
+                         'because_sha': None}
+
+    class TestFromJson:
+
+        def test_not_nominated(self, unnominated_commit: 'core.Commit'):
+            c = unnominated_commit
+            v = c.to_json()
+            c2 = core.Commit.from_json(v)
+            assert c == c2
+
+        def test_nominated(self, nominated_commit: 'core.Commit'):
+            c = nominated_commit
+            v = c.to_json()
+            c2 = core.Commit.from_json(v)
+            assert c == c2
+
+
+class TestRE:
+
+    """Tests for the regular expressions used to identify commits."""
+
+    class TestFixes:
+
+        def test_simple(self):
+            message = textwrap.dedent("""\
+                etnaviv: fix vertex buffer state emission for single stream GPUs
+
+                GPUs with a single supported vertex stream must use the single state
+                address to program the stream.
+
+                Fixes: 3d09bb390a39 (etnaviv: GC7000: State changes for HALTI3..5)
+                Signed-off-by: Lucas Stach <l.stach@pengutronix.de>
+                Reviewed-by: Jonathan Marek <jonathan@marek.ca>
+            """)
+
+            m = core.IS_FIX.search(message)
+            assert m is not None
+            assert m.group(1) == '3d09bb390a39'
+
+    class TestCC:
+
+        def test_single_branch(self):
+            """Tests commit meant for a single branch, ie, 19.1"""
+            message = textwrap.dedent("""\
+                radv: fix DCC fast clear code for intensity formats
+
+                This fixes a rendering issue with DiRT 4 on GFX10. Only GFX10 was
+                affected because intensity formats are different.
+
+                Cc: 19.2 <mesa-stable@lists.freedesktop.org>
+                Closes: https://gitlab.freedesktop.org/mesa/mesa/-/issues/1923
+                Signed-off-by: Samuel Pitoiset <samuel.pitoiset@gmail.com>
+                Reviewed-by: Bas Nieuwenhuizen <bas@basnieuwenhuizen.nl>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '19.2'
+
+        def test_multiple_branches(self):
+            """Tests commit with more than one branch specified"""
+            message = textwrap.dedent("""\
+                radeonsi: enable zerovram for Rocket League
+
+                Fixes corruption on game startup.
+                Closes: https://gitlab.freedesktop.org/mesa/mesa/-/issues/1888
+
+                Cc: 19.1 19.2 <mesa-stable@lists.freedesktop.org>
+                Reviewed-by: Pierre-Eric Pelloux-Prayer <pierre-eric.pelloux-prayer@amd.com>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '19.1'
+            assert m.group(2) == '19.2'
+
+        def test_no_branch(self):
+            """Tests commit with no branch specification"""
+            message = textwrap.dedent("""\
+                anv/android: fix images created with external format support
+
+                This fixes a case where user first creates image and then later binds it
+                with memory created from AHW buffer.
+
+                Cc: <mesa-stable@lists.freedesktop.org>
+                Signed-off-by: Tapani Pälli <tapani.palli@intel.com>
+                Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+
+        def test_quotes(self):
+            """Tests commit with quotes around the versions"""
+            message = textwrap.dedent("""\
+                 anv: Always fill out the AUX table even if CCS is disabled
+
+                 Cc: "20.0" mesa-stable@lists.freedesktop.org
+                 Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
+                 Tested-by: Marge Bot <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+                 Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '20.0'
+
+        def test_multiple_quotes(self):
+            """Tests commit with quotes around the versions"""
+            message = textwrap.dedent("""\
+                 anv: Always fill out the AUX table even if CCS is disabled
+
+                 Cc: "20.0" "20.1" mesa-stable@lists.freedesktop.org
+                 Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
+                 Tested-by: Marge Bot <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+                 Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '20.0'
+            assert m.group(2) == '20.1'
+
+        def test_single_quotes(self):
+            """Tests commit with quotes around the versions"""
+            message = textwrap.dedent("""\
+                 anv: Always fill out the AUX table even if CCS is disabled
+
+                 Cc: '20.0' mesa-stable@lists.freedesktop.org
+                 Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
+                 Tested-by: Marge Bot <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+                 Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '20.0'
+
+        def test_multiple_single_quotes(self):
+            """Tests commit with quotes around the versions"""
+            message = textwrap.dedent("""\
+                 anv: Always fill out the AUX table even if CCS is disabled
+
+                 Cc: '20.0' '20.1' mesa-stable@lists.freedesktop.org
+                 Reviewed-by: Kenneth Graunke <kenneth@whitecape.org>
+                 Tested-by: Marge Bot <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+                 Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/3454>
+            """)
+
+            m = core.IS_CC.search(message)
+            assert m is not None
+            assert m.group(1) == '20.0'
+            assert m.group(2) == '20.1'
+
+    class TestRevert:
+
+        def test_simple(self):
+            message = textwrap.dedent("""\
+                Revert "radv: do not emit PKT3_CONTEXT_CONTROL with AMDGPU 3.6.0+"
+
+                This reverts commit 2ca8629fa9b303e24783b76a7b3b0c2513e32fbd.
+
+                This was initially ported from RadeonSI, but in the meantime it has
+                been reverted because it might hang. Be conservative and re-introduce
+                this packet emission.
+
+                Unfortunately this doesn't fix anything known.
+
+                Cc: 19.2 <mesa-stable@lists.freedesktop.org>
+                Signed-off-by: Samuel Pitoiset <samuel.pitoiset@gmail.com>
+                Reviewed-by: Bas Nieuwenhuizen <bas@basnieuwenhuizen.nl>
+            """)
+
+            m = core.IS_REVERT.search(message)
+            assert m is not None
+            assert m.group(1) == '2ca8629fa9b303e24783b76a7b3b0c2513e32fbd'
+
+
+class TestResolveNomination:
+
+    @attr.s(slots=True)
+    class FakeSubprocess:
+
+        """A fake asyncio.subprocess like classe for use with mock."""
+
+        out: typing.Optional[bytes] = attr.ib(None)
+        returncode: int = attr.ib(0)
+
+        async def mock(self, *_, **__):
+            """A dirtly little helper for mocking."""
+            return self
+
+        async def communicate(self) -> typing.Tuple[bytes, bytes]:
+            assert self.out is not None
+            return self.out, b''
+
+        async def wait(self) -> int:
+            return self.returncode
+
+    @staticmethod
+    async def return_true(*_, **__) -> bool:
+        return True
+
+    @staticmethod
+    async def return_false(*_, **__) -> bool:
+        return False
+
+    @pytest.mark.asyncio
+    async def test_fix_is_nominated(self):
+        s = self.FakeSubprocess(b'Fixes: 3d09bb390a39 (etnaviv: GC7000: State changes for HALTI3..5)')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_true):
+                await core.resolve_nomination(c, '')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.FIXES
+
+    @pytest.mark.asyncio
+    async def test_fix_is_not_nominated(self):
+        s = self.FakeSubprocess(b'Fixes: 3d09bb390a39 (etnaviv: GC7000: State changes for HALTI3..5)')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_false):
+                await core.resolve_nomination(c, '')
+
+        assert not c.nominated
+        assert c.nomination_type is core.NominationType.FIXES
+
+    @pytest.mark.asyncio
+    async def test_cc_is_nominated(self):
+        s = self.FakeSubprocess(b'Cc: 16.2 <mesa-stable@lists.freedesktop.org>')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            await core.resolve_nomination(c, '16.2')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.CC
+
+    @pytest.mark.asyncio
+    async def test_cc_is_nominated2(self):
+        s = self.FakeSubprocess(b'Cc: mesa-stable@lists.freedesktop.org')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            await core.resolve_nomination(c, '16.2')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.CC
+
+    @pytest.mark.asyncio
+    async def test_cc_is_not_nominated(self):
+        s = self.FakeSubprocess(b'Cc: 16.2 <mesa-stable@lists.freedesktop.org>')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            await core.resolve_nomination(c, '16.1')
+
+        assert not c.nominated
+        assert c.nomination_type is None
+
+    @pytest.mark.asyncio
+    async def test_revert_is_nominated(self):
+        s = self.FakeSubprocess(b'This reverts commit 1234567890123456789012345678901234567890.')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_true):
+                await core.resolve_nomination(c, '')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.REVERT
+
+    @pytest.mark.asyncio
+    async def test_revert_is_not_nominated(self):
+        s = self.FakeSubprocess(b'This reverts commit 1234567890123456789012345678901234567890.')
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_false):
+                await core.resolve_nomination(c, '')
+
+        assert not c.nominated
+        assert c.nomination_type is core.NominationType.REVERT
+
+    @pytest.mark.asyncio
+    async def test_is_fix_and_cc(self):
+        s = self.FakeSubprocess(
+            b'Fixes: 3d09bb390a39 (etnaviv: GC7000: State changes for HALTI3..5)\n'
+            b'Cc: 16.1 <mesa-stable@lists.freedesktop.org>'
+        )
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_true):
+                await core.resolve_nomination(c, '16.1')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.FIXES
+
+    @pytest.mark.asyncio
+    async def test_is_fix_and_revert(self):
+        s = self.FakeSubprocess(
+            b'Fixes: 3d09bb390a39 (etnaviv: GC7000: State changes for HALTI3..5)\n'
+            b'This reverts commit 1234567890123456789012345678901234567890.'
+        )
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_true):
+                await core.resolve_nomination(c, '16.1')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.FIXES
+
+    @pytest.mark.asyncio
+    async def test_is_cc_and_revert(self):
+        s = self.FakeSubprocess(
+            b'This reverts commit 1234567890123456789012345678901234567890.\n'
+            b'Cc: 16.1 <mesa-stable@lists.freedesktop.org>'
+        )
+        c = core.Commit('abcdef1234567890', 'a commit')
+
+        with mock.patch('bin.pick.core.asyncio.create_subprocess_exec', s.mock):
+            with mock.patch('bin.pick.core.is_commit_in_branch', self.return_true):
+                await core.resolve_nomination(c, '16.1')
+
+        assert c.nominated
+        assert c.nomination_type is core.NominationType.CC
+
+
+class TestResolveFixes:
+
+    @pytest.mark.asyncio
+    async def test_in_new(self):
+        """Because commit abcd is nominated, so f123 should be as well."""
+        c = [
+            core.Commit('f123', 'desc', nomination_type=core.NominationType.FIXES, because_sha='abcd'),
+            core.Commit('abcd', 'desc', True),
+        ]
+        await core.resolve_fixes(c, [])
+        assert c[1].nominated
+
+    @pytest.mark.asyncio
+    async def test_not_in_new(self):
+        """Because commit abcd is not nominated, commit f123 shouldn't be either."""
+        c = [
+            core.Commit('f123', 'desc', nomination_type=core.NominationType.FIXES, because_sha='abcd'),
+            core.Commit('abcd', 'desc'),
+        ]
+        await core.resolve_fixes(c, [])
+        assert not c[0].nominated
+
+    @pytest.mark.asyncio
+    async def test_in_previous(self):
+        """Because commit abcd is nominated, so f123 should be as well."""
+        p = [
+            core.Commit('abcd', 'desc', True),
+        ]
+        c = [
+            core.Commit('f123', 'desc', nomination_type=core.NominationType.FIXES, because_sha='abcd'),
+        ]
+        await core.resolve_fixes(c, p)
+        assert c[0].nominated
+
+    @pytest.mark.asyncio
+    async def test_not_in_previous(self):
+        """Because commit abcd is not nominated, commit f123 shouldn't be either."""
+        p = [
+            core.Commit('abcd', 'desc'),
+        ]
+        c = [
+            core.Commit('f123', 'desc', nomination_type=core.NominationType.FIXES, because_sha='abcd'),
+        ]
+        await core.resolve_fixes(c, p)
+        assert not c[0].nominated
+
+
+class TestIsCommitInBranch:
+
+    @pytest.mark.asyncio
+    async def test_no(self):
+        # Hopefully this is never true?
+        value = await core.is_commit_in_branch('ffffffffffffffffffffffffffffff')
+        assert not value
+
+    @pytest.mark.asyncio
+    async def test_yes(self):
+        # This commit is from 2000, it better always be in the branch
+        value = await core.is_commit_in_branch('88f3b89a2cb77766d2009b9868c44e03abe2dbb2')
+        assert value
+
+
+class TestFullSha:
+
+    @pytest.mark.asyncio
+    async def test_basic(self):
+        # This commit is from 2000, it better always be in the branch
+        value = await core.full_sha('88f3b89a2cb777')
+        assert value
+
+    @pytest.mark.asyncio
+    async def test_invalid(self):
+        # This commit is from 2000, it better always be in the branch
+        with pytest.raises(core.PickUIException):
+            await core.full_sha('fffffffffffffffffffffffffffffffffff')

mesa 3D driver/bin/pick/ui.py

@@ -0,0 +1,264 @@
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Urwid UI for pick script."""
+
+import asyncio
+import itertools
+import textwrap
+import typing
+
+import attr
+import urwid
+
+from . import core
+
+if typing.TYPE_CHECKING:
+    WidgetType = typing.TypeVar('WidgetType', bound=urwid.Widget)
+
+PALETTE = [
+    ('a', 'black', 'light gray'),
+    ('b', 'black', 'dark red'),
+    ('bg', 'black', 'dark blue'),
+    ('reversed', 'standout', ''),
+]
+
+
+class RootWidget(urwid.Frame):
+
+    def __init__(self, *args, ui: 'UI' = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        assert ui is not None
+        self.ui = ui
+
+    def keypress(self, size: int, key: str) -> typing.Optional[str]:
+        if key == 'q':
+            raise urwid.ExitMainLoop()
+        elif key == 'u':
+            asyncio.ensure_future(self.ui.update())
+        elif key == 'a':
+            self.ui.add()
+        else:
+            return super().keypress(size, key)
+        return None
+
+
+class CommitWidget(urwid.Text):
+
+    # urwid.Text is normally not interactable, this is required to tell urwid
+    # to use our keypress method
+    _selectable = True
+
+    def __init__(self, ui: 'UI', commit: 'core.Commit'):
+        super().__init__(f'{commit.sha[:10]} {commit.description}')
+        self.ui = ui
+        self.commit = commit
+
+    async def apply(self) -> None:
+        async with self.ui.git_lock:
+            result, err = await self.commit.apply(self.ui)
+            if not result:
+                self.ui.chp_failed(self, err)
+            else:
+                self.ui.remove_commit(self)
+
+    async def denominate(self) -> None:
+        async with self.ui.git_lock:
+            await self.commit.denominate(self.ui)
+            self.ui.remove_commit(self)
+
+    async def backport(self) -> None:
+        async with self.ui.git_lock:
+            await self.commit.backport(self.ui)
+            self.ui.remove_commit(self)
+
+    def keypress(self, size: int, key: str) -> typing.Optional[str]:
+        if key == 'c':
+            asyncio.ensure_future(self.apply())
+        elif key == 'd':
+            asyncio.ensure_future(self.denominate())
+        elif key == 'b':
+            asyncio.ensure_future(self.backport())
+        else:
+            return key
+        return None
+
+
+@attr.s(slots=True)
+class UI:
+
+    """Main management object.
+
+    :previous_commits: A list of commits to main since this branch was created
+    :new_commits: Commits added to main since the last time this script was run
+    """
+
+    commit_list: typing.List['urwid.Button'] = attr.ib(factory=lambda: urwid.SimpleFocusListWalker([]), init=False)
+    feedback_box: typing.List['urwid.Text'] = attr.ib(factory=lambda: urwid.SimpleFocusListWalker([]), init=False)
+    header: 'urwid.Text' = attr.ib(factory=lambda: urwid.Text('Mesa Stable Picker', align='center'), init=False)
+    body: 'urwid.Columns' = attr.ib(attr.Factory(lambda s: s._make_body(), True), init=False)
+    footer: 'urwid.Columns' = attr.ib(attr.Factory(lambda s: s._make_footer(), True), init=False)
+    root: RootWidget = attr.ib(attr.Factory(lambda s: s._make_root(), True), init=False)
+    mainloop: urwid.MainLoop = attr.ib(None, init=False)
+
+    previous_commits: typing.List['core.Commit'] = attr.ib(factory=list, init=False)
+    new_commits: typing.List['core.Commit'] = attr.ib(factory=list, init=False)
+    git_lock: asyncio.Lock = attr.ib(factory=asyncio.Lock, init=False)
+
+    def _make_body(self) -> 'urwid.Columns':
+        commits = urwid.ListBox(self.commit_list)
+        feedback = urwid.ListBox(self.feedback_box)
+        return urwid.Columns([commits, feedback])
+
+    def _make_footer(self) -> 'urwid.Columns':
+        body = [
+            urwid.Text('[U]pdate'),
+            urwid.Text('[Q]uit'),
+            urwid.Text('[C]herry Pick'),
+            urwid.Text('[D]enominate'),
+            urwid.Text('[B]ackport'),
+            urwid.Text('[A]pply additional patch')
+        ]
+        return urwid.Columns(body)
+
+    def _make_root(self) -> 'RootWidget':
+        return RootWidget(self.body, self.header, self.footer, 'body', ui=self)
+
+    def render(self) -> 'WidgetType':
+        asyncio.ensure_future(self.update())
+        return self.root
+
+    def load(self) -> None:
+        self.previous_commits = core.load()
+
+    async def update(self) -> None:
+        self.load()
+        with open('VERSION', 'r') as f:
+            version = '.'.join(f.read().split('.')[:2])
+        if self.previous_commits:
+            sha = self.previous_commits[0].sha
+        else:
+            sha = f'{version}-branchpoint'
+
+        new_commits = await core.get_new_commits(sha)
+
+        if new_commits:
+            pb = urwid.ProgressBar('a', 'b', done=len(new_commits))
+            o = self.mainloop.widget
+            self.mainloop.widget = urwid.Overlay(
+                urwid.Filler(urwid.LineBox(pb)), o, 'center', ('relative', 50), 'middle', ('relative', 50))
+            self.new_commits = await core.gather_commits(
+                version, self.previous_commits, new_commits,
+                lambda: pb.set_completion(pb.current + 1))
+            self.mainloop.widget = o
+
+        for commit in reversed(list(itertools.chain(self.new_commits, self.previous_commits))):
+            if commit.nominated and commit.resolution is core.Resolution.UNRESOLVED:
+                b = urwid.AttrMap(CommitWidget(self, commit), None, focus_map='reversed')
+                self.commit_list.append(b)
+        self.save()
+
+    async def feedback(self, text: str) -> None:
+        self.feedback_box.append(urwid.AttrMap(urwid.Text(text), None))
+        latest_item_index = len(self.feedback_box) - 1
+        self.feedback_box.set_focus(latest_item_index)
+
+    def remove_commit(self, commit: CommitWidget) -> None:
+        for i, c in enumerate(self.commit_list):
+            if c.base_widget is commit:
+                del self.commit_list[i]
+                break
+
+    def save(self):
+        core.save(itertools.chain(self.new_commits, self.previous_commits))
+
+    def add(self) -> None:
+        """Add an additional commit which isn't nominated."""
+        o = self.mainloop.widget
+
+        def reset_cb(_) -> None:
+            self.mainloop.widget = o
+
+        async def apply_cb(edit: urwid.Edit) -> None:
+            text: str = edit.get_edit_text()
+
+            # In case the text is empty
+            if not text:
+                return
+
+            sha = await core.full_sha(text)
+            for c in reversed(list(itertools.chain(self.new_commits, self.previous_commits))):
+                if c.sha == sha:
+                    commit = c
+                    break
+            else:
+                raise RuntimeError(f"Couldn't find {sha}")
+
+            await commit.apply(self)
+
+        q = urwid.Edit("Commit sha\n")
+        ok_btn = urwid.Button('Ok')
+        urwid.connect_signal(ok_btn, 'click', lambda _: asyncio.ensure_future(apply_cb(q)))
+        urwid.connect_signal(ok_btn, 'click', reset_cb)
+
+        can_btn = urwid.Button('Cancel')
+        urwid.connect_signal(can_btn, 'click', reset_cb)
+
+        cols = urwid.Columns([ok_btn, can_btn])
+        pile = urwid.Pile([q, cols])
+        box = urwid.LineBox(pile)
+
+        self.mainloop.widget = urwid.Overlay(
+            urwid.Filler(box), o, 'center', ('relative', 50), 'middle', ('relative', 50)
+        )
+
+    def chp_failed(self, commit: 'CommitWidget', err: str) -> None:
+        o = self.mainloop.widget
+
+        def reset_cb(_) -> None:
+            self.mainloop.widget = o
+
+        t = urwid.Text(textwrap.dedent(f"""
+            Failed to apply {commit.commit.sha} {commit.commit.description} with the following error:
+
+            {err}
+
+            You can either cancel, or resolve the conflicts (`git mergetool`), finish the
+            cherry-pick (`git cherry-pick --continue`) and select ok."""))
+
+        can_btn = urwid.Button('Cancel')
+        urwid.connect_signal(can_btn, 'click', reset_cb)
+        urwid.connect_signal(
+            can_btn, 'click', lambda _: asyncio.ensure_future(commit.commit.abort_cherry(self, err)))
+
+        ok_btn = urwid.Button('Ok')
+        urwid.connect_signal(ok_btn, 'click', reset_cb)
+        urwid.connect_signal(
+            ok_btn, 'click', lambda _: asyncio.ensure_future(commit.commit.resolve(self)))
+        urwid.connect_signal(
+            ok_btn, 'click', lambda _: self.remove_commit(commit))
+
+        cols = urwid.Columns([ok_btn, can_btn])
+        pile = urwid.Pile([t, cols])
+        box = urwid.LineBox(pile)
+
+        self.mainloop.widget = urwid.Overlay(
+            urwid.Filler(box), o, 'center', ('relative', 50), 'middle', ('relative', 50)
+        )

mesa 3D driver/bin/post_version.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# Copyright © 2019-2020 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Update the main page, release notes, and calendar."""
+
+import argparse
+import csv
+import pathlib
+import subprocess
+
+
+def update_release_notes(version: str) -> None:
+    p = pathlib.Path('docs') / 'relnotes.rst'
+
+    with open(p, 'r') as f:
+        relnotes = f.readlines()
+
+    new_relnotes = []
+    first_list = True
+    second_list = True
+    for line in relnotes:
+        if first_list and line.startswith('-'):
+            first_list = False
+            new_relnotes.append(f'-  :doc:`{version} release notes <relnotes/{version}>`\n')
+        if not first_list and second_list and line.startswith('   relnotes/'):
+            second_list = False
+            new_relnotes.append(f'   relnotes/{version}\n')
+        new_relnotes.append(line)
+
+    with open(p, 'w') as f:
+        for line in new_relnotes:
+            f.write(line)
+
+    subprocess.run(['git', 'add', p])
+
+
+def update_calendar(version: str) -> None:
+    p = pathlib.Path('docs') / 'release-calendar.csv'
+
+    with p.open('r') as f:
+        calendar = list(csv.reader(f))
+
+    branch = None
+    for i, line in enumerate(calendar):
+        if line[2] == version:
+            if line[0]:
+                branch = line[0]
+            break
+    if branch is not None:
+        calendar[i + 1][0] = branch
+    del calendar[i]
+
+    with p.open('w') as f:
+        writer = csv.writer(f)
+        writer.writerows(calendar)
+
+    subprocess.run(['git', 'add', p])
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument('version', help="The released version.")
+    args = parser.parse_args()
+
+    update_calendar(args.version)
+    done = 'update calendar'
+
+    if 'rc' not in args.version:
+        update_release_notes(args.version)
+        done += ' and link releases notes'
+
+    subprocess.run(['git', 'commit', '-m',
+                    f'docs: {done} for {args.version}'])
+
+
+if __name__ == "__main__":
+    main()

mesa 3D driver/bin/post_version_test.py

@@ -0,0 +1,67 @@
+# Copyright © 2019 Intel Corporation
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from unittest import mock
+
+import pytest
+
+from . import post_version
+
+
+@mock.patch('bin.post_version.subprocess.run', mock.Mock())
+class TestUpdateCalendar:
+
+    @pytest.fixture(autouse=True)
+    def mock_sideffects(self) -> None:
+        """Mock out side effects."""
+        with mock.patch('bin.post_version.subprocess.run', mock.Mock()), \
+                mock.patch('bin.post_version.pathlib', mock.MagicMock()):
+            yield
+
+    def test_basic(self):
+        data = [
+            ['20.3', '2021-01-13', '20.3.3', 'Dylan Baker', None],
+            [None,   '2021-01-27', '20.3.4', 'Dylan Baker', None],
+        ]
+
+        m = mock.Mock()
+        with mock.patch('bin.post_version.csv.reader', mock.Mock(return_value=data.copy())), \
+                mock.patch('bin.post_version.csv.writer', mock.Mock(return_value=m)):
+            post_version.update_calendar('20.3.3')
+
+            m.writerows.assert_called_with([data[1]])
+
+    def test_two_releases(self):
+        data = [
+            ['20.3', '2021-01-13', '20.3.3', 'Dylan Baker', None],
+            [None,   '2021-01-27', '20.3.4', 'Dylan Baker', None],
+            ['21.0', '2021-01-13', '21.0.0', 'Dylan Baker', None],
+            [None,   '2021-01-13', '21.0.1', 'Dylan Baker', None],
+        ]
+
+        m = mock.Mock()
+        with mock.patch('bin.post_version.csv.reader', mock.Mock(return_value=data.copy())), \
+                mock.patch('bin.post_version.csv.writer', mock.Mock(return_value=m)):
+            post_version.update_calendar('20.3.3')
+
+            d = data.copy()
+            del d[0]
+            d[0][0] = '20.3'
+            m.writerows.assert_called_with(d)

mesa 3D driver/bin/symbols-check.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python
+
+import argparse
+import os
+import platform
+import subprocess
+
+# This list contains symbols that _might_ be exported for some platforms
+PLATFORM_SYMBOLS = [
+    '__bss_end__',
+    '__bss_start__',
+    '__bss_start',
+    '__cxa_guard_abort',
+    '__cxa_guard_acquire',
+    '__cxa_guard_release',
+    '__end__',
+    '__odr_asan._glapi_Context',
+    '__odr_asan._glapi_Dispatch',
+    '_bss_end__',
+    '_edata',
+    '_end',
+    '_fini',
+    '_init',
+]
+
+def get_symbols_nm(nm, lib):
+    '''
+    List all the (non platform-specific) symbols exported by the library
+    using `nm`
+    '''
+    symbols = []
+    platform_name = platform.system()
+    output = subprocess.check_output([nm, '-gP', lib],
+                                     stderr=open(os.devnull, 'w')).decode("ascii")
+    for line in output.splitlines():
+        fields = line.split()
+        if len(fields) == 2 or fields[1] == 'U':
+            continue
+        symbol_name = fields[0]
+        if platform_name == 'Linux':
+            if symbol_name in PLATFORM_SYMBOLS:
+                continue
+        elif platform_name == 'Darwin':
+            assert symbol_name[0] == '_'
+            symbol_name = symbol_name[1:]
+        symbols.append(symbol_name)
+    return symbols
+
+
+def get_symbols_dumpbin(dumpbin, lib):
+    '''
+    List all the (non platform-specific) symbols exported by the library
+    using `dumpbin`
+    '''
+    symbols = []
+    output = subprocess.check_output([dumpbin, '/exports', lib],
+                                     stderr=open(os.devnull, 'w')).decode("ascii")
+    for line in output.splitlines():
+        fields = line.split()
+        # The lines with the symbols are made of at least 4 columns; see details below
+        if len(fields) < 4:
+            continue
+        try:
+            # Making sure the first 3 columns are a dec counter, a hex counter
+            # and a hex address
+            _ = int(fields[0], 10)
+            _ = int(fields[1], 16)
+            _ = int(fields[2], 16)
+        except ValueError:
+            continue
+        symbol_name = fields[3]
+        # De-mangle symbols
+        if symbol_name[0] == '_':
+            symbol_name = symbol_name[1:].split('@')[0]
+        symbols.append(symbol_name)
+    return symbols
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--symbols-file',
+                        action='store',
+                        required=True,
+                        help='path to file containing symbols')
+    parser.add_argument('--lib',
+                        action='store',
+                        required=True,
+                        help='path to library')
+    parser.add_argument('--nm',
+                        action='store',
+                        help='path to binary (or name in $PATH)')
+    parser.add_argument('--dumpbin',
+                        action='store',
+                        help='path to binary (or name in $PATH)')
+    parser.add_argument('--ignore-symbol',
+                        action='append',
+                        help='do not process this symbol')
+    args = parser.parse_args()
+
+    try:
+        if platform.system() == 'Windows':
+            if not args.dumpbin:
+                parser.error('--dumpbin is mandatory')
+            lib_symbols = get_symbols_dumpbin(args.dumpbin, args.lib)
+        else:
+            if not args.nm:
+                parser.error('--nm is mandatory')
+            lib_symbols = get_symbols_nm(args.nm, args.lib)
+    except:
+        # We can't run this test, but we haven't technically failed it either
+        # Return the GNU "skip" error code
+        exit(77)
+    mandatory_symbols = []
+    optional_symbols = []
+    with open(args.symbols_file) as symbols_file:
+        qualifier_optional = '(optional)'
+        for line in symbols_file.readlines():
+
+            # Strip comments
+            line = line.split('#')[0]
+            line = line.strip()
+            if not line:
+                continue
+
+            # Line format:
+            # [qualifier] symbol
+            qualifier = None
+            symbol = None
+
+            fields = line.split()
+            if len(fields) == 1:
+                symbol = fields[0]
+            elif len(fields) == 2:
+                qualifier = fields[0]
+                symbol = fields[1]
+            else:
+                print(args.symbols_file + ': invalid format: ' + line)
+                exit(1)
+
+            # The only supported qualifier is 'optional', which means the
+            # symbol doesn't have to be exported by the library
+            if qualifier and not qualifier == qualifier_optional:
+                print(args.symbols_file + ': invalid qualifier: ' + qualifier)
+                exit(1)
+
+            if qualifier == qualifier_optional:
+                optional_symbols.append(symbol)
+            else:
+                mandatory_symbols.append(symbol)
+
+    unknown_symbols = []
+    for symbol in lib_symbols:
+        if symbol in mandatory_symbols:
+            continue
+        if symbol in optional_symbols:
+            continue
+        if args.ignore_symbol and symbol in args.ignore_symbol:
+            continue
+        if symbol[:2] == '_Z':
+            # As ajax found out, the compiler intentionally exports symbols
+            # that we explicitely asked it not to export, and we can't do
+            # anything about it:
+            # https://gcc.gnu.org/bugzilla/show_bug.cgi?id=36022#c4
+            continue
+        unknown_symbols.append(symbol)
+
+    missing_symbols = [
+        sym for sym in mandatory_symbols if sym not in lib_symbols
+    ]
+
+    for symbol in unknown_symbols:
+        print(args.lib + ': unknown symbol exported: ' + symbol)
+
+    for symbol in missing_symbols:
+        print(args.lib + ': missing symbol: ' + symbol)
+
+    if unknown_symbols or missing_symbols:
+        exit(1)
+    exit(0)
+
+
+if __name__ == '__main__':
+    main()

mesa 3D driver/bin/update-android-headers.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+
+set -eu
+
+if [ ! -e .git ]; then
+    echo must run from top-level directory;
+    exit 1
+fi
+
+if [ ! -d platform-hardware-libhardware ]; then
+    git clone --depth 1 https://android.googlesource.com/platform/hardware/libhardware platform-hardware-libhardware
+    git clone --depth 1 https://android.googlesource.com/platform/system/core platform-system-core
+    git clone --depth 1 https://android.googlesource.com/platform/frameworks/native platform-frameworks-native
+fi
+
+dest=include/android_stub
+
+rm -rf ${dest}
+mkdir ${dest}
+
+
+# These directories contains mostly only the files we need, so copy wholesale
+
+cp -av platform-frameworks-native/libs/nativewindow/include/vndk        \
+    platform-system-core/libsync/include/sync                           \
+    platform-system-core/libsync/include/ndk                            \
+    platform-system-core/libbacktrace/include/backtrace                 \
+    platform-system-core/libsystem/include/system                       \
+    platform-system-core/liblog/include/log                             \
+    platform-frameworks-native/libs/nativewindow/include/apex           \
+    platform-frameworks-native/libs/nativewindow/include/system         \
+    platform-frameworks-native/libs/nativebase/include/nativebase       \
+    ${dest}
+
+
+# We only need a few files from these big directories so just copy those
+
+mkdir ${dest}/hardware
+cp -av platform-hardware-libhardware/include/hardware/{hardware,gralloc,gralloc1,fb}.h ${dest}/hardware
+cp -av platform-frameworks-native/vulkan/include/hardware/hwvulkan.h ${dest}/hardware
+
+mkdir ${dest}/cutils
+cp -av platform-system-core/libcutils/include/cutils/{log,native_handle,properties}.h ${dest}/cutils
+
+
+# include/android has files from a few different projects
+
+mkdir ${dest}/android
+cp -av platform-frameworks-native/libs/nativewindow/include/android/*   \
+    platform-frameworks-native/libs/arect/include/android/*             \
+    platform-system-core/liblog/include/android/*                       \
+    platform-system-core/libsync/include/android/*                      \
+    ${dest}/android
+

mesa 3D driver/build-support/conftest.dyn

@@ -0,0 +1,3 @@
+{
+	radeon_drm_winsys_create;
+};

mesa 3D driver/build-support/conftest.map

@@ -0,0 +1,6 @@
+VERSION_1 {
+    global:
+        main;
+    local:
+        *;
+};

mesa 3D driver/docs/ARB_color_buffer_float.txt

@@ -0,0 +1,4 @@
+Known issues in the ARB_color_buffer_float implementation:
+- Rendering to multiple render targets, some fixed-point, some floating-point, with FIXED_ONLY fragment clamping and polygon smooth enabled may write incorrect values to the fixed point buffers (depends on spec interpretation)
+- For fragment programs with ARB_fog_* options, colors are clamped before fog application regardless of the fragment clamping setting (this depends on spec interpretation)
+

mesa 3D driver/docs/README.UVD

@@ -0,0 +1,44 @@
+The software may implement third party technologies (e.g. third party
+libraries) that are not licensed to you by AMD and for which you may need
+to obtain licenses from other parties.  Unless explicitly stated otherwise,
+these third party technologies are not licensed hereunder.  Such third
+party technologies include, but are not limited, to H.264, H.265, HEVC, MPEG-2,
+MPEG-4, AVC, and VC-1.
+
+For MPEG-2 Encoding Products ANY USE OF THIS PRODUCT IN ANY MANNER OTHER
+THAN PERSONAL USE THAT COMPLIES WITH THE MPEG-2 STANDARD FOR ENCODING VIDEO
+INFORMATION FOR PACKAGED MEDIA IS EXPRESSLY PROHIBITED WITHOUT A LICENSE
+UNDER APPLICABLE PATENTS IN THE MPEG-2 PATENT PORTFOLIO, WHICH LICENSES IS
+AVAILABLE FROM MPEG LA, LLC, 6312 S. Fiddlers Green Circle, Suite 400E,
+Greenwood Village, Colorado 80111 U.S.A.
+
+WARRANTY DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
+KIND.  AMD DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING
+BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL RUN
+UNINTERRUPTED OR ERROR-FREE OR WARRANTIES ARISING FROM CUSTOM OF TRADE OR
+COURSE OF USAGE.  THE ENTIRE RISK ASSOCIATED WITH THE USE OF THE SOFTWARE IS
+ASSUMED BY YOU.  Some jurisdictions do not allow the exclusion of implied
+warranties, so the above exclusion may not apply to You.
+
+LIMITATION OF LIABILITY AND INDEMNIFICATION:  AMD AND ITS LICENSORS WILL NOT,
+UNDER ANY CIRCUMSTANCES BE LIABLE FOR ANY PUNITIVE, DIRECT, INCIDENTAL,
+INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE OR
+THIS AGREEMENT EVEN IF AMD AND ITS LICENSORS HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.  In no event shall AMD's total liability to You
+for all damages, losses, and causes of action (whether in contract, tort
+(including negligence) or otherwise) exceed the amount of $100 USD.  You agree
+to defend, indemnify and hold harmless AMD and its licensors, and any of their
+directors, officers, employees, affiliates or agents from and against any and
+all loss, damage, liability and other expenses (including reasonable
+attorneys' fees), resulting from Your use of the Software or violation of the
+terms and conditions of this Agreement.
+
+U.S. GOVERNMENT RESTRICTED RIGHTS: The Software is provided with "RESTRICTED
+RIGHTS." Use, duplication, or disclosure by the Government is subject to the
+restrictions as set forth in FAR 52.227-14 and DFAR252.227-7013, et seq., or
+its successor.  Use of the Software by the Government constitutes
+acknowledgement of AMD's proprietary rights in them.
+
+EXPORT RESTRICTIONS: The Software may be subject to export restrictions as
+stated in the Software License Agreement.

mesa 3D driver/docs/README.VCE

@@ -0,0 +1,43 @@
+The software may implement third party technologies (e.g. third party
+libraries) that are not licensed to you by AMD and for which you may need
+to obtain licenses from other parties.  Unless explicitly stated otherwise,
+these third party technologies are not licensed hereunder.  Such third
+party technologies include, but are not limited, to H.264, MPEG-2, MPEG-4,
+AVC, and VC-1.  
+
+For MPEG-2 Intermediate Products: ANY USE OF THIS PRODUCT IN ANY MANNER OTHER
+THAN PERSONAL USE THAT COMPLIES WITH THE MPEG-2 STANDARD IS EXPRESSLY
+PROHIBITED WITHOUT A LICENSE UNDER APPLICABLE PATENTS IN THE MPEG-2 PATENT
+PORTFOLIO, WHICH LICENSES IS AVAILABLE FROM MPEG LA, LLC, 6312 S. Fiddlers
+Green Circle, Suite 400E, Greenwood Village, Colorado 80111 U.S.A.
+
+WARRANTY DISCLAIMER: THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
+KIND.  AMD DISCLAIMS ALL WARRANTIES, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING
+BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT, THAT THE SOFTWARE WILL RUN
+UNINTERRUPTED OR ERROR-FREE OR WARRANTIES ARISING FROM CUSTOM OF TRADE OR
+COURSE OF USAGE.  THE ENTIRE RISK ASSOCIATED WITH THE USE OF THE SOFTWARE IS
+ASSUMED BY YOU.  Some jurisdictions do not allow the exclusion of implied
+warranties, so the above exclusion may not apply to You.
+
+LIMITATION OF LIABILITY AND INDEMNIFICATION:  AMD AND ITS LICENSORS WILL NOT,
+UNDER ANY CIRCUMSTANCES BE LIABLE FOR ANY PUNITIVE, DIRECT, INCIDENTAL,
+INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM USE OF THE SOFTWARE OR
+THIS AGREEMENT EVEN IF AMD AND ITS LICENSORS HAVE BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.  In no event shall AMD's total liability to You
+for all damages, losses, and causes of action (whether in contract, tort
+(including negligence) or otherwise) exceed the amount of $100 USD.  You agree
+to defend, indemnify and hold harmless AMD and its licensors, and any of their
+directors, officers, employees, affiliates or agents from and against any and
+all loss, damage, liability and other expenses (including reasonable
+attorneys' fees), resulting from Your use of the Software or violation of the
+terms and conditions of this Agreement.
+
+U.S. GOVERNMENT RESTRICTED RIGHTS: The Software is provided with "RESTRICTED
+RIGHTS." Use, duplication, or disclosure by the Government is subject to the
+restrictions as set forth in FAR 52.227-14 and DFAR252.227-7013, et seq., or
+its successor.  Use of the Software by the Government constitutes
+acknowledgement of AMD's proprietary rights in them.
+
+EXPORT RESTRICTIONS: The Software may be subject to export restrictions as
+stated in the Software License Agreement.

mesa 3D driver/docs/_extra/specs/EGL_MESA_device_software.txt

@@ -0,0 +1,82 @@
+Name
+
+    MESA_device_software
+
+Name Strings
+
+    EGL_MESA_device_software
+
+Contributors
+
+    Adam Jackson <ajax@redhat.com>
+    Emil Velikov <emil.velikov@collabora.com>
+
+Contacts
+
+    Adam Jackson <ajax@redhat.com>
+
+Status
+
+    DRAFT
+
+Version
+
+    Version 2, 2018-10-03
+
+Number
+
+    EGL Extension #TODO
+
+Extension Type
+
+    EGL device extension
+
+Dependencies
+
+    Requires EGL_EXT_device_query.
+
+    This extension is written against the EGL 1.5 Specification.
+
+Overview
+
+    This extension defines a software EGL "device". The device is not backed by
+    any actual device node and simply renders into client memory.
+
+    By defining this as an extension, EGL_EXT_device_enumeration is able to
+    sanely enumerate a software device.
+
+New Types
+
+    None
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    None
+
+Additions to the EGL Specification
+
+    None
+
+New Behavior
+
+    The device list produced by eglQueryDevicesEXT will include a software
+    device. This can be distinguished from other device classes in the usual
+    way by calling eglQueryDeviceStringEXT(EGL_EXTENSIONS) and matching this
+    extension's string in the result.
+
+Issues
+
+    None
+
+Revision History
+
+    Version 2, 2018-10-03 (Emil Velikov)
+        - Drop "fallback" from "software fallback device"
+        - Add Emil Velikov as contributor
+
+    Version 1, 2017-07-06 (Adam Jackson)
+        - Initial version

mesa 3D driver/docs/_extra/specs/EGL_MESA_drm_image_formats.txt

@@ -0,0 +1,98 @@
+Name
+
+    MESA_drm_image_formats
+
+Name Strings
+
+    EGL_MESA_drm_image_formats
+
+Contributors
+
+    Nicolai Hähnle <Nicolai.Haehnle@amd.com>
+    Qiang Yu <Qiang.Yu@amd.com>
+
+Contact
+
+    Nicolai Hähnle <Nicolai.Haehnle@amd.com>
+
+Status
+
+    Proposal
+
+Version
+
+    Version 1, January 26, 2017
+
+Number
+
+    EGL Extension #??
+
+Dependencies
+
+    This extension requires the EGL_MESA_drm_image extension.
+
+    This extension is written against the wording of EGL_MESA_drm_image
+    specification.
+
+Overview
+
+    This extension extends the functionality of EGL_MESA_drm_image by adding
+    additional formats required by Glamor for use with DRM buffers.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute:
+
+        EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA  0x3290
+        EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA     0x3291
+        EGL_DRM_BUFFER_FORMAT_RGB565_MESA       0x3292
+
+Additions to the EGL_MESA_drm_image Specification:
+
+    Remove the sentence "The only format specified ..." from the paragraph
+    describing eglCreateDRMImageMESA and add the following paragraph:
+
+        The formats specified for use with EGL_DRM_BUFFER_FORMAT_MESA are:
+
+      * EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel is a CPU-endian
+        32-bit quantity, with alpha in the upper 8 bits, then red, then green,
+        then blue,
+
+      * EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA, where each pixel is a CPU-
+        endian, 32-bit quantity, with alpha in the most significant 2 bits,
+        followed by 10 bits each for red, green, and blue,
+
+      * EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA, where each pixel is a CPU-endian
+        16-bit quantity, with alpha in the most significant bit, followed by
+        5 bits each for red, green, and blue, and
+
+      * EGL_DRM_BUFFER_FORMAT_RGB565_MESA, where each pixel is a CPU-endian
+        16-bit quantity, with red in the 5 most significant bits, followed by
+        6 bits of green and 5 bits of blue.
+
+Issues
+
+    1. Should we expose the full set of channel permutations for the formats,
+       e.g. ABGR2101010, RGBA1010102, and BGRA1010102 in addition to
+       ARGB2101010?
+
+       RESOLVED: No.
+
+       DISCUSSION: The original extension sets a precedent of only exposing one
+       of the possible permutations of 8-bit channel formats. It is also not
+       clear where the additional permutations would be used. For example,
+       Glamor has a fixed mapping from pixmap/screen depth to format that
+       doesn't allow for the other permutations.
+
+Revision History
+
+    Version 1, January, 2017
+        Initial draft (Nicolai Hähnle)

mesa 3D driver/docs/_extra/specs/EGL_MESA_platform_surfaceless.txt

@@ -0,0 +1,120 @@
+Name
+
+    MESA_platform_surfaceless
+
+Name Strings
+
+    EGL_MESA_platform_surfaceless
+
+Contributors
+
+    Chad Versace <chadversary@google.com>
+    Haixia Shi <hshi@google.com>
+    Stéphane Marchesin <marcheu@google.com>
+    Zach Reizner <zachr@chromium.org>
+    Gurchetan Singh <gurchetansingh@google.com>
+
+Contacts
+
+    Chad Versace <chadversary@google.com>
+
+Status
+
+    DRAFT
+
+Version
+
+    Version 2, 2016-10-13
+
+Number
+
+    EGL Extension #TODO
+
+Extension Type
+
+    EGL client extension
+
+Dependencies
+
+    Requires EGL 1.5 or later; or EGL 1.4 with EGL_EXT_platform_base.
+
+    This extension is written against the EGL 1.5 Specification (draft
+    20140122).
+
+    This extension interacts with EGL_EXT_platform_base as follows. If the
+    implementation supports EGL_EXT_platform_base, then text regarding
+    eglGetPlatformDisplay applies also to eglGetPlatformDisplayEXT;
+    eglCreatePlatformWindowSurface to eglCreatePlatformWindowSurfaceEXT; and
+    eglCreatePlatformPixmapSurface to eglCreatePlatformPixmapSurfaceEXT.
+
+Overview
+
+    This extension defines a new EGL platform, the "surfaceless" platform. This
+    platfom's defining property is that it has no native surfaces, and hence
+    neither eglCreatePlatformWindowSurface nor eglCreatePlatformPixmapSurface
+    can be used. The platform is independent of any native window system.
+
+    The platform's intended use case is for enabling OpenGL and OpenGL ES
+    applications on systems where no window system exists. However, the
+    platform's permitted usage is not restricted to this case.  Since the
+    platform is independent of any native window system, it may also be used on
+    systems where a window system is present.
+
+New Types
+
+    None
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted as the <platform> argument of eglGetPlatformDisplay:
+
+        EGL_PLATFORM_SURFACELESS_MESA           0x31DD
+
+Additions to the EGL Specification
+
+    None.
+
+New Behavior
+
+    To determine if the EGL implementation supports this extension, clients
+    should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
+
+    To obtain an EGLDisplay on the surfaceless platform, call
+    eglGetPlatformDisplay with <platform> set to EGL_PLATFORM_SURFACELESS_MESA.
+    The <native_display> parameter must be EGL_DEFAULT_DISPLAY.
+
+    eglCreatePlatformWindowSurface fails when called with a <display> that
+    belongs to the surfaceless platform. It returns EGL_NO_SURFACE and
+    generates EGL_BAD_NATIVE_WINDOW. The justification for this unconditional
+    failure is that the surfaceless platform has no native windows, and
+    therefore the <native_window> parameter is always invalid.
+
+    Likewise, eglCreatePlatformPixmapSurface also fails when called with a
+    <display> that belongs to the surfaceless platform.  It returns
+    EGL_NO_SURFACE and generates EGL_BAD_NATIVE_PIXMAP.
+
+    The surfaceless platform imposes no platform-specific restrictions on the
+    creation of pbuffers, as eglCreatePbufferSurface has no native surface
+    parameter.  Specifically, if the EGLDisplay advertises an EGLConfig whose
+    EGL_SURFACE_TYPE attribute contains EGL_PBUFFER_BIT, then the EGLDisplay
+    permits the creation of pbuffers with that config.
+
+Issues
+
+    None.
+
+Revision History
+
+    Version 2, 2016-10-13 (Chad Versace)
+        - Assign enum values
+        - Define interfactions with EGL 1.4 and EGL_EXT_platform_base.
+        - Add Gurchetan as contributor, as he implemented the pbuffer support.
+
+    Version 1, 2016-09-23 (Chad Versace)
+        - Initial version
+        - Posted for review at
+          https://lists.freedesktop.org/archives/mesa-dev/2016-September/129549.html

mesa 3D driver/docs/_extra/specs/EGL_MESA_query_driver.txt

@@ -0,0 +1,95 @@
+Name
+
+    MESA_query_driver
+
+Name Strings
+
+    EGL_MESA_query_driver
+
+Contact
+
+    Rob Clark      <robdclark 'at' gmail.com>
+    Nicolai Hähnle <Nicolai.Haehnle 'at' amd.com>
+
+Contibutors
+
+    Veluri Mithun <velurimithun38 'at' gmail.com>
+
+Status
+
+    Complete
+
+Version
+
+    Version 3, 2019-01-24
+
+Number
+
+    EGL Extension 131
+
+Dependencies
+
+    EGL 1.0 is required.
+
+Overview
+
+    When an application has to query the name of a driver and for
+    obtaining driver's option list (UTF-8 encoded XML) of a driver
+    the below functions are useful.
+
+    XML file formally describes all available options and also
+    includes verbal descriptions in multiple languages. Its main purpose
+    is to be automatically processed by configuration GUIs.
+    The XML shall respect the following DTD:
+
+    <!ELEMENT driinfo      (section*)>
+    <!ELEMENT section      (description+, option+)>
+    <!ELEMENT description  (enum*)>
+    <!ATTLIST description  lang CDATA #REQUIRED
+                           text CDATA #REQUIRED>
+    <!ELEMENT option       (description+)>
+    <!ATTLIST option       name CDATA #REQUIRED
+                           type (bool|enum|int|float) #REQUIRED
+                           default CDATA #REQUIRED
+                           valid CDATA #IMPLIED>
+    <!ELEMENT enum         EMPTY>
+    <!ATTLIST enum         value CDATA #REQUIRED
+                           text CDATA #REQUIRED>
+
+New Procedures and Functions
+
+    char* eglGetDisplayDriverConfig(EGLDisplay dpy);
+    const char* eglGetDisplayDriverName(EGLDisplay dpy);
+
+Description
+
+    By passing EGLDisplay as parameter to `eglGetDisplayDriverName` one can retrieve
+    driverName. Similarly passing EGLDisplay to `eglGetDisplayDriverConfig` we can retrieve
+    driverConfig options of the driver in XML format.
+
+    The string returned by `eglGetDisplayDriverConfig` is heap-allocated and caller
+    is responsible for freeing it.
+
+    EGL_BAD_DISPLAY is generated if `disp` is not an EGL display connection.
+
+    EGL_NOT_INITIALIZED is generated if `disp` has not been initialized.
+
+    If the implementation does not have enough resources to allocate the XML then an
+    EGL_BAD_ALLOC error is generated.
+
+New Tokens
+
+    No new tokens
+
+Issues
+
+    None
+
+
+Revision History
+
+    Version 1, 2018-11-05 - First draft (Veluri Mithun)
+    Version 2, 2019-01-23 - Final version (Veluri Mithun)
+    Version 3, 2019-01-24 - Mark as complete, add Khronos extension
+                            number, fix parameter name in prototypes,
+                            write revision history (Eric Engestrom)

mesa 3D driver/docs/_extra/specs/EXT_shader_integer_mix.spec

@@ -0,0 +1,138 @@
+Name
+
+    EXT_shader_integer_mix
+
+Name Strings
+
+    GL_EXT_shader_integer_mix
+
+Contact
+
+    Matt Turner (matt.turner 'at' intel.com)
+
+Contributors
+
+    Matt Turner, Intel
+    Ian Romanick, Intel
+
+Status
+
+    Shipping
+
+Version
+
+    Last Modified Date:         09/12/2013
+    Author Revision:            6
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 3.0 or OpenGL ES 3.0 is required. This extension interacts with
+    GL_ARB_ES3_compatibility.
+
+    This extension is written against the OpenGL 4.4 (core) specification
+    and the GLSL 4.40 specification.
+
+Overview
+
+    GLSL 1.30 (and GLSL ES 3.00) expanded the mix() built-in function to
+    operate on a boolean third argument that does not interpolate but
+    selects. This extension extends mix() to select between int, uint,
+    and bool components.
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    None.
+
+Additions to Chapter 8 of the GLSL 4.40 Specification (Built-in Functions)
+
+    Modify Section 8.3, Common Functions
+
+    Additions to the table listing common built-in functions:
+
+      Syntax                       Description
+      ---------------------------  --------------------------------------------------
+      genIType mix(genIType x,     Selects which vector each returned component comes
+                   genIType y,     from. For a component of a that is false, the
+                   genBType a)     corresponding component of x is returned. For a
+      genUType mix(genUType x,     component of a that is true, the corresponding
+                   genUType y,     component of y is returned.
+                   genBType a)
+      genBType mix(genBType x,
+                   genBType y,
+                   genBType a)
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None.
+
+Modifications to The OpenGL Shading Language Specification, Version 4.40
+
+    Including the following line in a shader can be used to control the
+    language features described in this extension:
+
+      #extension GL_EXT_shader_integer_mix : <behavior>
+
+    where <behavior> is as specified in section 3.3.
+
+    New preprocessor #defines are added to the OpenGL Shading Language:
+
+      #define GL_EXT_shader_integer_mix        1
+
+Interactions with ARB_ES3_compatibility
+
+    On desktop implementations that support ARB_ES3_compatibility,
+    GL_EXT_shader_integer_mix can be enabled (and the new functions
+    used) in shaders declared with '#version 300 es'.
+
+GLX Protocol
+
+    None.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+New Implementation Dependent State
+
+    None.
+
+Issues
+
+    1) Should we allow linear interpolation of integers via a non-boolean
+       third component?
+
+    RESOLVED: No.
+
+    2) Should we allow mix() to select between boolean components?
+
+    RESOLVED: Yes. Implementing the same functionality using casts would be
+    possible but ugly.
+
+Revision History
+
+    Rev.    Date      Author    Changes
+    ----  --------    --------  ---------------------------------------------
+      6   09/12/2013  idr       After discussions in Khronos, change vendor
+                                prefix to EXT.
+
+      5   09/09/2013  idr       Add ARB_ES3_compatibility interaction.
+
+      4   09/06/2013  mattst88  Allow extension on OpenGL ES 3.0.
+
+      3   08/28/2013  mattst88  Add #extension/#define changes.
+
+      2   08/26/2013  mattst88  Change vendor prefix to MESA. Add mix() that
+                                selects between boolean components.
+      1   08/26/2013  mattst88  Initial revision

mesa 3D driver/docs/_extra/specs/EXT_shader_samples_identical.txt

@@ -0,0 +1,176 @@
+Name
+
+    EXT_shader_samples_identical
+
+Name Strings
+
+    GL_EXT_shader_samples_identical
+
+Contact
+
+    Ian Romanick, Intel (ian.d.romanick 'at' intel.com)
+
+Contributors
+
+    Chris Forbes, Mesa
+    Magnus Wendt, Intel
+    Neil S. Roberts, Intel
+    Graham Sellers, AMD
+
+Status
+
+    XXX - Not complete yet.
+
+Version
+
+    Last Modified Date: November 19, 2015
+    Revision: 6
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 3.2, or OpenGL ES 3.1, or ARB_texture_multisample is required.
+
+    This extension is written against the OpenGL 4.5 (Core Profile)
+    Specification
+
+Overview
+
+    Multisampled antialiasing has become a common method for improving the
+    quality of rendered images.  Multisampling differs from supersampling in
+    that the color of a primitive that covers all or part of a pixel is
+    resolved once, regardless of the number of samples covered.  If a large
+    polygon is rendered, the colors of all samples in each interior pixel will
+    be the same.  This suggests a simple compression scheme that can reduce
+    the necessary memory bandwidth requirements.  In one such scheme, each
+    sample is stored in a separate slice of the multisample surface.  An
+    additional multisample control surface (MCS) contains a mapping from pixel
+    samples to slices.
+
+    If all the values stored in the MCS for a particular pixel are the same,
+    then all the samples have the same value.  Applications can take advantage
+    of this information to reduce the bandwidth of reading multisample
+    textures.  A custom multisample resolve filter could optimize resolving
+    pixels where every sample is identical by reading the color once.
+
+    color = texelFetch(sampler, coordinate, 0);
+    if (!textureSamplesIdenticalEXT(sampler, coordinate)) {
+        for (int i = 1; i < MAX_SAMPLES; i++) {
+            vec4 c = texelFetch(sampler, coordinate, i);
+
+            //... accumulate c into color
+
+        }
+    }
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    None.
+
+Additions to the OpenGL 4.5 (Core Profile) Specification
+
+    None.
+
+Modifications to The OpenGL Shading Language Specification, Version 4.50.5
+
+    Including the following line in a shader can be used to control the
+    language features described in this extension:
+
+        #extension GL_EXT_shader_samples_identical
+
+    A new preprocessor #define is added to the OpenGL Shading Language:
+
+        #define GL_EXT_shader_samples_identical
+
+    Add to the table in section 8.7 "Texture Lookup Functions"
+
+    Syntax:
+
+        bool textureSamplesIdenticalEXT(gsampler2DMS sampler, ivec2 coord)
+
+        bool textureSamplesIdenticalEXT(gsampler2DMSArray sampler,
+                                        ivec3 coord)
+
+    Description:
+
+        Returns true if it can be determined that all samples within the texel
+        of the multisample texture bound to <sampler> at <coord> contain the
+        same values or false if this cannot be determined."
+
+Additions to the AGL/EGL/GLX/WGL Specifications
+
+    None
+
+Errors
+
+    None
+
+New State
+
+    None
+
+New Implementation Dependent State
+
+    None
+
+Issues
+
+    1) What should the new functions be called?
+
+    RESOLVED: textureSamplesIdenticalEXT.  Initially
+    textureAllSamplesIdenticalEXT was considered, but
+    textureSamplesIdenticalEXT is more similar to the existing textureSamples
+    function.
+
+    2) It seems like applications could implement additional optimization if
+       they were provided with raw MCS data.  Should this extension also
+       provide that data?
+
+    There are a number of challenges in providing raw MCS data.  The biggest
+    problem being that the amount of MCS data depends on the number of
+    samples, and that is not known at compile time.  Additionally, without new
+    texelFetch functions, applications would have difficulty utilizing the
+    information.
+
+    Another option is to have a function that returns an array of tuples of
+    sample number and count.  This also has difficulties with the maximum
+    array size not being known at compile time.
+
+    RESOLVED: Do not expose raw MCS data in this extension.
+
+    3) Should this extension also extend SPIR-V?
+
+    RESOLVED: Yes, but this has not yet been written.
+
+    4) Is it possible for textureSamplesIdenticalEXT to report false negatives?
+
+    RESOLVED: Yes.  It is possible that the underlying hardware may not detect
+    that separate writes of the same color to different samples of a pixel are
+    the same.  The shader function is at the whim of the underlying hardware
+    implementation.  It is also possible that a compressed multisample surface
+    is not used.  In that case the function will likely always return false.
+
+Revision History
+
+    Rev  Date        Author    Changes
+    ---  ----------  --------  ---------------------------------------------
+      1  2014/08/20  cforbes   Initial version
+      2  2015/10/23  idr       Change from MESA to EXT.  Rebase on OpenGL 4.5,
+                               and add dependency on OpenGL ES 3.1.  Initial
+                               draft of overview section and issues 1 through
+                               3.
+      3  2015/10/27  idr       Typo fixes.
+      4  2015/11/10  idr       Rename extension from EXT_shader_multisample_compression
+                               to EXT_shader_samples_identical.
+                               Add issue #4.
+      5  2015/11/18  idr       Fix some typos spotted by gsellers.  Change the
+                               name of the name of the function to
+                               textureSamplesIdenticalEXT.
+      6  2015/11/19  idr       Fix more typos spotted by Nicolai Hähnle.

mesa 3D driver/docs/_extra/specs/INTEL_shader_atomic_float_minmax.txt

@@ -0,0 +1,200 @@
+Name
+
+    INTEL_shader_atomic_float_minmax
+
+Name Strings
+
+    GL_INTEL_shader_atomic_float_minmax
+
+Contact
+
+    Ian Romanick (ian . d . romanick 'at' intel . com)
+
+Contributors
+
+
+Status
+
+    In progress
+
+Version
+
+    Last Modified Date: 06/22/2018
+    Revision: 4
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 4.2, OpenGL ES 3.1, ARB_shader_storage_buffer_object, or
+    ARB_compute_shader is required.
+
+    This extension is written against version 4.60 of the OpenGL Shading
+    Language Specification.
+
+Overview
+
+    This extension provides GLSL built-in functions allowing shaders to
+    perform atomic read-modify-write operations to floating-point buffer
+    variables and shared variables.  Minimum, maximum, exchange, and
+    compare-and-swap are enabled.
+
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    None.
+
+IP Status
+
+    None.
+
+Modifications to the OpenGL Shading Language Specification, Version 4.60
+
+    Including the following line in a shader can be used to control the
+    language features described in this extension:
+
+      #extension GL_INTEL_shader_atomic_float_minmax : <behavior>
+
+    where <behavior> is as specified in section 3.3.
+
+    New preprocessor #defines are added to the OpenGL Shading Language:
+
+      #define GL_INTEL_shader_atomic_float_minmax   1
+
+Additions to Chapter 8 of the OpenGL Shading Language Specification
+(Built-in Functions)
+
+    Modify Section 8.11, "Atomic Memory Functions"
+
+    (add a new row after the existing "atomicMin" table row, p. 179)
+
+        float atomicMin(inout float mem, float data)
+
+
+        Computes a new value by taking the minimum of the value of data and
+        the contents of mem.  If one of these is an IEEE signaling NaN (i.e.,
+        a NaN with the most-significant bit of the mantissa cleared), it is
+        always considered smaller.  If one of these is an IEEE quiet NaN
+        (i.e., a NaN with the most-significant bit of the mantissa set), it is
+        always considered larger.  If both are IEEE quiet NaNs or both are
+        IEEE signaling NaNs, the result of the comparison is undefined.
+
+    (add a new row after the exiting "atomicMax" table row, p. 179)
+
+        float atomicMax(inout float mem, float data)
+
+        Computes a new value by taking the maximum of the value of data and
+        the contents of mem.  If one of these is an IEEE signaling NaN (i.e.,
+        a NaN with the most-significant bit of the mantissa cleared), it is
+        always considered larger.  If one of these is an IEEE quiet NaN (i.e.,
+        a NaN with the most-significant bit of the mantissa set), it is always
+        considered smaller.  If both are IEEE quiet NaNs or both are IEEE
+        signaling NaNs, the result of the comparison is undefined.
+
+    (add to "atomicExchange" table cell, p. 180)
+
+        float atomicExchange(inout float mem, float data)
+
+    (add to "atomicCompSwap" table cell, p. 180)
+
+        float atomicCompSwap(inout float mem, float compare, float data)
+
+Interactions with OpenGL 4.6 and ARB_gl_spirv
+
+    If OpenGL 4.6 or ARB_gl_spirv is supported, then
+    SPV_INTEL_shader_atomic_float_minmax must also be supported.
+
+    The AtomicFloatMinmaxINTEL capability is available whenever the OpenGL or
+    OpenGL ES implementation supports INTEL_shader_atomic_float_minmax.
+
+Issues
+
+    1) Why call this extension INTEL_shader_atomic_float_minmax?
+
+    RESOLVED: Several other extensions already set the precedent of
+    VENDOR_shader_atomic_float and VENDOR_shader_atomic_float64 for extensions
+    that enable floating-point atomic operations.  Using that as a base for
+    the name seems logical.
+
+    There already exists NV_shader_atomic_float, but the two extensions have
+    nearly zero overlap in functionality.  NV_shader_atomic_float adds
+    atomicAdd and image atomic operations that currently shipping Intel GPUs
+    do not support.  Calling this extension INTEL_shader_atomic_float would
+    likely have been confusing.
+
+    Adding something to describe the actual functions added by this extension
+    seemed reasonable.  INTEL_shader_atomic_float_compare was considered, but
+    that name was deemed to be not properly descriptive.  Calling this
+    extension INTEL_shader_atomic_float_min_max_exchange_compswap is right
+    out.
+
+    2) What atomic operations should we support for floating-point targets?
+
+    RESOLVED.  Exchange, min, max, and compare-swap make sense, and these are
+    all supported by the hardware.  Future extensions may add other functions.
+
+    For buffer variables and shared variables it is not possible to bit-cast
+    the memory location in GLSL, so existing integer operations, such as
+    atomicOr, cannot be used.  However, the underlying hardware implementation
+    can do this by treating the memory as an integer.  It would be possible to
+    implement atomicNegate using this technique with atomicXor.  It is unclear
+    whether this provides any actual utility.
+
+    3) What should be said about the NaN behavior?
+
+    RESOLVED.  There are several aspects of NaN behavior that should be
+    documented in this extension.  However, some of this behavior varies based
+    on NaN concepts that do not exist in the GLSL specification.
+
+    * atomicCompSwap performs the comparison as the floating-point equality
+      operator (==).  That is, if either 'mem' or 'compare' is NaN, the
+      comparison result is always false.
+
+    * atomicMin and atomicMax implement the IEEE specification with respect to
+      NaN.  IEEE considers two different kinds of NaN: signaling NaN and quiet
+      NaN.  A quiet NaN has the most significant bit of the mantissa set, and
+      a signaling NaN does not.  This concept does not exist in SPIR-V,
+      Vulkan, or OpenGL.  Let qNaN denote a quiet NaN and sNaN denote a
+      signaling NaN.  atomicMin and atomicMax specifically implement
+
+      - fmin(qNaN, x) = fmin(x, qNaN) = fmax(qNaN, x) = fmax(x, qNaN) = x
+      - fmin(sNaN, x) = fmin(x, sNaN) = fmax(sNaN, x) = fmax(x, sNaN) = sNaN
+      - fmin(sNaN, qNaN) = fmin(qNaN, sNaN) = fmax(sNaN, qNaN) =
+        fmax(qNaN, sNaN) = sNaN
+      - fmin(sNaN, sNaN) = sNaN.  This specification does not define which of
+        the two arguments is stored.
+      - fmax(sNaN, sNaN) = sNaN.  This specification does not define which of
+        the two arguments is stored.
+      - fmin(qNaN, qNaN) = qNaN.  This specification does not define which of
+        the two arguments is stored.
+      - fmax(qNaN, qNaN) = qNaN.  This specification does not define which of
+        the two arguments is stored.
+
+    Further details are available in the Skylake Programmer's Reference
+    Manuals available at
+    https://01.org/linuxgraphics/documentation/hardware-specification-prms.
+
+    4) What about atomicMin and atomicMax with (+0.0, -0.0) or (-0.0, +0.0)
+    arguments?
+
+    RESOLVED.  atomicMin should store -0.0, and atomicMax should store +0.0.
+    Due to a known issue in shipping Skylake GPUs, the incorrectly signed 0 is
+    stored.  This behavior may change in later GPUs.
+
+Revision History
+
+    Rev  Date        Author    Changes
+    ---  ----------  --------  ---------------------------------------------
+      1  04/19/2018  idr       Initial version
+      2  05/05/2018  idr       Describe interactions with the capabilities
+                               added by SPV_INTEL_shader_atomic_float_minmax.
+      3  05/29/2018  idr       Remove mention of 64-bit float support.
+      4  06/22/2018  idr       Resolve issue #2.
+                               Add issue #3 (regarding NaN behavior).
+                               Add issue #4 (regarding atomicMin(-0, +0).

mesa 3D driver/docs/_extra/specs/MESA_configless_context.spec

@@ -0,0 +1,129 @@
+Name
+
+    MESA_configless_context
+
+Name Strings
+
+    EGL_MESA_configless_context
+
+Contact
+
+    Neil Roberts <neil.s.roberts@intel.com>
+
+Status
+
+    Superseded by the functionally identical EGL_KHR_no_config_context
+    extension.
+
+Version
+
+    Version 2, September 9, 2016
+
+Number
+
+    EGL Extension #not assigned
+
+Dependencies
+
+    Requires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+Overview
+
+    This extension provides a means to use a single context to render to
+    multiple surfaces which have different EGLConfigs. Without this extension
+    the EGLConfig for every surface used by the context must be compatible
+    with the one used by the context. The only way to render to surfaces with
+    different formats would be to create multiple contexts but this is
+    inefficient with modern GPUs where this restriction is unnecessary.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    Accepted as <config> in eglCreateContext
+
+        EGL_NO_CONFIG_MESA                  ((EGLConfig)0)
+
+Additions to the EGL Specification section "2.2 Rendering Contexts and Drawing
+Surfaces"
+
+    Add the following to the 3rd paragraph:
+
+   "EGLContexts can also optionally be created with respect to an EGLConfig
+    depending on the parameters used at creation time. If a config is provided
+    then additional restrictions apply on what surfaces can be used with the
+    context."
+
+    Replace the last sentence of the 6th paragraph with:
+
+   "In order for a context to be compatible with a surface they both must have
+    been created with respect to the same EGLDisplay. If the context was
+    created without respect to an EGLConfig then there are no further
+    constraints. Otherwise they are only compatible if:"
+
+    Remove the last bullet point in the list of constraints.
+
+Additions to the EGL Specification section "3.7.1 Creating Rendering Contexts"
+
+    Replace the paragraph starting "If config is not a valid EGLConfig..."
+    with
+
+   "The config argument can either be a valid EGLConfig or EGL_NO_CONFIG_MESA.
+    If it is neither of these then an EGL_BAD_CONFIG error is generated. If a
+    valid config is passed then the error will also be generated if the config
+    does not support the requested client API (this includes requesting
+    creation of an OpenGL ES 1.x context when the EGL_RENDERABLE_TYPE
+    attribute of config does not contain EGL_OPENGL_ES_BIT, or creation of an
+    OpenGL ES 2.x context when the attribute does not contain
+    EGL_OPENGL_ES2_BIT).
+
+    Passing EGL_NO_CONFIG_MESA will create a configless context. When a
+    configless context is used with the OpenGL API it can be assumed that the
+    initial values of the context's state will be decided when the context is
+    first made current. In particular this means that the decision of whether
+    to use GL_BACK or GL_FRONT for the initial value of the first output in
+    glDrawBuffers will be decided based on the config of the draw surface when
+    it is first bound."
+
+Additions to the EGL Specification section "3.7.3 Binding Contexts and
+Drawables"
+
+    Replace the first bullet point with the following:
+
+   "* If draw or read are not compatible with ctx as described in section 2.2,
+      then an EGL_BAD_MATCH error is generated."
+
+    Add a second bullet point after that:
+
+   "* If draw and read are not compatible with each other as described in
+      section 2.2, then an EGL_BAD_MATCH error is generated."
+
+Issues
+
+    1.  What happens when an OpenGL context with a double-buffered surface and
+        draw buffer set to GL_BACK is made current with a single-buffered
+        surface?
+
+        NOT RESOLVED: There are a few options here.  An implementation can
+        raise an error, change the drawbuffer state to GL_FRONT or just do
+        nothing, expecting the application to set GL_FRONT drawbuffer before
+        drawing.  However, this extension deliberately does not specify any
+        required behavior in this corner case and applications should avoid
+        mixing single- and double-buffered surfaces with configless contexts.
+
+        Future extensions may specify required behavior in this case.
+
+Revision History
+
+    Version 2, September 9, 2016
+        Defer to EGL_KHR_no_config_context (Adam Jackson)
+
+    Version 1, February 28, 2014
+        Initial draft (Neil Roberts)

mesa 3D driver/docs/_extra/specs/MESA_copy_sub_buffer.spec

@@ -0,0 +1,96 @@
+Name
+
+    MESA_copy_sub_buffer
+
+Name Strings
+
+    GLX_MESA_copy_sub_buffer
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Shipping since Mesa 2.6 in February, 1998.
+
+Version
+
+    Last Modified Date:  12 January 2009
+
+Number
+
+    215
+
+Dependencies
+
+    OpenGL 1.0 or later is required.
+    GLX 1.0 or later is required.
+
+Overview
+
+    The glxCopySubBufferMESA() function copies a rectangular region
+    of the back color buffer to the front color buffer.  This can be
+    used to quickly repaint 3D windows in response to expose events
+    when the back color buffer cannot be damaged by other windows.
+
+IP Status
+
+    Open-source; freely implementable.
+
+Issues
+
+    None.
+
+New Procedures and Functions
+
+    void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable,
+			       int x, int y, int width, int height );
+
+New Tokens
+
+    None.
+
+Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
+
+    Add to section 3.3.10 Double Buffering:
+
+    The function
+
+	 void glXCopySubBufferMESA( Display *dpy, GLXDrawable drawable,
+				    int x, int y, int width, int height );
+
+    may be used to copy a rectangular region of the back color buffer to
+    the front color buffer.  This can be used to quickly repaint 3D windows
+    in response to expose events when the back color buffer cannot be
+    damaged by other windows.
+
+    <x> and <y> indicates the lower-left corner of the region to copy and
+    <width> and <height> indicate the size in pixels.  Coordinate (0,0)
+    corresponds to the lower-left pixel of the window, like glReadPixels.
+
+    If dpy and drawable are the display and drawable for the calling
+    thread's current context, glXCopySubBufferMESA performs an
+    implicit glFlush before it returns.  Subsequent OpenGL commands
+    may be issued immediately after calling glXCopySubBufferMESA, but
+    are not executed until the copy is completed. 
+
+GLX Protocol
+
+    None at this time.  The extension is implemented in terms of ordinary
+    Xlib protocol inside of Mesa.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    12 January 2009 Ian Romanick - Added language about implicit flush
+                                   and command completion.
+    8 June 2000     Brian Paul   - initial specification
+

mesa 3D driver/docs/_extra/specs/MESA_drm_image.spec

@@ -0,0 +1,153 @@
+Name
+
+    MESA_drm_image
+
+Name Strings
+
+    EGL_MESA_drm_image
+
+Contact
+
+    Kristian Høgsberg <krh@bitplanet.net>
+
+Status
+
+    Proposal
+
+Version
+
+    Version 2, August 25, 2010
+
+Number
+
+    EGL Extension #not assigned
+
+Dependencies
+
+    Requires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+    EGL_KHR_base_image is required.
+
+Overview
+
+    This extension provides entry points for integrating EGLImage with the
+    Linux DRM mode setting and memory management drivers.  The extension
+    lets applications create EGLImages without a client API resource and
+    lets the application get the DRM buffer handles.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Procedures and Functions
+
+    EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
+                                      const EGLint *attrib_list);
+
+    EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
+                                     EGLImageKHR image,
+                                     EGLint *name,
+				     EGLint *handle,
+				     EGLint *stride);
+
+New Tokens
+
+    Accepted in the <attrib_list> parameter of eglCreateDRMImageMESA:
+
+        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
+        EGL_DRM_BUFFER_USE_MESA			0x31D1
+
+    Accepted as values for the EGL_IMAGE_FORMAT_MESA attribute:
+
+        EGL_DRM_BUFFER_FORMAT_ARGB32_MESA	0x31D2
+
+    Bits accepted in EGL_DRM_BUFFER_USE_MESA:
+
+        EGL_DRM_BUFFER_USE_SCANOUT_MESA		0x0001
+        EGL_DRM_BUFFER_USE_SHARE_MESA		0x0002
+        EGL_DRM_BUFFER_USE_CURSOR_MESA		0x0004
+
+    Accepted in the <target> parameter of eglCreateImageKHR:
+
+        EGL_DRM_BUFFER_MESA			0x31D3
+
+    Use when importing drm buffer:
+
+        EGL_DRM_BUFFER_STRIDE_MESA		0x31D4
+        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
+
+Additions to the EGL 1.4 Specification:
+
+    To create a DRM EGLImage, call
+
+        EGLImageKHR eglCreateDRMImageMESA(EGLDisplay dpy,
+                                          const EGLint *attrib_list);
+
+    In the attribute list, pass EGL_WIDTH, EGL_HEIGHT and format and
+    use in the attrib list using EGL_DRM_BUFFER_FORMAT_MESA and
+    EGL_DRM_BUFFER_USE_MESA.  The only format specified by this
+    extension is EGL_DRM_BUFFER_FORMAT_ARGB32_MESA, where each pixel
+    is a CPU-endian, 32-bit quantity, with alpha in the upper 8 bits,
+    then red, then green, then blue.  The bit values accepted by
+    EGL_DRM_BUFFER_USE_MESA are EGL_DRM_BUFFER_USE_SCANOUT_MESA,
+    EGL_DRM_BUFFER_USE_SHARE_MESA and EGL_DRM_BUFFER_USE_CURSOR_MESA.
+    EGL_DRM_BUFFER_USE_SCANOUT_MESA requests that the created EGLImage
+    should be usable as a scanout buffer with the DRM kernel
+    modesetting API.  EGL_DRM_BUFFER_USE_SHARE_MESA requests that the
+    EGLImage can be shared with other processes by passing the
+    underlying DRM buffer name.  EGL_DRM_BUFFER_USE_CURSOR_MESA
+    requests that the image must be usable as a cursor with KMS.  When
+    EGL_DRM_BUFFER_USE_CURSOR_MESA is set, width and height must both
+    be 64.
+
+    To create a process local handle or a global DRM name for a
+    buffer, call
+
+        EGLBoolean eglExportDRMImageMESA(EGLDisplay dpy,
+                                         EGLImageKHR image,
+                                         EGLint *name,
+                                         EGLint *handle,
+                                         EGLint *stride);
+
+    If <name> is non-NULL, a global name is assigned to the image and
+    written to <name>, the handle (local to the DRM file descriptor,
+    for use with DRM kernel modesetting API) is written to <handle> if
+    non-NULL and the stride (in bytes) is written to <stride>, if
+    non-NULL.
+
+    Import a shared buffer by calling eglCreateImageKHR with
+    EGL_DRM_BUFFER_MESA as the target, using EGL_WIDTH, EGL_HEIGHT,
+    EGL_DRM_BUFFER_FORMAT_MESA, EGL_DRM_BUFFER_STRIDE_MESA
+    in the attrib list.
+
+Issues
+
+    1.  Why don't we use eglCreateImageKHR with a target that
+        indicates that we want to create an EGLImage from scratch?
+
+        RESOLVED: The eglCreateImageKHR entry point is reserved for
+        creating an EGLImage from an already existing client API
+        resource.  This is fine when we're creating the EGLImage from
+        an existing DRM buffer name, it doesn't seem right to overload
+        the function to also allocate the underlying resource.
+
+    2.  Why don't we use an eglQueryImageMESA type functions for
+        querying the DRM EGLImage attributes (name, handle, and stride)?
+
+        RESOLVED: The eglQueryImage function has been proposed often,
+        but it goes against the EGLImage design.  EGLImages are opaque
+        handles to a 2D array of pixels, which can be passed between
+        client APIs.  By referencing an EGLImage in a client API, the
+        EGLImage target (a texture, a renderbuffer or such) can be
+        used to query the attributes of the EGLImage.  We don't have a
+        full client API for creating and querying DRM buffers, though,
+        so we use a new EGL extension entry point instead.
+
+Revision History
+
+    Version 1, June 3, 2010
+        Initial draft (Kristian Høgsberg)
+    Version 2, August 25, 2010
+        Flesh out the extension a bit, add final EGL tokens, capture
+        some of the original discussion in the issues section.

mesa 3D driver/docs/_extra/specs/MESA_framebuffer_flip_y.txt

@@ -0,0 +1,106 @@
+Name
+
+    MESA_framebuffer_flip_y
+
+Name Strings
+
+    GL_MESA_framebuffer_flip_y
+
+Contact
+
+    Fritz Koenig <frkoenig@google.com>
+
+Contributors
+
+    Fritz Koenig, Google
+    Kristian Høgsberg, Google
+    Chad Versace, Google
+    Heinrich Fink, DAQRI
+
+Status
+
+    Proposal
+
+Version
+
+    Version 3, August, 2019
+
+Number
+
+    OpenGL Extension #540
+    OpenGL ES Extension #302
+
+Dependencies
+
+    Requires OpenGL ES 3.0, OpenGL 4.3, or ARB_framebuffer_no_attachments.
+
+Overview
+
+    This extension defines a new framebuffer parameter,
+    GL_FRAMEBUFFER_FLIP_Y_MESA, that changes the behavior of the reads and
+    writes to the framebuffer attachment points. When GL_FRAMEBUFFER_FLIP_Y_MESA
+    is GL_TRUE, render commands and pixel transfer operations access the
+    backing store of each attachment point with an y-inverted coordinate
+    system. This y-inversion is relative to the coordinate system set when
+    GL_FRAMEBUFFER_FLIP_Y_MESA is GL_FALSE.
+
+    Access through TexSubImage2D and similar calls will notice the effect of
+    the flip when they are not attached to framebuffer objects because
+    GL_FRAMEBUFFER_FLIP_Y_MESA is associated with the framebuffer object and
+    not the attachment points.
+
+IP Status
+
+    None
+
+Issues
+
+    None
+
+New Procedures and Functions
+
+    OpenGL ES must provide the following functions:
+
+    void FramebufferParameteriMESA(enum target, enum pname, int param);
+    void GetFramebufferParameterivMESA(enum target, enum pname, int *params);
+
+New Types
+
+    None
+
+New Tokens
+
+    Accepted by the <pname> argument of FramebufferParameteriMESA and
+    GetFramebufferParameterivMESA:
+
+        GL_FRAMEBUFFER_FLIP_Y_MESA                      0x8BBB
+
+Interactions with OpenGL 4.3, OpenGL ES 3.1, ARB_framebuffer_no_attachments
+and any other versions and extensions that provide the entry points
+FramebufferParameteri and GetFramebufferParameteriv
+
+        Token GL_FRAMEBUFFER_FLIP_Y_MESA is accepted as the <pname> argument of
+        FramebufferParameteri and GetFramebufferParameteriv.
+
+Errors
+
+    An INVALID_OPERATION error is generated by GetFramebufferParameteriv or
+    GetFramebufferParameterivMESA if the default framebuffer is bound
+    to <target> and <pname> is GL_FRAMEBUFFER_FLIP_Y_MESA.
+
+
+
+
+
+Revision History
+
+    Version 3, August, 2019
+        Allow OpenGL ES 3.0 to implement by adding functions
+        FramebufferParameteriMESA and GetFramebufferParameterivMESA which were
+        previously only available in OpenGL ES 3.1.
+
+    Version 2, June, 2019
+        Enable extension for OpenGL 4.3 and beyond
+
+    Version 1, June, 2018
+        Initial draft (Fritz Koenig)

mesa 3D driver/docs/_extra/specs/MESA_image_dma_buf_export.txt

@@ -0,0 +1,147 @@
+Name
+
+    MESA_image_dma_buf_export
+
+Name Strings
+
+    EGL_MESA_image_dma_buf_export
+
+Contributors
+
+    Dave Airlie
+
+Contact
+
+    Dave Airlie (airlied 'at' redhat 'dot' com)
+
+Status
+
+    Complete, shipping.
+
+Version
+
+    Version 3, May 5, 2015
+
+Number
+
+    EGL Extension #87
+
+Dependencies
+
+    Requires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+    EGL_KHR_base_image is required.
+
+    The EGL implementation must be running on a Linux kernel supporting the
+    dma_buf buffer sharing mechanism.
+
+Overview
+
+    This extension provides entry points for integrating EGLImage with the
+    dma-buf infrastructure.  The extension allows creating a Linux dma_buf
+    file descriptor or multiple file descriptors, in the case of multi-plane
+    YUV image, from an EGLImage.
+
+    It is designed to provide the complementary functionality to
+    EGL_EXT_image_dma_buf_import.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Types
+
+    This extension uses the 64-bit unsigned integer type EGLuint64KHR
+    first introduced by the EGL_KHR_stream extension, but does not
+    depend on that extension. The typedef may be reproduced separately
+    for this extension, if not already present in eglext.h.
+
+    typedef khronos_uint64_t EGLuint64KHR;
+
+New Procedures and Functions
+
+    EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
+                                  EGLImageKHR image,
+				  int *fourcc,
+				  int *num_planes,
+				  EGLuint64KHR *modifiers);
+
+    EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
+                                        EGLImageKHR image,
+                                        int *fds,
+				        EGLint *strides,
+					EGLint *offsets);
+
+New Tokens
+
+    None
+
+
+Additions to the EGL 1.4 Specification:
+
+    To mirror the import extension, this extension attempts to return
+    enough information to enable an exported dma-buf to be imported
+    via eglCreateImageKHR and EGL_LINUX_DMA_BUF_EXT token.
+
+    Retrieving the information is a two step process, so two APIs
+    are required.
+
+    The first entrypoint
+       EGLBoolean eglExportDMABUFImageQueryMESA(EGLDisplay dpy,
+                                  EGLImageKHR image,
+				  int *fourcc,
+				  int *num_planes,
+				  EGLuint64KHR *modifiers);
+
+    is used to retrieve the pixel format of the buffer, as specified by
+    drm_fourcc.h, the number of planes in the image and the Linux
+    drm modifiers. <fourcc>, <num_planes> and <modifiers> may be NULL,
+    in which case no value is retrieved.
+
+    The second entrypoint retrieves the dma_buf file descriptors,
+    strides and offsets for the image. The caller should pass
+    arrays sized according to the num_planes values retrieved previously.
+    Passing arrays of the wrong size will have undefined results.
+    If the number of fds is less than the number of planes, then
+    subsequent fd slots should contain -1.
+
+        EGLBoolean eglExportDMABUFImageMESA(EGLDisplay dpy,
+                                         EGLImageKHR image,
+					 int *fds,
+                                         EGLint *strides,
+                                         EGLint *offsets);
+
+    <fds>, <strides>, <offsets> can be NULL if the infomatation isn't
+    required by the caller.
+
+Issues
+
+1. Should the API look more like an attribute getting API?
+
+ANSWER: No, from a user interface pov, having to iterate across calling
+the API up to 12 times using attribs seems like the wrong solution.
+
+2. Should the API take a plane and just get the fd/stride/offset for that
+   plane?
+
+ANSWER: UNKNOWN,this might be just as valid an API.
+
+3. Does ownership of the file descriptor remain with the app?
+
+ANSWER: Yes, the app is responsible for closing any fds retrieved.
+
+4. If number of planes and number of fds differ what should we do?
+
+ANSWER: Return -1 for the secondary slots, as this avoids having
+to dup the fd extra times to make the interface sane.
+
+Revision History
+
+    Version 3, May, 2015
+        Just use the KHR 64-bit type.
+    Version 2, March, 2015
+        Add a query interface (Dave Airlie)
+    Version 1, June 3, 2014
+        Initial draft (Dave Airlie)
+

mesa 3D driver/docs/_extra/specs/MESA_multithread_makecurrent.spec

@@ -0,0 +1,158 @@
+Name
+
+    MESA_multithread_makecurrent
+
+Name Strings
+
+    GLX_MESA_multithread_makecurrent
+
+Contact
+
+    Eric Anholt (eric@anholt.net)
+
+Status
+
+    Not shipping.
+
+Version
+
+    Last Modified Date:  21 February 2011
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.0 or later is required.
+    GLX 1.3 or later is required.
+
+Overview
+
+    The GLX context setup encourages multithreaded applications to
+    create a context per thread which each operate on their own
+    objects in parallel, and leaves synchronization for write access
+    to shared objects up to the application.
+
+    For some applications, maintaining per-thread contexts and
+    ensuring that the glFlush happens in one thread before another
+    thread starts working on that object is difficult.  For them,
+    using the same context across multiple threads and protecting its
+    usage with a mutex is both higher performance and easier to
+    implement.  This extension gives those applications that option by
+    relaxing the context binding requirements.
+
+    This new behavior matches the requirements of AGL, while providing
+    a feature not specified in WGL.
+
+IP Status
+
+    Open-source; freely implementable.
+
+Issues
+
+    None.
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+
+    None.
+
+Changes to Chapter 2 of the GLX 1.3 Specification (Functions and Errors)
+
+    Replace the following sentence from section 2.2 Rendering Contexts:
+	In addition, a rendering context can be current for only one
+	thread at a time.
+    with:
+	In addition, an indirect rendering context can be current for
+	only one thread at a time.  A direct rendering context may be
+	current to multiple threads, with synchronization of access to
+	the context thruogh the GL managed by the application through
+	mutexes.
+
+Changes to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
+
+    Replace the following sentence from section 3.3.7 Rendering Contexts:
+	If ctx is current to some other thread, then
+	glXMakeContextCurrent will generate a BadAccess error.
+    with:
+	If ctx is an indirect context current to some other thread,
+	then glXMakeContextCurrent will generate a BadAccess error.
+
+    Replace the following sentence from section 3.5 Rendering Contexts:
+	If ctx is current to some other thread, then
+	glXMakeCurrent will generate a BadAccess error.
+    with:
+	If ctx is an indirect context current to some other thread,
+	then glXMakeCurrent will generate a BadAccess error.
+
+GLX Protocol
+
+    None.  The GLX extension only extends to direct rendering contexts.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Issues
+
+    (1) What happens if the app binds a context/drawable in multiple
+	threads, then binds a different context/thread in one of them?
+
+    As with binding a new context from the current thread, the old
+    context's refcount is reduced and the new context's refcount is
+    increased.
+
+    (2) What happens if the app binds a context/drawable in multiple
+	threads, then binds None/None in one of them?
+
+    The GLX context is unreferenced from that thread, and the other
+    threads retain their GLX context binding.
+
+    (3) What happens if the app binds a context/drawable in 7 threads,
+	then destroys the context in one of them?
+
+    As with GLX context destruction previously, the XID is destroyed
+    but the context remains usable by threads that have the context
+    current.
+
+    (4) What happens if the app binds a new drawable/readable with
+        glXMakeCurrent() when it is already bound to another thread?
+
+    The context becomes bound to the new drawable/readable, and
+    further rendering in either thread will use the new
+    drawable/readable.
+
+    (5) What requirements should be placed on the user managing contexts
+        from multiple threads?
+
+    The intention is to allow multithreaded access to the GL at the
+    minimal performance cost, so requiring that the GL do general
+    synchronization (beyond that already required by context sharing)
+    is not an option, and synchronizing of GL's access to the GL
+    context between multiple threads is left to the application to do
+    across GL calls.  However, it would be unfortunate for a library
+    doing multithread_makecurrent to require that other libraries
+    share in synchronization for binding of their own contexts, so the
+    refcounting of the contexts is required to be threadsafe.
+
+    (6) Does this apply to indirect contexts?
+
+    This was ignored in the initial revision of the spec.  Behavior
+    for indirect contexts is left as-is.
+
+Revision History
+
+    20 November 2009 Eric Anholt - initial specification
+    22 November 2009 Eric Anholt - added issues from Ian Romanick.
+    3 February 2011 Eric Anholt - updated with resolution to issues 1-3
+    3 February 2011 Eric Anholt - added issue 4, 5
+    21 February 2011 Eric Anholt - Include glXMakeCurrent() sentence
+    along with glXMakeContextCurrent() for removal.

mesa 3D driver/docs/_extra/specs/MESA_pack_invert.spec

@@ -0,0 +1,138 @@
+Name
+
+    MESA_pack_invert
+
+Name Strings
+
+    GL_MESA_pack_invert
+
+Contact
+
+    Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com)
+    Keith Whitwell, Tungsten Graphics, Inc.  (keith 'at' tungstengraphics.com)
+
+Status
+
+    Shipping (Mesa 4.0.4 and later)
+
+Version
+
+    1.0
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.0 or later is required
+    This extensions is written against the OpenGL 1.4 Specification.
+
+Overview
+
+    This extension adds a new pixel storage parameter to indicate that
+    images are to be packed in top-to-bottom order instead of OpenGL's
+    conventional bottom-to-top order.  Only pixel packing can be
+    inverted (i.e. for glReadPixels, glGetTexImage, glGetConvolutionFilter,
+    etc).
+
+    Almost all known image file formats store images in top-to-bottom
+    order.  As it is, OpenGL reads images from the frame buffer in
+    bottom-to-top order.  Thus, images usually have to be inverted before
+    writing them to a file with image I/O libraries.  This extension
+    allows images to be read such that inverting isn't needed.
+
+IP Status
+
+    None
+
+Issues
+
+    1. Should we also define UNPACK_INVERT_MESA for glDrawPixels, etc?
+
+    Resolved:  No, we're only concerned with pixel packing.  There are other
+    solutions for inverting images when using glDrawPixels (negative Y pixel
+    zoom) or glTexImage (invert the vertex T coordinates).  It would be easy
+    enough to define a complementary extension for pixel packing in the
+    future if needed.
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted by the <pname> parameter of PixelStorei and PixelStoref
+    and the <pname> parameter of GetIntegerv, GetFloatv, GetDoublev
+    and GetBooleanv:
+
+        PACK_INVERT_MESA                   0x8758
+
+Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
+
+    None
+
+Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
+Operations and the Frame Buffer)
+
+    Add the following entry to table 4.4 (PixelStore parameters) on page 182:
+
+    Parameter Name       Type    Initial Value    Valid Range
+    ---------------------------------------------------------
+    PACK_INVERT_MESA     boolean     FALSE        TRUE/FALSE
+
+    In the section labeled "Placement in Client Memory" on page 184
+    insert the following text into the paragraph before the sentence
+    that starts with "If the format is RED, GREEN, BLUE...":
+
+    "The parameter PACK_INVERT_MESA controls whether the image is packed
+     in bottom-to-top order (the default) or top-to-bottom order.  Equation
+     3.8 is modified as follows:
+
+     ... the first element of the Nth row is indicated by
+
+         p + Nk,                if PACK_INVERT_MESA is false
+         p + k * (H - 1) - Nk,  if PACK_INVERT_MESA is true, where H is the
+                                image height
+    "
+
+Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
+State Requests)
+
+    None
+
+Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
+
+    None
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None
+
+GLX Protocol
+
+    None
+
+Errors
+
+    None
+
+New State
+
+    Add the following entry to table 6.20 (Pixels) on page 235:
+
+    Get Value         Type     Get Cmd    Initial Value  Description                Sec    Attribute
+    --------------------------------------------------------------------------------------------------
+    PACK_INVERT_MESA  boolean  GetBoolean  FALSE         Value of PACK_INVERT_MESA  4.3.2  pixel-store
+
+Revision History
+
+    21 September 2002 - Initial draft

mesa 3D driver/docs/_extra/specs/MESA_pixmap_colormap.spec

@@ -0,0 +1,90 @@
+Name
+
+    MESA_pixmap_colormap
+
+Name Strings
+
+    GLX_MESA_pixmap_colormap
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Shipping since Mesa 1.2.8 in May, 1996.
+
+Version
+
+    Last Modified Date:  8 June 2000
+
+Number
+
+    216
+
+Dependencies
+
+    OpenGL 1.0 or later is required.
+    GLX 1.0 or later is required.
+
+Overview
+
+    Since Mesa allows RGB rendering into drawables with PseudoColor,
+    StaticColor, GrayScale and StaticGray visuals, Mesa needs a colormap
+    in order to compute pixel values during rendering.
+
+    The colormap associated with a window can be queried with normal
+    Xlib functions but there is no colormap associated with pixmaps.
+
+    The glXCreateGLXPixmapMESA function is an alternative to glXCreateGLXPixmap
+    which allows specification of a colormap.
+
+IP Status
+
+    Open-source; freely implementable.
+
+Issues
+
+    None.
+
+New Procedures and Functions
+
+    GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
+				      Pixmap pixmap, Colormap cmap );
+
+New Tokens
+
+    None.
+
+Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
+
+    Add to section 3.4.2 Off Screen Rendering
+
+    The Mesa implementation of GLX allows RGB rendering into X windows and
+    pixmaps of any visual class, not just TrueColor or DirectColor.  In order
+    to compute pixel values from RGB values Mesa requires a colormap.
+
+    The function
+
+	GLXPixmap glXCreateGLXPixmapMESA( Display *dpy, XVisualInfo *visual,
+					  Pixmap pixmap, Colormap cmap );
+
+    allows one to create a GLXPixmap with a specific colormap.  The image
+    rendered into the pixmap may then be copied to a window (which uses the
+    same colormap and visual) with the expected results.
+
+GLX Protocol
+
+    None since this is a client-side extension.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    8 June 2000 - initial specification

mesa 3D driver/docs/_extra/specs/MESA_query_renderer.spec

@@ -0,0 +1,385 @@
+Name
+
+    MESA_query_renderer
+
+Name Strings
+
+    GLX_MESA_query_renderer
+
+Contact
+
+    Ian Romanick <ian.d.romanick@intel.com>
+
+IP Status
+
+    No known IP claims.
+
+Status
+
+    Shipping as of Mesa 10.0
+
+Version
+
+    Version 9, 09 November 2018
+
+Number
+
+    OpenGL Extension #446
+
+Dependencies
+
+    GLX 1.4 is required.
+
+    GLX_ARB_create_context and GLX_ARB_create_context_profile are required.
+
+Overview
+
+    In many situations, applications want to detect characteristics of a
+    rendering device before creating a context for that device.  Information
+    gathered at this stage may guide choices the application makes about
+    color depth, number of samples per-pixel, texture quality, and so on.
+    In addition, versions of supported APIs and implementation API
+    preference may also guide start-up decisions made by the application.
+    For example, one implementation may prefer vertex data be supplied using
+    methods only available in a compatibility profile, but another
+    implementation may only support the desired version in a core profile.
+
+    There are also cases where more than one renderer may be available per
+    display.  For example, there is typically a hardware implementation and
+    a software based implementation.  There are cases where an application
+    may want to pick one over the other.  One such situation is when the
+    software implementation supports more features than the hardware
+    implementation.  Another situation is when a particular version of the
+    hardware implementation is blacklisted due to known bugs.
+
+    This extension provides a mechanism for the application to query all of
+    the available renderers for a particular display and screen.  In
+    addition, this extension provides a mechanism for applications to create
+    contexts with respect to a specific renderer.
+
+New Procedures and Functions
+
+    Bool glXQueryRendererIntegerMESA(Display *dpy, int screen,
+                                     int renderer, int attribute,
+                                     unsigned int *value);
+    Bool glXQueryCurrentRendererIntegerMESA(int attribute, unsigned int *value);
+
+    const char *glXQueryRendererStringMESA(Display *dpy, int screen,
+                                           int renderer, int attribute);
+
+    const char *glXQueryCurrentRendererStringMESA(int attribute);
+
+New Tokens
+
+    Accepted as an <attribute> in glXQueryRendererIntegerMESA and
+    glXQueryCurrentRendererIntegerMESA:
+
+        GLX_RENDERER_VENDOR_ID_MESA                      0x8183
+        GLX_RENDERER_DEVICE_ID_MESA                      0x8184
+        GLX_RENDERER_VERSION_MESA                        0x8185
+        GLX_RENDERER_ACCELERATED_MESA                    0x8186
+        GLX_RENDERER_VIDEO_MEMORY_MESA                   0x8187
+        GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA    0x8188
+        GLX_RENDERER_PREFERRED_PROFILE_MESA              0x8189
+        GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA    0x818A
+        GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA    0x818B
+        GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA      0x818C
+        GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA     0x818D
+
+    Accepted as an <attribute> in glXQueryRendererStringMESA and
+    glXQueryCurrentRendererStringMESA:
+
+        GLX_RENDERER_VENDOR_ID_MESA
+        GLX_RENDERER_DEVICE_ID_MESA
+
+Additions to the OpenGL / WGL Specifications
+
+    None. This specification is written for GLX.
+
+Additions to the GLX 1.4 Specification
+
+    [Add to Section 3.3.2 "GLX Versioning" of the GLX Specification]
+
+    To obtain information about the available renderers for a particular
+    display and screen,
+
+        Bool glXQueryRendererIntegerMESA(Display *dpy, int screen, int renderer,
+                                         int attribute, unsigned int *value);
+
+    can be used.  The value for <attribute> will be returned in one or more
+    integers specified by <value>.  The values, data sizes, and descriptions
+    of each renderer attribute are listed in the table below.
+
+    GLX renderer attribute         number     description
+                                  of values
+    ----------------------        ---------   -----------
+    GLX_RENDERER_VENDOR_ID_MESA   1           PCI ID of the device vendor
+    GLX_RENDERER_DEVICE_ID_MESA   1           PCI ID of the device
+    GLX_RENDERER_VERSION_MESA     3           Major, minor, and patch level of
+                                              the renderer implementation
+    GLX_RENDERER_ACCELERATED_MESA 1           Boolean indicating whether or
+                                              not the renderer is hardware
+                                              accelerated
+    GLX_RENDERER_VIDEO_MEMORY_MESA 1          Number of megabytes of video
+                                              memory available to the renderer
+    GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA
+                                  1           Boolean indicating whether or
+                                              not the renderer uses a unified
+                                              memory architecture or has
+                                              separate "on-card" and GART
+                                              memory.
+    GLX_RENDERER_PREFERRED_PROFILE_MESA
+                                  1           Bitmask of the preferred context
+                                              profile for this renderer.  This
+                                              value is suitable to be supplied
+                                              with the
+                                              GLX_CONTEXT_PROFILE_MASK_ARB
+                                              attribute to
+                                              glXCreateContextAttribsARB
+    GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA
+                                  2           Maximum core profile major and
+                                              minor version supported by the
+                                              renderer
+    GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA
+                                  2           Maximum compatibility profile
+                                              major and minor version
+                                              supported by the renderer
+    GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA
+                                  2           Maximum OpenGL ES 1.x
+                                              major and minor version
+                                              supported by the renderer
+    GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA
+                                  2           Maximum OpenGL ES 2.x or 3.x
+                                              major and minor version
+                                              supported by the renderer
+
+    In the table, boolean attributes will have either the value 0 or 1.
+
+    GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA,
+    GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA,
+    GLX_RENDERER_OPENGL_ES_PROFILE_VERSION_MESA, and
+    GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA each return <0, 0> in
+    *value if no version of that profile is supported.
+
+    GLX_RENDERER_VENDOR_ID_MESA and GLX_RENDERER_DEVICE_ID_MESA may return
+    0xFFFFFFFF if the device does not have a PCI ID (because it is not a PCI
+    device) or if the PCI ID is not available.  In this case the application
+    should rely on the string query instead.
+
+    If <attribute> is not a recognized value, False is returned, but no GLX
+    error is generated.  Otherwise, True is returned.
+
+    String versions of some attributes may also be queried using
+
+        const char *glXQueryRendererStringMESA(Display *dpy, int screen,
+                                               int renderer, int attribute);
+
+    The value for <attribute> will be returned in one or more
+    integers specified by <value>.  The values, data sizes, and descriptions
+    of each renderer attribute are listed in the table below.
+
+    GLX renderer attribute        description
+    ----------------------        -----------
+    GLX_RENDERER_VENDOR_ID_MESA   Name of the renderer provider.  This may
+                                  differ from the vendor name of the
+                                  underlying hardware.
+    GLX_RENDERER_DEVICE_ID_MESA   Name of the renderer.  This may differ from
+                                  the name of the underlying hardware (e.g.,
+                                  for a software renderer).
+
+    If <attribute> is not a recognized value, NULL is returned, but no GLX
+    error is generated.
+
+    The string returned for GLX_RENDERER_VENDOR_ID_MESA will have the same
+    format as the string that would be returned by glGetString of GL_VENDOR.
+    It may, however, have a different value.
+
+    The string returned for GLX_RENDERER_DEVICE_ID_MESA will have the same
+    format as the string that would be returned by glGetString of GL_RENDERER.
+    It may, however, have a different value.
+
+Issues
+
+    1) How should the difference between on-card and GART memory be exposed?
+
+        UNRESOLVED.
+
+    2) How should memory limitations of unified memory architecture (UMA)
+    systems be exposed?
+
+        UNRESOLVED.  Some hardware has different per-process and global
+        limits for memory that can be accessed within a single draw call.
+
+    3) How should the renderer's API preference be advertised?
+
+        UNRESOLVED.  The common case for desktop renderers is to prefer
+        either core or compatibility.  However, some renderers may actually
+        prefer an ES context.  This leaves the application in a tough spot
+        if it can only support core or compatibility and the renderer says it
+        wants ES.
+
+    4) Should OpenGL ES 2.0 and OpenGL ES 3.0 be treated separately?
+
+        RESOLVED.  No.  OpenGL ES 3.0 is backwards compatible with OpenGL ES
+        2.0.  Applications can detect OpenGL ES 3.0 support by querying
+        GLX_RENDERER_OPENGL_ES2_PROFILE_VERSION_MESA.
+
+    5) How can applications tell the difference between different hardware
+    renderers for the same device?  For example, whether the renderer is the
+    open-source driver or the closed-source driver.
+
+        RESOLVED.  Assuming this extension is ever implemented outside Mesa,
+        applications can query GLX_RENDERER_VENDOR_ID_MESA from
+        glXQueryRendererStringMESA.  This will almost certainly return
+        different strings for open-source and closed-source drivers.
+
+    6) What is the value of GLX_RENDERER_UNIFIED_MEMORY_ARCHITECTURE_MESA for
+    software renderers?
+
+        UNRESOLVED.  Video (display) memory and texture memory is not unified
+        for software implementations, so it seems reasonable for this to be
+        False.
+
+    7) How does an application determine the number of available renderers?
+
+        UNRESOLVED.
+
+    8) What happens if a fbconfig is used to create context on a renderer
+    that cannot support it?  For example, if a multisampled config is used
+    with a software renderer that does not support multisampling.
+
+        RESOLVED.  The language for glXCreateContextAttribsARB already covers
+        this case.  Context creation will fail, and BadMatch is generated.
+
+    9) In addition to being able to query the supported versions, should
+    applications also be able to query the supported extensions?
+
+        RESOLVED.  No.  Desktop OpenGL core profiles and OpenGL ES 3.0 have
+        moved away from the monolithic string returned by glGetString of
+        GL_EXTENSIONS.  Providing the newer indexed query would require adding
+        a lot of extra infrastructure, and it would probably provide little
+        benefit to applications.
+
+    10) What combination of values for GLX_RENDERER_PREFERRED_PROFILE_MESA,
+    GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA, and
+    GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA should be returned
+    for a renderer that only supports OpenGL 3.1 without the
+    GL_ARB_compatibility extension?
+
+        RESOLVED.  The renderer will return GLX_CONTEXT_CORE_PROFILE_BIT_ARB
+        for GLX_RENDERER_PREFERRED_PROFILE_MESA.
+
+        Further, the renderer will return <3,0> for
+        GLX_RENDERER_OPENGL_COMPATIBILITY_PROFILE_VERSION_MESA because OpenGL
+        3.1 without GL_ARB_compatibility is not backwards compatible with
+        previous versions of OpenGL.  The render will return <3,1> for
+        GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA indicating that support
+        for OpenGL 3.1 is available.
+
+        Even though there is no OpenGL 3.1 core profile, the values
+        returned for GLX_RENDERER_PREFERRED_PROFILE_MESA and
+        GLX_RENDERER_OPENGL_CORE_PROFILE_VERSION_MESA can be supplied
+        with the GLX_CONTEXT_PROFILE_MASK_ARB and
+        GLX_CONTEXT_{MAJOR,MINOR}_VERSION_ARB attributes of
+        glXCreateContextAttribsARB without error.  If the requested
+        OpenGL version is less than 3.2, the
+        GLX_CONTEXT_PROFILE_MASK_ARB attribute is ignored by
+        glXCreateContextAttribsARB.
+
+    11) How can application learn about multi-GPU (e.g., SLI, CrossFireX,
+    etc.) configurations?
+
+        UNRESOLVED.  Based on ISV feedback, this is important information to
+        provide to the application.  Given the variety of possible hardware
+        configurations (e.g., Hybrid CrossFireX) and different rendering
+        modes (e.g., split-frame rendering vs. alternate-frame rendering),
+        it's not clear how this information can be communicated.
+
+        It is likely that this will be left to a layered extension.
+
+    12) Should capability queries similar to those in
+    GL_ARB_internalformat_query or GL_ARB_internalformat_query2 be added?
+
+        RESOLVED.  No.  With the possible exception of the texture size
+        queries, it seems unlikely that applications would ever use this
+        information before creating a context.
+
+    13) Existing GL extensions (e.g., GL_ATI_meminfo and
+    GL_NVX_gpu_memory_info) allow easy queries after context creation.  With
+    this extension it is a bit of a pain for a portable application to query
+    the information after context creation.
+
+        RESOLVED.  Add versions of the queries that implicitly take the
+        display, screen, and renderer from the currently bound context.
+
+    14) Why not make the queries from issue #13 GL functions (instead of GLX)?
+
+        RESOLVED.  It is fairly compelling for the post-creation queries to
+        just use glGetInteger and glGetString.  However, the GL enums and
+        the GLX enums would have different names and would almost certainly
+        have different values.  It seems like this would cause more problems
+        than it would solve.
+
+    15) Should the string queries be required to return the same values as
+    glGetString(GL_VENDOR) and glGetString(GL_RENDERER)?
+
+        UNRESOLVED.  This may be useful for applications that already do
+        device detection based on these strings.
+
+    16) What type should the value parameter of glXQueryRendererIntegerMESA
+        and glXQueryCurrentRendererIntegerMESA be?
+
+        UNRESOLVED.  Other similar GLX query functions just use int or
+        unsigned int, so that's what this extension uses for now.  However,
+        an expeclitly sized value, such as uint32_t or uint64_t, seems
+        preferable.
+
+    17) What about SoCs and other systems that don't have PCI?
+
+        RESOLVED. The GLX_RENDERER_VENDOR_ID_MESA and
+        GLX_RENDERER_DEVICE_ID_MESA integer queries may return 0xFFFFFFFF if a
+        PCI ID either does not exist or is not available.  Implementations
+        should make every attempt to return as much information as is
+        possible.  For example, if the implementation is running on a non-PCI
+        SoC with a Qualcomm GPU, GLX_RENDERER_VENDOR_ID_MESA should return
+        0x5143, but GLX_RENDERER_DEVICE_ID_MESA will return 0xFFFFFFFF.
+
+Revision History
+
+    Version 1, 2012/08/27 - Initial version
+
+    Version 2, 2012/09/04 - Specify behavior of implementations that
+                            do not support certain profiles.
+                            Change wording of issue #8 to be more
+                            clear.
+                            Make some wording changes to issue #10 to
+                            clarify the resolution a bit.
+
+    Version 3, 2012/09/23 - Add issue #11 regarding multi-GPU systems.
+
+    Version 4, 2013/02/01 - Add issue #12 regarding texture / renderbuffer
+                            format queries.
+
+    Version 5, 2013/02/14 - Add issues #13 and #14 regarding simpler queires
+                            after the context is created and made current.
+                            Add issue #15 regarding the string query.
+                            Add issue #16 regarding the value type returned
+                            by the Integer functions.
+
+    Version 6, 2013/10/25 - Fix a typo.  Update the list of functions to
+                            which the new enums can be passed.  The "Current"
+                            versions were previously missing.
+
+    Version 7, 2013/11/07 - Fix a couple more typos.  Add issue #17 regarding
+                            the PCI queries on systems that don't have PCI.
+
+    Version 8, 2014/02/14 - Fix a couple typos. GLX_RENDER_ID_MESA should
+                            read GLX_RENDERER_ID_MESA. The VENDOR/DEVICE_ID
+                            example given in issue #17 should be 0x5143 and
+                            0xFFFFFFFF respectively.
+
+    Version 9, 2018/11/09 - Remove GLX_RENDERER_ID_MESA, which has never been
+                            implemented. Remove the unnecessary interactions
+                            with the GLX GLES profile extensions. Note the
+                            official GL extension number. Specify the section
+                            of the GLX spec to modify.

mesa 3D driver/docs/_extra/specs/MESA_release_buffers.spec

@@ -0,0 +1,85 @@
+Name
+
+    MESA_release_buffers
+
+Name Strings
+
+    GLX_MESA_release_buffers
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Shipping since Mesa 2.0 in October, 1996.
+
+Version
+
+    Last Modified Date:  8 June 2000
+
+Number
+
+    217
+
+Dependencies
+
+    OpenGL 1.0 or later is required.
+    GLX 1.0 or later is required.
+
+Overview
+
+    Mesa's implementation of GLX is entirely implemented on the client side.
+    Therefore, Mesa cannot immediately detect when an X window or pixmap is
+    destroyed in order to free any ancillary data associated with the window
+    or pixmap.
+
+    The glxMesaReleaseBuffers() function can be used to explicitly indicate
+    when the back color buffer, depth buffer, stencil buffer, and/or accumu-
+    lation buffer associated with a drawable can be freed.
+
+IP Status
+
+    Open-source; freely implementable.
+
+Issues
+
+    None.
+
+New Procedures and Functions
+
+    Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d );
+
+New Tokens
+
+    None.
+
+Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
+
+    The function
+
+	Bool glXReleaseBuffersMESA( Display *dpy, GLXDrawable d );
+
+    causes all software ancillary buffers (back buffer, depth, stencil,
+    accum, etc) associated with the named drawable to be immediately
+    deallocated.  True is returned if <d> is a valid Mesa GLX drawable,
+    else False is returned.  After calling glXReleaseBuffersMESA, the
+    drawable should no longer be used for GL rendering.  Results of
+    attempting to do so are undefined.
+
+
+GLX Protocol
+
+    None, since this is a client-side operation.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    8 June 2000 - initial specification

mesa 3D driver/docs/_extra/specs/MESA_shader_debug.spec

@@ -0,0 +1,264 @@
+Name
+
+    MESA_shader_debug
+
+Name Strings
+
+    GL_MESA_shader_debug
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+    Michal Krol (mjkrol 'at' gmail.com)
+
+Status
+
+    Obsolete.
+
+Version
+
+    Last Modified Date: July 30, 2006
+    Author Revision: 0.2
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.0 is required.
+
+    The ARB_shader_objects extension is required.
+
+    The ARB_shading_language_100 extension is required.
+
+    The extension is written against the OpenGL 1.5 specification.
+
+    The extension is written against the OpenGL Shading Language 1.10
+    Specification.
+
+Overview
+
+    This extension introduces a debug object that can be attached to
+    a program object to enable debugging. Vertex and/or fragment shader,
+    during execution, issue diagnostic function calls that are logged
+    to the debug object's log. A separate debug log for each shader type
+    is maintained. A debug object can be attached, detached and queried
+    at any time outside the Begin/End pair. Multiple debug objects can
+    be attached to a single program object.
+
+IP Status
+
+    None
+
+Issues
+
+    None
+
+New Procedures and Functions
+
+    handleARB CreateDebugObjectMESA(void)
+    void ClearDebugLogMESA(handleARB obj, enum logType, enum shaderType)
+    void GetDebugLogMESA(handleARB obj, enum logType, enum shaderType,
+                         sizei maxLength, sizei *length,
+                         charARB *debugLog)
+    sizei GetDebugLogLengthMESA(handleARB obj, enum logType,
+                                enum shaderType)
+
+New Types
+
+    None
+
+New Tokens
+
+    Returned by the <params> parameter of GetObjectParameter{fi}vARB:
+
+        DEBUG_OBJECT_MESA                               0x8759
+
+    Accepted by the <logType> argument of ClearDebugLogMESA,
+    GetDebugLogLengthMESA and GetDebugLogMESA:
+
+        DEBUG_PRINT_MESA                                0x875A
+        DEBUG_ASSERT_MESA                               0x875B
+
+Additions to Chapter 2 of the OpenGL 1.5 Specification
+(OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the OpenGL 1.5 Specification (Rasterization)
+
+    None
+
+Additions to Chapter 4 of the OpenGL 1.5 Specification (Per-Fragment
+Operations and the Frame Buffer)
+
+    None
+
+Additions to Chapter 5 of the OpenGL 1.5 Specification
+(Special Functions)
+
+    None
+
+Additions to Chapter 6 of the OpenGL 1.5 Specification (State and State
+Requests)
+
+    None
+
+Additions to Appendix A of the OpenGL 1.5 Specification (Invariance)
+
+    None
+
+Additions to Chapter 1 of the OpenGL Shading Language 1.10 Specification
+(Introduction)
+
+    None
+
+Additions to Chapter 2 of the OpenGL Shading Language 1.10 Specification
+(Overview of OpenGL Shading)
+
+    None
+
+Additions to Chapter 3 of the OpenGL Shading Language 1.10 Specification
+(Basics)
+
+    None
+
+Additions to Chapter 4 of the OpenGL Shading Language 1.10 Specification
+(Variables and Types)
+
+    None
+
+Additions to Chapter 5 of the OpenGL Shading Language 1.10 Specification
+(Operators and Expressions)
+
+    None
+
+Additions to Chapter 6 of the OpenGL Shading Language 1.10 Specification
+(Statements and Structure)
+
+    None
+
+Additions to Chapter 7 of the OpenGL Shading Language 1.10 Specification
+(Built-in Variables)
+
+    None
+
+Additions to Chapter 8 of the OpenGL Shading Language 1.10 Specification
+(Built-in Functions)
+
+    Add a new section 8.10 "Debug Functions":
+
+    Debug functions are available to both fragment and vertex shaders.
+    They are used to track the execution of a shader by logging
+    passed-in arguments to the debug object's log. Those values can be
+    retrieved by the application for inspection after shader execution
+    is complete.
+
+    The text, if any, produced by any of these functions is appended
+    to each debug object that is attached to the program object.
+    There are different debug log types
+
+    Add a new section 8.10.1 "Print Function":
+
+    The following printMESA prototypes are available.
+
+        void printMESA(const float value)
+        void printMESA(const int value)
+        void printMESA(const bool value)
+        void printMESA(const vec2 value)
+        void printMESA(const vec3 value)
+        void printMESA(const vec4 value)
+        void printMESA(const ivec2 value)
+        void printMESA(const ivec3 value)
+        void printMESA(const ivec4 value)
+        void printMESA(const bvec2 value)
+        void printMESA(const bvec3 value)
+        void printMESA(const bvec4 value)
+        void printMESA(const mat2 value)
+        void printMESA(const mat3 value)
+        void printMESA(const mat4 value)
+        void printMESA(const sampler1D value)
+        void printMESA(const sampler2D value)
+        void printMESA(const sampler3D value)
+        void printMESA(const samplerCube value)
+        void printMESA(const sampler1DShadow value)
+        void printMESA(const sampler2DShadow value)
+
+    The printMESA function writes the argument <value> to the "debug
+    print log" (XXX DEBUG_PRINT_MESA?). Each component is written in
+    text format (XXX format!) and is delimited by a white space (XXX 1
+    or more?).
+
+    Add a new section 8.10.2 "Assert Function":
+
+    The following assertMESA prototypes are available.
+
+        void assertMESA(const bool condition)
+        void assertMESA(const bool condition, const int cookie)
+        void assertMESA(const bool condition, const int cookie,
+                        const int file, const int line)
+
+    The assertMESA function checks if the argument <condition> is
+    true or false. If it is true, nothing happens. If it is false,
+    a diagnostic message is written to the "debug assert log".
+    The message contains the argument <file>, <line>, <cookie> and
+    implementation dependent double-quoted string, each of this
+    delimited by a white space. If the argument <cookie> is not present,
+    it is meant as if it was of value 0. If the arguments <file> and
+    <line> are not present, they are meant as if they were of values
+    __FILE__ and __LINE__, respectively. The following three calls
+    produce the same output, assuming they were issued from the same
+    file and line.
+
+        assertMESA (false);
+        assertMESA (false, 0);
+        assertMESA (false, 0, __FILE__, __LINE__);
+
+    The diagnostic message examples follow.
+
+        1 89 0 ""
+        1 45 333 "all (lessThanEqual (fragColor, vec4 (1.0)))"
+        1 66 1 "assertion failed in file 1, line 66, cookie 1"
+
+Additions to Chapter 9 of the OpenGL Shading Language 1.10 Specification
+(Shading Language Grammar)
+
+    None
+
+Additions to Chapter 10 of the OpenGL Shading Language 1.10
+Specification (Issues)
+
+    None
+
+Additions to the AGL/EGL/GLX/WGL Specifications
+
+    None
+
+GLX Protocol
+
+    None
+
+Errors
+
+    TBD
+
+New State
+
+    TBD
+
+New Implementation Dependent State
+
+    TBD
+
+Sample Code
+
+    TBD
+
+Revision History
+
+    29 May 2006
+        Initial draft. (Michal Krol)
+    30 July 2006
+        Add Overview, New Procedures and Functions, New Tokens sections.
+        Add sections 8.10.1, 8.10.2 to GLSL spec.

mesa 3D driver/docs/_extra/specs/MESA_shader_integer_functions.txt

@@ -0,0 +1,522 @@
+Name
+
+    MESA_shader_integer_functions
+
+Name Strings
+
+    GL_MESA_shader_integer_functions
+
+Contact
+
+    Ian Romanick <ian.d.romanick@intel.com>
+
+Contributors
+
+    All the contributors of GL_ARB_gpu_shader5
+
+Status
+
+    Supported by all GLSL 1.30 capable drivers in Mesa 12.1 and later
+
+Version
+
+    Version 3, March 31, 2017
+
+Number
+
+    OpenGL Extension #495
+
+Dependencies
+
+    This extension is written against the OpenGL 3.2 (Compatibility Profile)
+    Specification.
+
+    This extension is written against Version 1.50 (Revision 09) of the OpenGL
+    Shading Language Specification.
+
+    GLSL 1.30 (OpenGL) or GLSL ES 3.00 (OpenGL ES) is required.
+
+    This extension interacts with ARB_gpu_shader5.
+
+    This extension interacts with ARB_gpu_shader_fp64.
+
+    This extension interacts with NV_gpu_shader5.
+
+Overview
+
+    GL_ARB_gpu_shader5 extends GLSL in a number of useful ways.  Much of this
+    added functionality requires significant hardware support.  There are many
+    aspects, however, that can be easily implmented on any GPU with "real"
+    integer support (as opposed to simulating integers using floating point
+    calculations).
+
+    This extension provides a set of new features to the OpenGL Shading
+    Language to support capabilities of these GPUs, extending the
+    capabilities of version 1.30 of the OpenGL Shading Language and version
+    3.00 of the OpenGL ES Shading Language.  Shaders using the new
+    functionality provided by this extension should enable this
+    functionality via the construct
+
+      #extension GL_MESA_shader_integer_functions : require   (or enable)
+
+    This extension provides a variety of new features for all shader types,
+    including:
+
+      * support for implicitly converting signed integer types to unsigned
+        types, as well as more general implicit conversion and function
+        overloading infrastructure to support new data types introduced by
+        other extensions;
+
+      * new built-in functions supporting:
+
+        * splitting a floating-point number into a significand and exponent
+          (frexp), or building a floating-point number from a significand and
+          exponent (ldexp);
+
+        * integer bitfield manipulation, including functions to find the
+          position of the most or least significant set bit, count the number
+          of one bits, and bitfield insertion, extraction, and reversal;
+
+        * extended integer precision math, including add with carry, subtract
+          with borrow, and extenended multiplication;
+
+    The resulting extension is a strict subset of GL_ARB_gpu_shader5.
+
+IP Status
+
+    No known IP claims.
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    None
+
+Additions to Chapter 2 of the OpenGL 3.2 (Compatibility Profile) Specification
+(OpenGL Operation)
+
+    None.
+
+Additions to Chapter 3 of the OpenGL 3.2 (Compatibility Profile) Specification
+(Rasterization)
+
+    None.
+
+Additions to Chapter 4 of the OpenGL 3.2 (Compatibility Profile) Specification
+(Per-Fragment Operations and the Frame Buffer)
+
+    None.
+
+Additions to Chapter 5 of the OpenGL 3.2 (Compatibility Profile) Specification
+(Special Functions)
+
+    None.
+
+Additions to Chapter 6 of the OpenGL 3.2 (Compatibility Profile) Specification
+(State and State Requests)
+
+    None.
+
+Additions to Appendix A of the OpenGL 3.2 (Compatibility Profile)
+Specification (Invariance)
+
+    None.
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None.
+
+Modifications to The OpenGL Shading Language Specification, Version 1.50
+(Revision 09)
+
+    Including the following line in a shader can be used to control the
+    language features described in this extension:
+
+      #extension GL_MESA_shader_integer_functions : <behavior>
+
+    where <behavior> is as specified in section 3.3.
+
+    New preprocessor #defines are added to the OpenGL Shading Language:
+
+      #define GL_MESA_shader_integer_functions        1
+
+
+    Modify Section 4.1.10, Implicit Conversions, p. 27
+
+    (modify table of implicit conversions)
+
+                                Can be implicitly
+        Type of expression        converted to
+        ---------------------   -----------------
+        int                     uint, float
+        ivec2                   uvec2, vec2
+        ivec3                   uvec3, vec3
+        ivec4                   uvec4, vec4
+
+        uint                    float
+        uvec2                   vec2
+        uvec3                   vec3
+        uvec4                   vec4
+
+    (modify second paragraph of the section) No implicit conversions are
+    provided to convert from unsigned to signed integer types or from
+    floating-point to integer types.  There are no implicit array or structure
+    conversions.
+
+    (insert before the final paragraph of the section) When performing
+    implicit conversion for binary operators, there may be multiple data types
+    to which the two operands can be converted.  For example, when adding an
+    int value to a uint value, both values can be implicitly converted to uint
+    and float.  In such cases, a floating-point type is chosen if either
+    operand has a floating-point type.  Otherwise, an unsigned integer type is
+    chosen if either operand has an unsigned integer type.  Otherwise, a
+    signed integer type is chosen.
+    
+
+    Modify Section 5.9, Expressions, p. 57
+
+    (modify bulleted list as follows, adding support for implicit conversion
+    between signed and unsigned types)
+
+    Expressions in the shading language are built from the following:
+
+    * Constants of type bool, int, int64_t, uint, uint64_t, float, all vector
+      types, and all matrix types.
+
+    ...
+
+    * The operator modulus (%) operates on signed or unsigned integer scalars
+      or vectors.  If the fundamental types of the operands do not match, the
+      conversions from Section 4.1.10 "Implicit Conversions" are applied to
+      produce matching types.  ...
+
+
+    Modify Section 6.1, Function Definitions, p. 63
+
+    (modify description of overloading, beginning at the top of p. 64)
+
+     Function names can be overloaded.  The same function name can be used for
+     multiple functions, as long as the parameter types differ.  If a function
+     name is declared twice with the same parameter types, then the return
+     types and all qualifiers must also match, and it is the same function
+     being declared.  For example,
+
+       vec4 f(in vec4 x, out vec4  y);   // (A)
+       vec4 f(in vec4 x, out uvec4 y);   // (B) okay, different argument type
+       vec4 f(in ivec4 x, out uvec4 y);  // (C) okay, different argument type
+
+       int  f(in vec4 x, out ivec4 y);  // error, only return type differs
+       vec4 f(in vec4 x, in  vec4  y);  // error, only qualifier differs
+       vec4 f(const in vec4 x, out vec4 y);  // error, only qualifier differs
+
+     When function calls are resolved, an exact type match for all the
+     arguments is sought.  If an exact match is found, all other functions are
+     ignored, and the exact match is used.  If no exact match is found, then
+     the implicit conversions in Section 4.1.10 (Implicit Conversions) will be
+     applied to find a match.  Mismatched types on input parameters (in or
+     inout or default) must have a conversion from the calling argument type
+     to the formal parameter type.  Mismatched types on output parameters (out
+     or inout) must have a conversion from the formal parameter type to the
+     calling argument type.
+
+     If implicit conversions can be used to find more than one matching
+     function, a single best-matching function is sought.  To determine a best
+     match, the conversions between calling argument and formal parameter
+     types are compared for each function argument and pair of matching
+     functions.  After these comparisons are performed, each pair of matching
+     functions are compared.  A function definition A is considered a better
+     match than function definition B if:
+
+       * for at least one function argument, the conversion for that argument
+         in A is better than the corresponding conversion in B; and
+
+       * there is no function argument for which the conversion in B is better
+         than the corresponding conversion in A.
+
+     If a single function definition is considered a better match than every
+     other matching function definition, it will be used.  Otherwise, a
+     semantic error occurs and the shader will fail to compile.
+
+     To determine whether the conversion for a single argument in one match is
+     better than that for another match, the following rules are applied, in
+     order:
+
+       1. An exact match is better than a match involving any implicit
+          conversion.
+
+       2. A match involving an implicit conversion from float to double is
+          better than a match involving any other implicit conversion.
+
+       3. A match involving an implicit conversion from either int or uint to
+          float is better than a match involving an implicit conversion from
+          either int or uint to double.
+
+     If none of the rules above apply to a particular pair of conversions,
+     neither conversion is considered better than the other.
+
+     For the function prototypes (A), (B), and (C) above, the following
+     examples show how the rules apply to different sets of calling argument
+     types:
+
+       f(vec4, vec4);        // exact match of vec4 f(in vec4 x, out vec4 y)
+       f(vec4, uvec4);       // exact match of vec4 f(in vec4 x, out ivec4 y)
+       f(vec4, ivec4);       // matched to vec4 f(in vec4 x, out vec4 y)
+                             //   (C) not relevant, can't convert vec4 to 
+                             //   ivec4.  (A) better than (B) for 2nd
+                             //   argument (rule 2), same on first argument.
+       f(ivec4, vec4);       // NOT matched.  All three match by implicit
+                             //   conversion.  (C) is better than (A) and (B)
+                             //   on the first argument.  (A) is better than
+                             //   (B) and (C).
+
+
+    Modify Section 8.3, Common Functions, p. 84
+
+    (add support for single-precision frexp and ldexp functions)
+
+    Syntax:
+
+      genType frexp(genType x, out genIType exp);
+      genType ldexp(genType x, in genIType exp);
+
+    The function frexp() splits each single-precision floating-point number in
+    <x> into a binary significand, a floating-point number in the range [0.5,
+    1.0), and an integral exponent of two, such that:
+
+      x = significand * 2 ^ exponent
+
+    The significand is returned by the function; the exponent is returned in
+    the parameter <exp>.  For a floating-point value of zero, the significant
+    and exponent are both zero.  For a floating-point value that is an
+    infinity or is not a number, the results of frexp() are undefined.  
+
+    If the input <x> is a vector, this operation is performed in a
+    component-wise manner; the value returned by the function and the value
+    written to <exp> are vectors with the same number of components as <x>.
+
+    The function ldexp() builds a single-precision floating-point number from
+    each significand component in <x> and the corresponding integral exponent
+    of two in <exp>, returning:
+
+      significand * 2 ^ exponent
+
+    If this product is too large to be represented as a single-precision
+    floating-point value, the result is considered undefined.
+
+    If the input <x> is a vector, this operation is performed in a
+    component-wise manner; the value passed in <exp> and returned by the
+    function are vectors with the same number of components as <x>.
+
+
+    (add support for new integer built-in functions)
+
+    Syntax:
+
+      genIType bitfieldExtract(genIType value, int offset, int bits);
+      genUType bitfieldExtract(genUType value, int offset, int bits);
+
+      genIType bitfieldInsert(genIType base, genIType insert, int offset, 
+                              int bits);
+      genUType bitfieldInsert(genUType base, genUType insert, int offset, 
+                              int bits);
+
+      genIType bitfieldReverse(genIType value);
+      genUType bitfieldReverse(genUType value);
+
+      genIType bitCount(genIType value);
+      genIType bitCount(genUType value);
+
+      genIType findLSB(genIType value);
+      genIType findLSB(genUType value);
+
+      genIType findMSB(genIType value);
+      genIType findMSB(genUType value);
+
+    The function bitfieldExtract() extracts bits <offset> through
+    <offset>+<bits>-1 from each component in <value>, returning them in the
+    least significant bits of corresponding component of the result.  For
+    unsigned data types, the most significant bits of the result will be set
+    to zero.  For signed data types, the most significant bits will be set to
+    the value of bit <offset>+<base>-1.  If <bits> is zero, the result will be
+    zero.  The result will be undefined if <offset> or <bits> is negative, or
+    if the sum of <offset> and <bits> is greater than the number of bits used
+    to store the operand.  Note that for vector versions of bitfieldExtract(),
+    a single pair of <offset> and <bits> values is shared for all components.
+
+    The function bitfieldInsert() inserts the <bits> least significant bits of
+    each component of <insert> into the corresponding component of <base>.
+    The result will have bits numbered <offset> through <offset>+<bits>-1
+    taken from bits 0 through <bits>-1 of <insert>, and all other bits taken
+    directly from the corresponding bits of <base>.  If <bits> is zero, the
+    result will simply be <base>.  The result will be undefined if <offset> or
+    <bits> is negative, or if the sum of <offset> and <bits> is greater than
+    the number of bits used to store the operand.  Note that for vector
+    versions of bitfieldInsert(), a single pair of <offset> and <bits> values
+    is shared for all components.
+
+    The function bitfieldReverse() reverses the bits of <value>.  The bit
+    numbered <n> of the result will be taken from bit (<bits>-1)-<n> of
+    <value>, where <bits> is the total number of bits used to represent
+    <value>.
+
+    The function bitCount() returns the number of one bits in the binary
+    representation of <value>.
+
+    The function findLSB() returns the bit number of the least significant one
+    bit in the binary representation of <value>.  If <value> is zero, -1 will
+    be returned.
+
+    The function findMSB() returns the bit number of the most significant bit
+    in the binary representation of <value>.  For positive integers, the
+    result will be the bit number of the most significant one bit.  For
+    negative integers, the result will be the bit number of the most
+    significant zero bit.  For a <value> of zero or negative one, -1 will be
+    returned.
+
+
+    (support for unsigned integer add/subtract with carry-out)
+
+    Syntax:
+
+      genUType uaddCarry(genUType x, genUType y, out genUType carry);
+      genUType usubBorrow(genUType x, genUType y, out genUType borrow);
+
+    The function uaddCarry() adds 32-bit unsigned integers or vectors <x> and
+    <y>, returning the sum modulo 2^32.  The value <carry> is set to zero if
+    the sum was less than 2^32, or one otherwise.
+
+    The function usubBorrow() subtracts the 32-bit unsigned integer or vector
+    <y> from <x>, returning the difference if non-negative or 2^32 plus the
+    difference, otherwise.  The value <borrow> is set to zero if x >= y, or
+    one otherwise.
+
+
+    (support for signed and unsigned multiplies, with 32-bit inputs and a
+     64-bit result spanning two 32-bit outputs)
+
+    Syntax:
+
+      void umulExtended(genUType x, genUType y, out genUType msb, 
+                        out genUType lsb);
+      void imulExtended(genIType x, genIType y, out genIType msb,
+                        out genIType lsb);
+
+    The functions umulExtended() and imulExtended() multiply 32-bit unsigned
+    or signed integers or vectors <x> and <y>, producing a 64-bit result.  The
+    32 least significant bits are returned in <lsb>; the 32 most significant
+    bits are returned in <msb>.
+
+
+GLX Protocol
+
+    None.
+
+Dependencies on ARB_gpu_shader_fp64
+
+    This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
+    of implicit conversions supported in the OpenGL Shading Language.  If more
+    than one of these extensions is supported, an expression of one type may
+    be converted to another type if that conversion is allowed by any of these
+    specifications.
+
+    If ARB_gpu_shader_fp64 or a similar extension introducing new data types
+    is not supported, the function overloading rule in the GLSL specification
+    preferring promotion an input parameters to smaller type to a larger type
+    is never applicable, as all data types are of the same size.  That rule
+    and the example referring to "double" should be removed.
+
+
+Dependencies on NV_gpu_shader5
+
+    This extension, ARB_gpu_shader_fp64, and NV_gpu_shader5 all modify the set
+    of implicit conversions supported in the OpenGL Shading Language.  If more
+    than one of these extensions is supported, an expression of one type may
+    be converted to another type if that conversion is allowed by any of these
+    specifications.
+
+    If NV_gpu_shader5 is supported, integer data types are supported with four
+    different precisions (8-, 16, 32-, and 64-bit) and floating-point data
+    types are supported with three different precisions (16-, 32-, and
+    64-bit).  The extension adds the following rule for output parameters,
+    which is similar to the one present in this extension for input
+    parameters:
+
+       5. If the formal parameters in both matches are output parameters, a
+          conversion from a type with a larger number of bits per component is
+          better than a conversion from a type with a smaller number of bits
+          per component.  For example, a conversion from an "int16_t" formal
+          parameter type to "int"  is better than one from an "int8_t" formal
+          parameter type to "int".
+
+    Such a rule is not provided in this extension because there is no
+    combination of types in this extension and ARB_gpu_shader_fp64 where this
+    rule has any effect.
+
+
+Errors
+
+    None
+
+
+New State
+
+    None
+
+New Implementation Dependent State
+
+    None
+
+Issues
+
+    (1) What should this extension be called?
+
+      UNRESOLVED.  This extension borrows from GL_ARB_gpu_shader5, so creating
+      some sort of a play on that name would be viable.  However, nothing in
+      this extension should require SM5 hardware, so such a name would be a
+      little misleading and weird.
+
+      Since the primary purpose is to add integer related functions from
+      GL_ARB_gpu_shader5, call this extension GL_MESA_shader_integer_functions
+      for now.
+
+    (2) Why is some of the formatting in this extension weird?
+
+      RESOLVED: This extension is formatted to minimize the differences (as
+      reported by 'diff --side-by-side -W180') with the GL_ARB_gpu_shader5
+      specification.
+
+    (3) Should ldexp and frexp be included?
+
+      RESOLVED: Yes.  Few GPUs have native instructions to implement these
+      functions.  These are generally implemented using existing GLSL built-in
+      functions and the other functions provided by this extension.
+
+    (4) Should umulExtended and imulExtended be included?
+
+      RESOLVED: Yes.  These functions should be implementable on any GPU that
+      can support the rest of this extension, but the implementation may be
+      complex.  The implementation on a GPU that only supports 32bit x 32bit =
+      32bit multiplication would be quite expensive.  However, many GPUs
+      (including OpenGL 4.0 GPUs that already support this function) have a
+      32bit x 16bit = 48bit multiplier.  The implementation there is only
+      trivially more expensive than regular 32bit multiplication.
+
+    (5) Should the pack and unpack functions be included?
+
+      RESOLVED: No.  These functions are already available via
+      GL_ARB_shading_language_packing.
+
+    (6) Should the "BitsTo" functions be included?
+
+      RESOLVED: No.  These functions are already available via
+      GL_ARB_shader_bit_encoding.
+
+Revision History
+
+    Rev.      Date     Author    Changes
+    ----  -----------  --------  -----------------------------------------
+     3    31-Mar-2017  Jon Leech Add ES support (OpenGL-Registry/issues/3)
+     2     7-Jul-2016  idr       Fix typo in #extension line
+     1    20-Jun-2016  idr       Initial version based on GL_ARB_gpu_shader5.

mesa 3D driver/docs/_extra/specs/MESA_swap_control.spec

@@ -0,0 +1,129 @@
+Name
+
+    MESA_swap_control
+
+Name Strings
+
+    GLX_MESA_swap_control
+
+Contact
+
+    Ian Romanick, IBM, idr at us.ibm.com
+
+Status
+
+    Deployed in DRI drivers post-XFree86 4.3.
+
+Version
+
+    Date: 5/1/2003   Revision: 1.1
+
+Number
+
+    ???
+
+Dependencies
+
+    None
+
+    Based on GLX_SGI_swap_control version 1.9 and WGL_EXT_swap_control
+    version 1.5.
+
+Overview
+
+    This extension allows an application to specify a minimum periodicity
+    of color buffer swaps, measured in video frame periods.
+
+Issues
+
+    * Should implementations that export GLX_MESA_swap_control also export
+      GL_EXT_swap_control for compatibility with WGL_EXT_swap_control?
+
+    UNRESOLVED.
+
+New Procedures and Functions
+
+    int glXSwapIntervalMESA(unsigned int interval)
+    int glXGetSwapIntervalMESA(void)
+
+New Tokens
+
+    None
+
+Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
+
+    None
+
+Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
+and the Framebuffer)
+
+    None
+
+Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
+
+    None
+
+Additions to the GLX 1.3 Specification
+
+    [Add the following to Section 3.3.10 of the GLX Specification (Double
+     Buffering)]
+
+    glXSwapIntervalMESA specifies the minimum number of video frame periods
+    per buffer swap.  (e.g. a value of two means that the color buffers
+    will be swapped at most every other video frame.)  A return value
+    of zero indicates success; otherwise an error occurred.  The interval
+    takes effect when glXSwapBuffers is first called subsequent to the
+    glXSwapIntervalMESA call.
+
+    A video frame period is the time required by the monitor to display a 
+    full frame of video data.  In the case of an interlaced monitor,
+    this is typically the time required to display both the even and odd 
+    fields of a frame of video data.
+
+    If <interval> is set to a value of 0, buffer swaps are not synchro-
+    nized to a video frame.  The <interval> value is silently clamped to
+    the maximum implementation-dependent value supported before being
+    stored.
+
+    The swap interval is not part of the render context state.  It cannot
+    be pushed or popped.  The current swap interval for the window
+    associated with the current context can be obtained by calling
+    glXGetSwapIntervalMESA.  The default swap interval is 0.
+
+    On XFree86, setting the environment variable LIBGL_THROTTLE_REFRESH sets
+    the swap interval to 1.
+
+Errors
+
+    glXSwapIntervalMESA returns GLX_BAD_CONTEXT if there is no current
+    GLXContext or if the current context is not a direct rendering context.
+
+GLX Protocol
+
+    None.  This extension only extends to direct rendering contexts.
+
+New State
+
+    Get Value		Get Command	Type	    Initial Value
+    ---------		-----------	----	    -------------
+    [swap interval]	GetSwapInterval	Z+	    0
+
+New Implementation Dependent State
+
+    None
+
+
+Revision History
+
+    1.1,  5/1/03   Added the issues section and contact information.
+    	  	   Changed the default swap interval to 0.
+    1.0,  3/17/03  Initial version based on GLX_SGI_swap_control and
+                   WGL_EXT_swap_control.

mesa 3D driver/docs/_extra/specs/MESA_swap_frame_usage.spec

@@ -0,0 +1,201 @@
+Name
+
+    MESA_swap_frame_usage
+
+Name Strings
+
+    GLX_MESA_swap_frame_usage
+
+Contact
+
+    Ian Romanick, IBM, idr at us.ibm.com
+
+Status
+
+    Deployed in DRI drivers post-XFree86 4.3.
+
+Version
+
+    Date: 5/1/2003   Revision: 1.1
+
+Number
+
+    ???
+
+Dependencies
+
+    GLX_SGI_swap_control affects the definition of this extension.
+    GLX_MESA_swap_control affects the definition of this extension.
+    GLX_OML_sync_control affects the definition of this extension.
+
+    Based on WGL_I3D_swap_frame_usage version 1.3.
+
+Overview
+
+    This extension allows an application to determine what portion of the
+    swap period has elapsed since the last swap operation completed.  The
+    "usage" value is a floating point value on the range [0,max] which is
+    calculated as follows:
+
+                              td
+                   percent = ----
+                              tf
+
+    where td is the time measured from the last completed buffer swap (or
+    call to enable the statistic) to when the next buffer swap completes, tf
+    is the entire time for a frame which may be multiple screen refreshes
+    depending on the swap interval as set by the GLX_SGI_swap_control or
+    GLX_OML_sync_control extensions. 
+
+    The value, percent, indicates the amount of time spent between the
+    completion of the two swaps.  If the value is in the range [0,1], the
+    buffer swap occurred within the time period required to maintain a
+    constant frame rate.  If the value is in the range (1,max], a constant
+    frame rate was not achieved.  The value indicates the number of frames
+    required to draw.
+
+    This definition of "percent" differs slightly from
+    WGL_I3D_swap_frame_usage.  In WGL_I3D_swap_frame_usage, the measurement
+    is taken from the completion of one swap to the issuance of the next.
+    This representation may not be as useful as measuring between
+    completions, as a significant amount of time may pass between the
+    issuance of a swap and the swap actually occurring.
+
+    There is also a mechanism to determine whether a frame swap was
+    missed.
+
+New Procedures and Functions
+
+    int glXGetFrameUsageMESA(Display *dpy,
+                             GLXDrawable drawable,
+    	                     float *usage)
+
+    int glXBeginFrameTrackingMESA(Display *dpy,
+                                  GLXDrawable drawable)
+
+    int glXEndFrameTrackingMESA(Display *dpy,
+                                GLXDrawable drawable)
+
+    int glXQueryFrameTrackingMESA(Display *dpy,
+                                  GLXDrawable drawable,
+				  int64_t *swapCount,
+                                  int64_t *missedFrames,
+                                  float *lastMissedUsage)
+
+New Tokens
+
+    None
+
+Additions to Chapter 2 of the 1.4 GL Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the 1.4 GL Specification (Rasterization)
+
+    None
+
+Additions to Chapter 4 of the 1.4 GL Specification (Per-Fragment Operations
+and the Framebuffer)
+
+    None
+
+Additions to Chapter 5 of the 1.4 GL Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the 1.4 GL Specification (State and State Requests)
+
+    None
+
+Additions to the GLX 1.3 Specification
+
+    The frame usage is measured as the percentage of the swap period elapsed
+    between two buffer-swap operations being committed.  In unextended GLX the
+    swap period is the vertical refresh time.  If SGI_swap_control or
+    MESA_swap_control are supported, the swap period is the vertical refresh
+    time multiplied by the swap interval (or one if the swap interval is set
+    to zero).
+    
+    If OML_sync_control is supported, the swap period is the vertical
+    refresh time multiplied by the divisor parameter to
+    glXSwapBuffersMscOML.  The frame usage in this case is less than 1.0 if
+    the swap is committed before target_msc, and is greater than or equal to
+    1.0 otherwise.  The actual usage value is based on the divisor and is
+    never less than 0.0.
+
+       int glXBeginFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable,
+				     float *usage)
+
+    glXGetFrameUsageMESA returns a floating-point value in <usage>
+    that represents the current swap usage, as defined above.
+
+    Missed frame swaps can be tracked by calling the following function:
+
+       int glXBeginFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable)
+
+    glXBeginFrameTrackingMESA resets a "missed frame" count and
+    synchronizes with the next frame vertical sync before it returns.
+    If a swap is missed based in the rate control specified by the
+    <interval> set by glXSwapIntervalSGI or the default swap of once
+    per frame, the missed frame count is incremented.
+
+    The current missed frame count and total number of swaps since
+    the last call to glXBeginFrameTrackingMESA can be obtained by
+    calling the following function:
+
+       int glXQueryFrameTrackingMESA(Display *dpy,
+                                     GLXDrawable drawable,
+				     int64_t *swapCount,
+                                     int64_t *missedFrames,
+                                     float *lastMissedUsage)
+
+    The location pointed to by <swapCount> will be updated with the
+    number of swaps that have been committed.  This value may not match the
+    number of swaps that have been requested since swaps may be
+    queued by the implementation.  This function can be called at any
+    time and does not synchronize to vertical blank.
+
+    The location pointed to by <missedFrames> will contain the number
+    swaps that missed the specified frame.  The frame usage for the
+    last missed frame is returned in the location pointed to by
+    <lastMissedUsage>.
+
+    Frame tracking is disabled by calling the function
+
+       int glXEndFrameTrackingMESA(Display *dpy,
+                                   GLXDrawable drawable)
+
+    This function will not return until all swaps have occurred.  The
+    application can call glXQueryFrameTrackingMESA for a final swap and
+    missed frame count.
+
+    If these functions are successful, zero is returned.  If the context
+    associated with dpy and drawable is not a direct context,
+    GLX_BAD_CONTEXT is returned.
+
+Errors
+
+    If the function succeeds, zero is returned.  If the function
+    fails, one of the following error codes is returned:
+
+       GLX_BAD_CONTEXT         The current rendering context is not a direct
+       			       context.
+
+GLX Protocol
+
+    None.  This extension only extends to direct rendering contexts.
+
+New State
+
+    None
+
+New Implementation Dependent State
+
+    None
+
+Revision History
+
+    1.1,  5/1/03   Added contact information.
+    1.0,  3/17/03  Initial version based on WGL_I3D_swap_frame_usage.

mesa 3D driver/docs/_extra/specs/MESA_texture_array.spec

@@ -0,0 +1,804 @@
+Name
+
+    MESA_texture_array
+
+Name Strings
+
+    GL_MESA_texture_array
+
+Contact
+
+    Ian Romanick, IBM (idr 'at' us.ibm.com)
+
+IP Status
+
+    No known IP issues.
+
+Status
+
+    DEPRECATED - Support removed in Mesa 10.1.
+
+Version
+
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.2 or GL_EXT_texture3D is required.
+
+    Support for ARB_fragment_program is assumed, but not required.
+
+    Support for ARB_fragment_program_shadow is assumed, but not required.
+
+    Support for EXT_framebuffer_object is assumed, but not required.
+
+    Written based on the wording of the OpenGL 2.0 specification and
+    ARB_fragment_program_shadow but not dependent on them.
+
+Overview
+
+    There are a number of circumstances where an application may wish to
+    blend two textures out of a larger set of textures.  Moreover, in some
+    cases the selected textures may vary on a per-fragment basis within
+    a polygon.  Several examples include:
+
+       1. High dynamic range textures.  The application stores several
+       different "exposures" of an image as different textures.  On a
+       per-fragment basis, the application selects which exposures are
+       used.
+
+       2. A terrain engine where the altitude of a point determines the
+       texture applied to it.  If the transition is from beach sand to
+       grass to rocks to snow, the application will store each texture
+       in a different texture map, and dynamically select which two
+       textures to blend at run-time.
+
+       3. Storing short video clips in textures.  Each depth slice is a
+       single frame of video.
+
+    Several solutions to this problem have been proposed, but they either
+    involve using a separate texture unit for each texture map or using 3D
+    textures without mipmaps.  Both of these options have major drawbacks.
+
+    This extension provides a third alternative that eliminates the major
+    drawbacks of both previous methods.  A new texture target,
+    TEXTURE_2D_ARRAY, is added that functions identically to TEXTURE_3D in
+    all aspects except the sizes of the non-base level images.  In
+    traditional 3D texturing, the size of the N+1 LOD is half the size
+    of the N LOD in all three dimensions.  For the TEXTURE_2D_ARRAY target,
+    the height and width of the N+1 LOD is halved, but the depth is the
+    same for all levels of detail. The texture then becomes an array of
+    2D textures.  The per-fragment texel is selected by the R texture
+    coordinate.
+
+    References:
+
+        https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011557
+        https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=000516
+        https://www.opengl.org/discussion_boards/cgi_directory/ultimatebb.cgi?ubb=get_topic;f=3;t=011903
+        http://www.delphi3d.net/articles/viewarticle.php?article=terraintex.htm
+
+New Procedures and Functions
+
+    All functions come directly from EXT_texture_array.
+
+    void FramebufferTextureLayerEXT(enum target, enum attachment,
+                                    uint texture, int level, int layer);
+
+New Tokens
+
+    All token names and values come directly from EXT_texture_array.
+
+    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, by
+    the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
+    GetDoublev, and by the <target> parameter of TexImage3D, GetTexImage,
+    GetTexLevelParameteriv, GetTexLevelParameterfv, GetTexParameteriv, and
+    GetTexParameterfv:
+
+        TEXTURE_1D_ARRAY_EXT                            0x8C18
+        TEXTURE_2D_ARRAY_EXT                            0x8C1A
+
+    Accepted by the <target> parameter of TexImage2D, TexSubImage2D,
+    CopyTexImage2D, CopyTexSubImage2D, CompressedTexImage2D,
+    CompressedTexSubImage2D, GetTexLevelParameteriv, and 
+    GetTexLevelParameterfv:
+
+        TEXTURE_1D_ARRAY_EXT
+        PROXY_TEXTURE_1D_ARRAY_EXT                      0x8C19
+
+    Accepted by the <target> parameter of TexImage3D, TexSubImage3D,
+    CopyTexSubImage3D, CompressedTexImage3D, CompressedTexSubImage3D,
+    GetTexLevelParameteriv, and GetTexLevelParameterfv:
+
+        TEXTURE_2D_ARRAY_EXT
+        PROXY_TEXTURE_2D_ARRAY_EXT                      0x8C1B
+
+    Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
+    GetFloatv, and GetDoublev
+
+        TEXTURE_BINDING_1D_ARRAY_EXT                    0x8C1C
+        TEXTURE_BINDING_2D_ARRAY_EXT                    0x8C1D
+        MAX_ARRAY_TEXTURE_LAYERS_EXT                    0x88FF
+
+    Accepted by the <param> parameter of TexParameterf, TexParameteri,
+    TexParameterfv, and TexParameteriv when the <pname> parameter is
+    TEXTURE_COMPARE_MODE_ARB:
+
+        COMPARE_REF_DEPTH_TO_TEXTURE_EXT                0x884E
+
+    (Note:  COMPARE_REF_DEPTH_TO_TEXTURE_EXT is simply an alias for the
+    existing COMPARE_R_TO_TEXTURE token in OpenGL 2.0; the alternate name
+    reflects the fact that the R coordinate is not always used.)
+
+    Accepted by the <internalformat> parameter of TexImage3D and
+    CompressedTexImage3D, and by the <format> parameter of
+    CompressedTexSubImage3D:
+
+        COMPRESSED_RGB_S3TC_DXT1_EXT
+        COMPRESSED_RGBA_S3TC_DXT1_EXT
+        COMPRESSED_RGBA_S3TC_DXT3_EXT
+        COMPRESSED_RGBA_S3TC_DXT5_EXT
+
+    Accepted by the <pname> parameter of
+    GetFramebufferAttachmentParameterivEXT:
+
+        FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT          0x8CD4
+
+    (Note:  FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is simply an alias for the
+    FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_EXT token provided in
+    EXT_framebuffer_object.  This extension generalizes the notion of
+    "<zoffset>" to include layers of an array texture.)
+
+Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
+
+    -- Section 3.8.1 "Texture Image Specification"
+
+       Change the first paragraph (page 150) to say (spec changes identical to
+       EXT_texture_array):
+
+       "The command
+
+         void TexImage3D(enum target, int level, int internalformat,
+                         sizei width, sizei height, sizei depth, int border,
+                         enum format, enum type, void *data);
+
+       is used to specify a three-dimensional texture image. target must be one
+       one of TEXTURE_3D for a three-dimensional texture or
+       TEXTURE_2D_ARRAY_EXT for an two-dimensional array texture.
+       Additionally, target may be either PROXY_TEXTURE_3D for a
+       three-dimensional proxy texture, or PROXY_TEXTURE_2D_ARRAY_EXT for a
+       two-dimensional proxy array texture."
+
+       Change the fourth paragraph on page 151 to say (spec changes identical
+       to EXT_texture_array):
+
+       "Textures with a base internal format of DEPTH_COMPONENT are supported
+       by texture image specification commands only if target is TEXTURE_1D,
+       TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_2D_ARRAY_EXT,
+       PROXY_TEXTURE_1D, PROXY_TEXTURE_2D, PROXY_TEXTURE_1D_ARRAY_EXT, or
+       PROXY_TEXTURE_2D_ARRAY_EXT. Using this format in conjunction with any
+       other target will result in an INVALID_OPERATION error."
+
+
+       Change the fourth paragraph on page 156 to say (spec changes identical
+       to EXT_texture_array):
+       
+       "The command
+
+         void TexImage2D(enum target, int level,
+                         int internalformat, sizei width, sizei height,
+                         int border, enum format, enum type, void *data);
+
+       is used to specify a two-dimensional texture image. target must be one
+       of TEXTURE_2D for a two-dimensional texture, TEXTURE_1D_ARRAY_EXT for a
+       one-dimensional array texture, or one of TEXTURE_CUBE_MAP_POSITIVE_X,
+       TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE_MAP_POSITIVE_Y,
+       TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
+       TEXTURE_CUBE_MAP_NEGATIVE_Z for a cube map texture. Additionally,
+       target may be either PROXY_TEXTURE_2D for a two-dimensional proxy
+       texture, PROXY_TEXTURE_1D_ARRAY_EXT for a one-dimensional proxy array
+       texture, or PROXY TEXTURE_CUBE_MAP for a cube map proxy texture in the
+       special case discussed in section 3.8.11.  The other parameters match
+       the corresponding parameters of TexImage3D.
+
+       For the purposes of decoding the texture image, TexImage2D is
+       equivalent to calling TexImage3D with corresponding arguments and depth
+       of 1, except that
+
+         * The border depth, d_b, is zero, and the depth of the image is
+           always 1 regardless of the value of border. 
+
+         * The border height, h_b, is zero if <target> is
+           TEXTURE_1D_ARRAY_EXT, and <border> otherwise.
+
+         * Convolution will be performed on the image (possibly changing its
+           width and height) if SEPARABLE 2D or CONVOLUTION 2D is enabled.
+
+         * UNPACK SKIP IMAGES is ignored."
+
+    -- Section 3.8.2 "Alternate Texture Image Specification Commands"
+
+       Change the second paragraph (page 159) (spec changes identical
+       to EXT_texture_array):
+
+       "The command
+
+         void CopyTexImage2D(enum target, int level,
+                             enum internalformat, int x, int y, sizei width,
+                             sizei height, int border);
+
+       defines a two-dimensional texture image in exactly the manner of
+       TexImage2D, except that the image data are taken from the framebuffer
+       rather than from client memory. Currently, target must be one of
+       TEXTURE_2D, TEXTURE_1D_ARRAY_EXT, TEXTURE_CUBE_MAP_POSITIVE_X,
+       TEXTURE_CUBE_MAP_NEGATIVE_X, TEXTURE_CUBE MAP_POSITIVE_Y,
+       TEXTURE_CUBE_MAP_NEGATIVE_Y, TEXTURE_CUBE_MAP_POSITIVE_Z, or
+       TEXTURE_CUBE_MAP_NEGATIVE_Z.
+
+
+       Change the last paragraph on page 160 to say (spec changes identical
+       to EXT_texture_array):
+
+       "Currently the target arguments of TexSubImage1D and CopyTexSubImage1D
+       must be TEXTURE_1D, the target arguments of TexSubImage2D and
+       CopyTexSubImage2D must be one of TEXTURE_2D, TEXTURE_1D_ARRAY_EXT,
+       TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X,
+       TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y,
+       TEXTURE_CUBE_MAP_POSITIVE_Z, or TEXTURE_CUBE_MAP_NEGATIVE_Z, and the
+       target arguments of TexSubImage3D and CopyTexSubImage3D must be
+       TEXTURE_3D or TEXTURE_2D_ARRAY_EXT. ..."
+
+
+    -- Section 3.8.4 "Texture Parameters"
+
+       Change the first paragraph (page 166) to say:
+
+       "Various parameters control how the texel array is treated when
+       specified or changed, and when applied to a fragment. Each parameter is
+       set by calling
+
+         void TexParameter{if}(enum target, enum pname, T param); 
+         void TexParameter{if}v(enum target, enum pname, T params);
+
+       target is the target, either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
+       TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT."
+
+
+    -- Section 3.8.8 "Texture Minification" in the section "Scale Factor and Level of Detail"
+
+       Change the first paragraph (page 172) to say:
+
+       "Let s(x,y) be the function that associates an s texture coordinate
+       with each set of window coordinates (x,y) that lie within a primitive;
+       define t(x,y) and r(x,y) analogously.  Let u(x,y) = w_t * s(x,y),
+       v(x,y) = h_t * t(x,y), and w(x,y) = d_t * r(x,y), where w_t, h_t,
+       and d_t are as defined by equations 3.15, 3.16, and 3.17 with
+       w_s, h_s, and d_s equal to the width, height, and depth of the
+       image array whose level is level_base.  For a one-dimensional
+       texture or a one-dimensional array texture, define v(x,y) = 0 and
+       w(x,y) = 0; for a two-dimensional texture or a two-dimensional array
+       texture, define w(x,y) = 0..."
+
+    -- Section 3.8.8 "Texture Minification" in the section "Mipmapping"
+
+       Change the third paragraph (page 174) to say:
+       
+       "For a two-dimensional texture, two-dimensional array texture, or
+       cube map texture,"
+
+       Change the fourth paragraph (page 174) to say:
+
+       "And for a one-dimensional texture or a one-dimensional array texture,"
+
+       After the first paragraph (page 175) add:
+
+       "For one-dimensional array textures, h_b and d_b are treated as 1,
+       regardless of the actual values, when performing mipmap calculations.
+       For two-dimensional array textures, d_b is always treated as one,
+       regardless of the actual value, when performing mipmap calculations."
+
+    -- Section 3.8.8 "Automatic Mipmap Generation" in the section "Mipmapping"
+
+       Change the third paragraph (page 176) to say (spec changes identical
+       to EXT_texture_array):
+
+       "The contents of the derived arrays are computed by repeated, filtered
+       reduction of the level_base array.  For one- and two-dimensional array
+       textures, each layer is filtered independently.  ..."
+
+    -- Section 3.8.8 "Manual Mipmap Generation" in the section "Mipmapping"
+
+       Change first paragraph to say (spec changes identical to
+       EXT_texture_array):
+
+       "Mipmaps can be generated manually with the command
+
+         void GenerateMipmapEXT(enum target);
+
+       where <target> is one of TEXTURE_1D, TEXTURE_2D, TEXTURE_CUBE_MAP,
+       TEXTURE_3D, TEXTURE_1D_ARRAY, or TEXTURE_2D_ARRAY.  Mipmap generation
+       affects the texture image attached to <target>.  ..."
+
+    -- Section 3.8.10 "Texture Completeness"
+
+       Change the second paragraph (page 177) to say (spec changes identical
+       to EXT_texture_array):
+
+       "For one-, two-, or three-dimensional textures and one- or
+       two-dimensional array textures, a texture is complete if the following
+       conditions all hold true:"
+
+    -- Section 3.8.11 "Texture State and Proxy State"
+
+       Change the second and third paragraphs (page 179) to say (spec changes
+       identical to EXT_texture_array):
+
+       "In addition to image arrays for one-, two-, and three-dimensional
+       textures, one- and two-dimensional array textures, and the six image
+       arrays for the cube map texture, partially instantiated image arrays
+       are maintained for one-, two-, and three-dimensional textures and one-
+       and two-dimensional array textures.  Additionally, a single proxy image
+       array is maintained for the cube map texture.  Each proxy image array
+       includes width, height, depth, border width, and internal format state
+       values, as well as state for the red, green, blue, alpha, luminance,
+       and intensity component resolutions. Proxy image arrays do not include
+       image data, nor do they include texture properties. When TexImage3D is
+       executed with target specified as PROXY_TEXTURE_3D, the
+       three-dimensional proxy state values of the specified level-of-detail
+       are recomputed and updated. If the image array would not be supported
+       by TexImage3D called with target set to TEXTURE 3D, no error is
+       generated, but the proxy width, height, depth, border width, and
+       component resolutions are set to zero. If the image array would be
+       supported by such a call to TexImage3D, the proxy state values are set
+       exactly as though the actual image array were being specified. No pixel
+       data are transferred or processed in either case.
+
+       Proxy arrays for one- and two-dimensional textures and one- and
+       two-dimensional array textures are operated on in the same way when
+       TexImage1D is executed with target specified as PROXY_TEXTURE_1D,
+       TexImage2D is executed with target specified as PROXY_TEXTURE_2D or
+       PROXY_TEXTURE_1D_ARRAY_EXT, or TexImage3D is executed with target
+       specified as PROXY_TETXURE_2D_ARRAY_EXT."
+
+    -- Section 3.8.12 "Texture Objects"
+
+       Change section (page 180) to say (spec changes identical to 
+       EXT_texture_array):
+
+       "In addition to the default textures TEXTURE_1D, TEXTURE_2D,
+       TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_EXT,
+       named one-, two-, and three-dimensional, cube map, and one- and
+       two-dimensional array texture objects can be created and operated upon.
+       The name space for texture objects is the unsigned integers, with zero
+       reserved by the GL.
+
+       A texture object is created by binding an unused name to TEXTURE_1D,
+       TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
+       TEXTURE_2D_ARRAY_EXT. The binding is effected by calling
+
+         void BindTexture(enum target, uint texture);
+
+       with <target> set to the desired texture target and <texture> set to
+       the unused name.  The resulting texture object is a new state vector,
+       comprising all the state values listed in section 3.8.11, set to the
+       same initial values. If the new texture object is bound to TEXTURE_1D,
+       TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
+       TEXTURE_2D_ARRAY_EXT, it is and remains a one-, two-,
+       three-dimensional, cube map, one- or two-dimensional array texture
+       respectively until it is deleted.
+
+       BindTexture may also be used to bind an existing texture object to
+       either TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
+       TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT. The error
+       INVALID_OPERATION is generated if an attempt is made to bind a texture
+       object of different dimensionality than the specified target. If the
+       bind is successful no change is made to the state of the bound texture
+       object, and any previous binding to target is broken.
+
+       While a texture object is bound, GL operations on the target to which
+       it is bound affect the bound object, and queries of the target to which
+       it is bound return state from the bound object. If texture mapping of
+       the dimensionality of the target to which a texture object is bound is
+       enabled, the state of the bound texture object directs the texturing
+       operation.
+
+       In the initial state, TEXTURE_1D, TEXTURE_2D, TEXTURE_3D,
+       TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and TEXTURE_2D_ARRAY_EXT have
+       one-, two-, three-dimensional, cube map, and one- and two-dimensional
+       array texture state vectors respectively associated with them. In order
+       that access to these initial textures not be lost, they are treated as
+       texture objects all of whose names are 0. The initial one-, two-,
+       three-dimensional, cube map, one- and two-dimensional array textures
+       are therefore operated upon, queried, and applied as TEXTURE_1D,
+       TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, and
+       TEXTURE_2D_ARRAY_EXT respectively while 0 is bound to the corresponding
+       targets.
+
+       Change second paragraph on page 181 to say (spec changes identical to 
+       EXT_texture_array):
+       
+       "...  If a texture that is currently bound to one of the targets
+       TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP,
+       TEXTURE_1D_ARRAY_EXT, or TEXTURE_2D_ARRAY_EXT is deleted, it is as
+       though BindTexture had been executed with the same target and texture
+       zero. ..."
+
+       Change second paragraph on page 182 to say (spec changes identical to 
+       EXT_texture_array):
+       
+       "The texture object name space, including the initial one-, two-, and
+       three dimensional, cube map, and one- and two-dimensional array texture
+       objects, is shared among all texture units. ..."
+
+
+    -- Section 3.8.14 "Depth Texture Comparison Modes" in "Texture Comparison Modes"
+
+       Change second through fourth paragraphs (page 188) to say:
+
+       "Let D_t be the depth texture value, in the range [0, 1].  For
+       texture lookups from one- and two-dimensional, rectangle, and
+       one-dimensional array targets, let R be the interpolated <r>
+       texture coordinate, clamped to the range [0, 1].  For texture lookups
+       from two-dimensional array texture targets, let R be the interpolated
+       <q> texture coordinate, clamped to the range [0, 1].  Then the
+       effective texture value L_t, I_t, or A_t is computed as follows:
+
+       If the value of TEXTURE_COMPARE_MODE is NONE, then
+
+          r = Dt
+
+       If the value of TEXTURE_COMPARE_MODE is
+       COMPARE_REF_DEPTH_TO_TEXTURE_EXT), then r depends on the texture
+       comparison function as shown in table 3.27."
+
+    -- Section 3.8.15 "Texture Application"
+
+       Change the first paragraph (page 189) to say:
+
+       "Texturing is enabled or disabled using the generic Enable and Disable
+       commands, respectively, with the symbolic constants TEXTURE_1D,
+       TEXTURE_2D, TEXTURE_3D, TEXTURE_CUBE_MAP, TEXTURE_1D_ARRAY_EXT, or
+       TEXTURE_2D_ARRAY_EXT to enable one-, two-, three-dimensional, cube
+       map, one-dimensional array, or two-dimensional array texture,
+       respectively.  If both two- and one-dimensional textures are enabled,
+       the two-dimensional texture is used.  If the three-dimensional and
+       either of the two- or one-dimensional textures is enabled, the
+       three-dimensional texture is used.  If the cube map texture and any of
+       the three-, two-, or one-dimensional textures is enabled, then cube map
+       texturing is used.  If one-dimensional array texture is enabled and any
+       of cube map, three-, two-, or one-dimensional textures is enabled, 
+       one-dimensional array texturing is used.  If two-dimensional array
+       texture is enabled and any of cube map, three-, two-, one-dimensional
+       textures or one-dimensional array texture is enabled, two-dimensional
+       array texturing is used..."
+
+    -- Section 3.11.2 of ARB_fragment_program (Fragment Program Grammar and Restrictions):
+
+       (mostly add to existing grammar rules)
+
+       <optionName>           ::= "MESA_texture_array"
+
+       <texTarget>            ::= "1D"
+                               | "2D"
+                               | "3D"
+                               | "CUBE"
+                               | "RECT"
+                               | <arrayTarget> (if program option is present)
+                               | <shadowTarget> (if program option is present)
+
+       <arrayTarget>          ::= "ARRAY1D"
+                               | "ARRAY2D"
+
+       <shadowTarget>         ::= "SHADOW1D"
+                               | "SHADOW2D"
+                               | "SHADOWRECT"
+                               | <shadowArrayTarget> (if program option is present)
+
+       <shadowArrayTarget>    ::= "SHADOWARRAY1D"
+                               | "SHADOWARRAY2D"
+
+
+    -- Add Section 3.11.4.5.4 "Texture Stack Option"
+
+       "If a fragment program specifies the "MESA_texture_array" program
+       option, the <texTarget> rule is modified to add the texture targets
+       ARRAY1D and ARRAY2D (See Section 3.11.2)."
+
+    -- Section 3.11.6 "Fragment Program Texture Instruction Set"
+
+       (replace 1st and 2nd paragraphs with the following paragraphs)
+
+       "The first three texture instructions described below specify the
+       mapping of 4-tuple input vectors to 4-tuple output vectors.
+       The sampling of the texture works as described in section 3.8,
+       except that texture environments and texture functions are not
+       applicable, and the texture enables hierarchy is replaced by explicit
+       references to the desired texture target (i.e., 1D, 2D, 3D, cube map,
+       rectangle, ARRAY1D, ARRAY2D).  These texture instructions specify
+       how the 4-tuple is mapped into the coordinates used for sampling.  The
+       following function is used to describe the texture sampling in the
+       descriptions below: 
+
+         vec4 TextureSample(vec4 coord, float lodBias, int texImageUnit,
+                            enum texTarget);
+
+       Note that not all four components of the texture coordinates <coord>
+       are used by all texture targets.  Component usage for each <texTarget>
+       is defined in table X.
+
+                                                        coordinates used
+         texTarget          Texture Type               s t r  layer  shadow
+         ----------------   ---------------------      -----  -----  ------
+         1D                 TEXTURE_1D                 x - -    -      -
+         2D                 TEXTURE_2D                 x y -    -      -
+         3D                 TEXTURE_3D                 x y z    -      -
+         CUBE               TEXTURE_CUBE_MAP           x y z    -      -
+         RECT               TEXTURE_RECTANGLE_ARB      x y -    -      -
+         ARRAY1D            TEXTURE_1D_ARRAY_EXT       x - -    y      -
+         ARRAY2D            TEXTURE_2D_ARRAY_EXT       x y -    z      -
+         SHADOW1D           TEXTURE_1D                 x - -    -      z
+         SHADOW2D           TEXTURE_2D                 x y -    -      z
+         SHADOWRECT         TEXTURE_RECTANGLE_ARB      x y -    -      z
+         SHADOWARRAY1D      TEXTURE_1D_ARRAY_EXT       x - -    y      z
+         SHADOWARRAY2D      TEXTURE_2D_ARRAY_EXT       x y -    z      w
+
+         Table X:  Texture types accessed for each of the <texTarget>, and
+         coordinate mappings.  The "coordinates used" column indicate the
+         input values used for each coordinate of the texture lookup, the
+         layer selector for array textures, and the reference value for
+         texture comparisons."
+
+    -- Section 3.11.6.2 "TXP: Project coordinate and map to color"
+    
+       Add to the end of the section:
+       
+       "A program will fail to load if the TXP instruction is used in
+       conjunction with the SHADOWARRAY2D target."
+
+Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment Operations)
+
+    -- Section 4.4.2.3 "Attaching Texture Images to a Framebuffer"
+
+       Add to the end of the section (spec changes identical to
+       EXT_texture_array):
+
+       "The command
+
+         void FramebufferTextureLayerEXT(enum target, enum attachment,
+                                         uint texture, int level, int layer);
+
+       operates identically to FramebufferTexture3DEXT, except that it
+       attaches a single layer of a three-dimensional texture or a one- or
+       two-dimensional array texture.  <layer> is an integer indicating the
+       layer number, and is treated identically to the <zoffset> parameter in
+       FramebufferTexture3DEXT.  The error INVALID_VALUE is generated if
+       <layer> is negative.  The error INVALID_OPERATION is generated if
+       <texture> is non-zero and is not the name of a three dimensional
+       texture or one- or two-dimensional array texture.  Unlike
+       FramebufferTexture3D, no <textarget> parameter is accepted.
+
+       If <texture> is non-zero and the command does not result in an error,
+       the framebuffer attachment state corresponding to <attachment> is
+       updated as in the other FramebufferTexture commands, except that
+       FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT is set to <layer>."
+
+    -- Section 4.4.4.1 "Framebuffer Attachment Completeness"
+
+      Add to the end of the list of completeness rules (spec changes
+      identical to EXT_texture_array):
+
+        "* If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and
+           FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a one- or 
+           two-dimensional array texture, then
+           FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT must be smaller than the
+           number of layers in the texture."
+
+Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
+
+    -- Section 5.4 "Display Lists"
+
+       Change the first paragraph on page 242 to say (spec changes
+       identical to EXT_texture_array):
+
+       "TexImage3D, TexImage2D, TexImage1D, Histogram, and ColorTable are
+       executed immediately when called with the corresponding proxy arguments
+       PROXY_TEXTURE_3D or PROXY_TEXTURE_2D_ARRAY_EXT; PROXY_TEXTURE_2D,
+       PROXY_TEXTURE_CUBE_MAP, or PROXY_TEXTURE_1D_ARRAY_EXT;
+       PROXY_TEXTURE_1D; PROXY_HISTOGRAM; and PROXY_COLOR_TABLE,
+       PROXY_POST_CONVOLUTION_COLOR_TABLE, or
+       PROXY_POST_COLOR_MATRIX_COLOR_TABLE."
+
+Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State Requests)
+
+    -- Section 6.1.3 "Enumerated Queries"
+
+       Add after the line beginning "If the value of
+       FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE" (spec changes
+       identical to EXT_texture_array):
+
+       "If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER_EXT and the
+       texture object named FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is a
+       three-dimensional texture or a one- or two-dimensional array texture,
+       then <params> will contain the number of texture layer attached to the
+       attachment point.  Otherwise, <params> will contain the value zero."
+
+    -- Section 6.1.4 "Texture Queries"
+    
+       Change the first three paragraphs (page 248) to say (spec changes
+       identical to EXT_texture_array):
+
+       "The command
+
+         void GetTexImage(enum tex, int lod, enum format,
+                          enum type, void *img);
+
+       is used to obtain texture images. It is somewhat different from the
+       other get commands; tex is a symbolic value indicating which texture
+       (or texture face in the case of a cube map texture target name) is to
+       be obtained.  TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, TEXTURE_1D_ARRAY_EXT,
+       and TEXTURE_2D_ARRAY_EXT indicate a one-, two-, or three-dimensional
+       texture, or one- or two-dimensional array texture, respectively.
+       TEXTURE_CUBE_MAP_POSITIVE_X, ...
+
+       GetTexImage obtains... from the first image to the last for
+       three-dimensional textures.  One- and two-dimensional array textures
+       are treated as two- and three-dimensional images, respectively, where
+       the layers are treated as rows or images.  These groups are then...
+
+       For three-dimensional and two-dimensional array textures, pixel storage
+       operations are applied as if the image were two-dimensional, except
+       that the additional pixel storage state values PACK_IMAGE_HEIGHT and
+       PACK_SKIP_IMAGES are applied. ..."
+
+Additions to Appendix A of the OpenGL 2.0 Specification (Invariance)
+
+    None
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None
+
+GLX Protocol
+
+    None
+
+Dependencies on ARB_fragment_program
+
+    If ARB_fragment_program is not supported, the changes to section 3.11
+    should be ignored.
+
+Dependencies on EXT_framebuffer_object
+
+    If EXT_framebuffer_object is not supported, the changes to section
+    3.8.8 ("Manual Mipmap Generation"), 4.4.2.3, and 6.1.3 should be ignored.
+
+Dependencies on EXT_texture_compression_s3tc and NV_texture_compression_vtc
+
+    (Identical dependency as EXT_texture_array.)
+
+    S3TC texture compression is supported for two-dimensional array textures.
+    When <target> is TEXTURE_2D_ARRAY_EXT, each layer is stored independently
+    as a compressed two-dimensional textures.  When specifying or querying
+    compressed images using one of the S3TC formats, the images are provided
+    and/or returned as a series of two-dimensional textures stored
+    consecutively in memory, with the layer closest to zero specified first.
+    For array textures, images are not arranged in 4x4x4 or 4x4x2 blocks as in
+    the three-dimensional compression format provided in the
+    EXT_texture_compression_vtc extension.  Pixel store parameters, including
+    those specific to three-dimensional images, are ignored when compressed
+    image data are provided or returned, as in the
+    EXT_texture_compression_s3tc extension.
+
+    S3TC compression is not supported for one-dimensional texture targets in
+    EXT_texture_compression_s3tc, and is not supported for one-dimensional
+    array textures in this extension.  If compressed one-dimensional arrays
+    are needed, use a two-dimensional texture with a height of one.
+
+    This extension allows the use of the four S3TC internal format types in
+    TexImage3D, CompressedTexImage3D, and CompressedTexSubImage3D calls.
+
+Errors
+
+    None
+
+New State
+
+    (add to table 6.15, p. 276)
+
+                                                     Initial
+    Get Value                     Type   Get Command  Value Description           Sec.    Attribute
+    ----------------------------  -----  -----------  ----- --------------------  ------  ---------
+    TEXTURE_BINDING_1D_ARRAY_EXT  2*xZ+  GetIntegerv    0   texture object bound  3.8.12  texture
+                                                            to TEXTURE_1D_ARRAY
+    TEXTURE_BINDING_2D_ARRAY_EXT  2*xZ+  GetIntegerv    0   texture object bound  3.8.12  texture
+                                                            to TEXTURE_2D_ARRAY
+
+
+New Implementation Dependent State
+
+    (add to Table 6.32, p. 293)
+
+                                                    Minimum
+    Get Value                     Type  Get Command  Value  Description         Sec.  Attribute
+    ----------------------------  ----  ----------- ------- ------------------  ----- ---------
+    MAX_TEXTURE_ARRAY_LAYERS_EXT   Z+   GetIntegerv   64    maximum number of   3.8.1     -
+                                                            layers for texture
+                                                            arrays
+
+Issues
+
+    (1) Is "texture stack" a good name for this functionality?
+
+        NO.  The name is changed to "array texture" to match the
+        nomenclature used by GL_EXT_texture_array.
+
+    (2) Should the R texture coordinate be treated as normalized or
+    un-normalized?  If it were un-normalized, floor(R) could be thought
+    of as a direct index into the array texture.  This may be more
+    convenient for applications.
+
+        RESOLVED.  All texture coordinates are normalized.  The issue of
+        un-normalized texture coordinates has been discussed in the ARB
+        before and should be left for a layered extension.
+
+        RE-RESOLVED.  The R coordinate is un-normalized.  Accessing an array
+        using [0, layers-1] coordinates is much more natural.
+
+    (3) How does LOD selection work for stacked textures?
+
+        RESOLVED.  For 2D array textures the R coordinate is ignored, and
+        the LOD selection equations for 2D textures are used.  For 1D
+        array textures the T coordinate is ignored, and the LOD selection
+        equations for 1D textures are used.  The expected usage is in a
+        fragment program with an explicit LOD selection.
+
+    (4) What is the maximum size of a 2D array texture?  Is it the same
+    as for a 3D texture, or should a new query be added?  How about for 1D
+    array textures?
+
+        RESOLVED.  A new query is added.
+
+    (5) How are array textures exposed in GLSL?
+    
+        RESOLVED.  Use GL_EXT_texture_array.
+        
+    (6) Should a 1D array texture also be exposed?
+
+        RESOLVED.  For orthogonality, yes.
+
+    (7) How are stacked textures attached to framebuffer objects?
+
+        RESOLVED.  Layers of both one- and two-dimensional array textures
+        are attached using FreambufferTextureLayerEXT.  Once attached, the
+        array texture layer behaves exactly as either a one- or
+        two-dimensional texture.
+
+    (8) How is this extension related to GL_EXT_texture_array?
+    
+        This extension adapats GL_MESAX_texture_stack to the notation,
+        indexing, and FBO access of GL_EXT_texture_array.  This extension
+        replaces the GLSL support of GL_EXT_texture_array with
+        GL_ARB_fragment_program support.
+
+        Assembly program support is also provided by GL_NV_gpu_program4.
+        GL_NV_gpu_program4 also adds support for other features that are
+        specific to Nvidia hardware, while this extension adds only support
+        for array textures.
+
+        Much of text of this extension that has changed since
+        GL_MESAX_texture_stack comes directly from either
+        GL_EXT_texture_array or GL_NV_gpu_program4.
+
+Revision History
+
+    ||2005/11/15||0.1||idr||Initial draft MESAX version.||
+    ||2005/12/07||0.2||idr||Added framebuffer object interactions.||
+    ||2005/12/12||0.3||idr||Updated fragment program interactions.||
+    ||2007/05/16||0.4||idr||Converted to MESA_texture_array.  Brought in line with EXT_texture_array and NV_gpu_program4.||

mesa 3D driver/docs/_extra/specs/MESA_texture_signed_rgba.spec

@@ -0,0 +1,214 @@
+Name
+
+    MESA_texture_signed_rgba
+
+Name Strings
+
+    GL_MESA_texture_signed_rgba
+
+Contact
+
+
+
+Notice
+
+
+
+IP Status
+
+    No known IP issues
+
+Status
+
+
+
+Version
+
+    0.3, 2009-03-24
+
+Number
+
+    Not assigned ?
+
+Dependencies
+
+    Written based on the wording of the OpenGL 2.0 specification.
+
+    This extension trivially interacts with ARB_texture_float.
+    This extension shares some language with ARB_texture_compression_rgtc
+    but does not depend on it.
+
+Overview
+
+    OpenGL prior to 3.1 does not support any signed texture formats.
+    ARB_texture_compression_rgtc introduces some compressed red and
+    red_green signed formats but no uncompressed ones, which might
+    still be useful. NV_texture_shader adds signed texture formats,
+    but also a lot of functionality which has been superseded by fragment
+    shaders.
+    It is usually possible to get the same functionality
+    using a unsigned format by doing scale and bias in a shader, but this
+    is undesirable since modern hardware has direct support for this.
+    This extension adds a signed 4-channel texture format by backporting
+    the relevant features from OpenGL 3.1, as a means to support this in
+    OpenGL implementations only supporting older versions.
+
+Issues
+
+    1) What should this extension be called?
+
+       RESOLVED: MESA_texture_signed_rgba seems reasonable.
+       The rgba part is there because only 4 channel format is supported.
+
+
+    2) Should the full set of signed formats (alpha, luminance, rgb, etc.)
+       be supported?
+
+       RESOLVED: NO. To keep this extension simple, only add the most
+       universal format, rgba. alpha/luminance can't be trivially supported
+       since OpenGL 3.1 does not support them any longer, and there is some
+       implied dependency on ARB_texture_rg for red/red_green formats so
+       avoid all this. Likewise, only 8 bits per channel is supported.
+
+
+    3) Should this extension use new enums for the texture formats?
+
+       RESOLVED: NO. Same enums as those used in OpenGL 3.1.
+
+
+    4) How are signed integer values mapped to floating-point values?
+
+       RESOLVED: Same as described in issue 5) of
+       ARB_texture_compression_rgtc (quote):
+       A signed 8-bit two's complement value X is computed to
+       a floating-point value Xf with the formula:
+
+                { X / 127.0, X > -128
+           Xf = {
+                { -1.0,      X == -128
+
+       This conversion means -1, 0, and +1 are all exactly representable,
+       however -128 and -127 both map to -1.0.  Mapping -128 to -1.0
+       avoids the numerical awkwardness of have a representable value
+       slightly more negative than -1.0.
+
+       This conversion is intentionally NOT the "byte" conversion listed
+       in Table 2.9 for component conversions.  That conversion says:
+
+           Xf = (2*X + 1) / 255.0
+
+       The Table 2.9 conversion is incapable of exactly representing
+       zero.
+
+       (Difference to ARB_texture_compression_rgtc):
+       This is the same mapping as OpenGL 3.1 uses.
+       This is also different to what NV_texture_shader used.
+       The above mapping should be considered the reference, but there
+       is some leeway so other mappings are allowed for implementations which
+       cannot do this. Particularly the mapping given in NV_texture_shader or
+       the standard OpenGL byte/float mapping is considered acceptable too, as
+       might be a mapping which represents -1.0 by -128, 0.0 by 0 and 1.0 by
+       127 (that is, uses different scale factors for negative and positive
+       numbers).
+       Also, it is ok to store incoming GL_BYTE user data as-is, without
+       converting to GL_FLOAT (using the standard OpenGL float/byte mapping)
+       and converting back (using the mapping described here).
+       Other than those subtle issues there are no other non-standard
+       conversions used, so when using for instance CopyTexImage2D with
+       a framebuffer clamped to [0,1] all converted numbers will be in the range
+       [0, 127] (and not scaled and biased).
+
+
+    5) How will signed components resulting from RGBA8_SNORM texture
+       fetches interact with fragment coloring?
+
+       RESOLVED: Same as described in issue 6) of
+       ARB_texture_compression_rgtc (quote):
+       The specification language for this extension is silent
+       about clamping behavior leaving this to the core specification
+       and other extensions.  The clamping or lack of clamping is left
+       to the core specification and other extensions.
+
+       For assembly program extensions supporting texture fetches
+       (ARB_fragment_program, NV_fragment_program, NV_vertex_program3,
+       etc.) or the OpenGL Shading Language, these signed formats will
+       appear as expected with unclamped signed components as a result
+       of a texture fetch instruction.
+
+       If ARB_color_buffer_float is supported, its clamping controls
+       will apply.
+
+       NV_texture_shader extension, if supported, adds support for
+       fixed-point textures with signed components and relaxed the
+       fixed-function texture environment clamping appropriately.  If the
+       NV_texture_shader extension is supported, its specified behavior
+       for the texture environment applies where intermediate values
+       are clamped to [-1,1] unless stated otherwise as in the case
+       of explicitly clamped to [0,1] for GL_COMBINE.  or clamping the
+       linear interpolation weight to [0,1] for GL_DECAL and GL_BLEND.
+
+       Otherwise, the conventional core texture environment clamps
+       incoming, intermediate, and output color components to [0,1].
+
+       This implies that the conventional texture environment
+       functionality of unextended OpenGL 1.5 or OpenGL 2.0 without
+       using GLSL (and with none of the extensions referred to above)
+       is unable to make proper use of the signed texture formats added
+       by this extension because the conventional texture environment
+       requires texture source colors to be clamped to [0,1].  Texture
+       filtering of these signed formats would be still signed, but
+       negative values generated post-filtering would be clamped to
+       zero by the core texture environment functionality.  The
+       expectation is clearly that this extension would be co-implemented
+       with one of the previously referred to extensions or used with
+       GLSL for the new signed formats to be useful.
+
+
+    6) Should the RGBA_SNORM tokens also be accepted by CopyTexImage
+       functions?
+
+       RESOLVED: YES.
+
+
+    7) What to do with GetTexParameter if ARB_texture_float is supported,
+       in particular what datatype should this return for TEXTURE_RED_TYPE_ARB,
+       TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB, TEXTURE_ALPHA_TYPE_ARB?
+
+       RESOLVED: ARB_texture_float states type is either NONE,
+       UNSIGNED_NORMALIZED_ARB, or FLOAT. This extension adds a new enum,
+       SIGNED_NORMALIZED, which will be returned accordingly. This is the
+       same behaviour as in OpenGL 3.1.
+
+
+New Tokens
+
+
+    Accepted by the <internalformat> parameter of
+    TexImage1D, TexImage2D, TexImage3D, CopyTexImage1D, and CopyTexImage2D:
+
+        RGBA_SNORM                                0x8F93
+        RGBA8_SNORM                               0x8F97
+
+    Returned by the <params> parameter of GetTexLevelParameter:
+
+        SIGNED_NORMALIZED                         0x8F9C
+
+
+Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization):
+
+ -- Section 3.8.1, Texture Image Specification
+
+    Add to Table 3.16 (page 154): Sized internal formats
+
+    Sized             Base             R    G    B    A    L    I    D
+    Internal Format   Internal Format bits bits bits bits bits bits bits
+    ---------------   --------------- ---- ---- ---- ---- ---- ---- ----
+    RGBA8_SNORM       RGBA             8    8    8    8    0    0    0
+
+
+Dependencies on ARB_texture_float extension:
+
+    If ARB_texture_float is supported, GetTexParameter queries with <value>
+    of TEXTURE_RED_TYPE_ARB, TEXTURE_GREEN_TYPE_ARB, TEXTURE_BLUE_TYPE_ARB or
+    TEXTURE_ALPHA_TYPE_ARB return SIGNED_NORMALIZED if
+    the base internal format is RGBA_SNORM.

mesa 3D driver/docs/_extra/specs/MESA_window_pos.spec

@@ -0,0 +1,126 @@
+Name
+
+    MESA_window_pos
+
+Name Strings
+
+    GL_MESA_window_pos
+
+Contact
+
+    Brian Paul, brian.paul 'at' tungstengraphics.com
+
+Status
+
+    Shipping (since Mesa version 1.2.8)
+
+Version
+
+
+Number
+
+    197
+
+Dependencies
+
+    OpenGL 1.0 is required.
+    The extension is written against the OpenGL 1.2 Specification
+
+Overview
+
+    In order to set the current raster position to a specific window
+    coordinate with the RasterPos command, the modelview matrix, projection
+    matrix and viewport must be set very carefully.  Furthermore, if the
+    desired window coordinate is outside of the window's bounds one must
+    rely on a subtle side-effect of the Bitmap command in order to circumvent
+    frustum clipping.
+
+    This extension provides a set of functions to directly set the
+    current raster position, bypassing the modelview matrix, the
+    projection matrix and the viewport to window mapping.  Furthermore,
+    clip testing is not performed.
+
+    This greatly simplifies the process of setting the current raster
+    position to a specific window coordinate prior to calling DrawPixels,
+    CopyPixels or Bitmap.
+
+New Procedures and Functions
+
+    void WindowPos2dMESA(double x, double y)
+    void WindowPos2fMESA(float x, float y)
+    void WindowPos2iMESA(int x, int y)
+    void WindowPos2sMESA(short x, short y)
+    void WindowPos2ivMESA(const int *p)
+    void WindowPos2svMESA(const short *p)
+    void WindowPos2fvMESA(const float *p)
+    void WindowPos2dvMESA(const double *p)
+    void WindowPos3iMESA(int x, int y, int z)
+    void WindowPos3sMESA(short x, short y, short z)
+    void WindowPos3fMESA(float x, float y, float z)
+    void WindowPos3dMESA(double x, double y, double z)
+    void WindowPos3ivMESA(const int *p)
+    void WindowPos3svMESA(const short *p)
+    void WindowPos3fvMESA(const float *p)
+    void WindowPos3dvMESA(const double *p)
+    void WindowPos4iMESA(int x, int y, int z, int w)
+    void WindowPos4sMESA(short x, short y, short z, short w)
+    void WindowPos4fMESA(float x, float y, float z, float w)
+    void WindowPos4dMESA(double x, double y, double z, double )
+    void WindowPos4ivMESA(const int *p)
+    void WindowPos4svMESA(const short *p)
+    void WindowPos4fvMESA(const float *p)
+    void WindowPos4dvMESA(const double *p)
+
+New Tokens
+
+    none
+
+Additions to Chapter 2 of the OpenGL 1.2 Specification (OpenGL Operation)
+
+  - (2.12, p. 41) Insert after third paragraph:
+
+      Alternately, the current raster position may be set by one of the
+      WindowPosMESA commands:
+
+         void WindowPos{234}{sidf}MESA( T coords );
+         void WindowPos{234}{sidf}vMESA( T coords );
+
+      WindosPos4MESA takes four values indicating x, y, z, and w.
+      WindowPos3MESA (or WindowPos2MESA) is analaguos, but sets only
+      x, y, and z with w implicitly set to 1 (or only x and y with z
+      implicitly set to 0 and w implicitly set to 1).
+
+      WindowPosMESA operates like RasterPos except that the current modelview
+      matrix, projection matrix and viewport parameters are ignored and the
+      clip test operation always passes.  The current raster position values
+      are directly set to the parameters passed to WindowPosMESA.  The current
+      color, color index and texture coordinate update the current raster
+      position's associated data.
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None
+
+GLX Protocol
+
+    Not specified at this time.  However, a protocol message very similar
+    to that of RasterPos is expected.
+
+Errors
+
+    INVALID_OPERATION is generated if WindowPosMESA is called between
+    Begin and End.
+
+New State
+
+    None.
+
+New Implementation Dependent State
+
+    None.
+
+Revision History
+
+  * Revision 1.0 - Initial specification
+  * Revision 1.1 - Minor clean-up  (7 Jan 2000, Brian Paul)
+

mesa 3D driver/docs/_extra/specs/MESA_ycbcr_texture.spec

@@ -0,0 +1,204 @@
+Name
+
+    MESA_ycbcr_texture
+
+Name Strings
+
+    GL_MESA_ycbcr_texture
+
+Contact
+
+    Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com)
+    Keith Whitwell, Tungsten Graphics, Inc.  (keith 'at' tungstengraphics.com)
+
+Status
+
+    Shipping (Mesa 4.0.4 and later)
+
+Version
+
+    1.0
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.0 or later is required
+    This extension is written against the OpenGL 1.4 Specification.
+    NV_texture_rectangle effects the definition of this extension.
+
+Overview
+
+    This extension supports texture images stored in the YCbCr format.
+    There is no support for converting YCbCr images to RGB or vice versa
+    during pixel transfer.  The texture's YCbCr colors are converted to
+    RGB during texture sampling, after-which, all the usual per-fragment
+    operations take place.  Only 2D texture images are supported (not
+    glDrawPixels, glReadPixels, etc).
+
+    A YCbCr pixel (texel) is a 16-bit unsigned short with two components.
+    The first component is luminance (Y).  For pixels in even-numbered
+    image columns, the second component is Cb.  For pixels in odd-numbered
+    image columns, the second component is Cr.  If one were to convert the
+    data to RGB one would need to examine two pixels from columns N and N+1
+    (where N is even) to deduce the RGB color.
+
+IP Status
+
+    None
+
+Issues
+
+    None
+
+New Procedures and Functions
+
+    None
+
+New Tokens
+
+    Accepted by the <internalFormat> and <format> parameters of
+    TexImage2D and TexSubImage2D:
+
+        YCBCR_MESA                   0x8757
+
+    Accepted by the <type> parameter of TexImage2D and TexSubImage2D:
+
+        UNSIGNED_SHORT_8_8_MESA      0x85BA /* same as Apple's */
+        UNSIGNED_SHORT_8_8_REV_MESA  0x85BB /* same as Apple's */
+
+Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
+
+    In section 3.6.4, Rasterization of Pixel Rectangles, on page 101,
+    add the following to Table 3.8 (Packed pixel formats):
+    
+    type Parameter                GL Data   Number of        Matching
+     Token Name                    Type     Components     Pixel Formats
+    --------------                -------   ----------     -------------
+    UNSIGNED_SHORT_8_8_MESA       ushort         2         YCBCR_MESA
+    UNSIGNED_SHORT_8_8_REV_MESA   ushort         2         YCBCR_MESA
+
+
+    In section 3.6.4, Rasterization of Pixel Rectangles, on page 102,
+    add the following to Table 3.10 (UNSIGNED_SHORT formats):
+
+    UNSIGNED_SHORT_8_8_MESA:
+
+      15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
+    +-------------------------------+-------------------------------+
+    |              1st              |              2nd              |
+    +-------------------------------+-------------------------------+
+                        
+    UNSIGNED_SHORT_8_8_REV_MESA:
+
+      15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
+    +-------------------------------+-------------------------------+
+    |              2nd              |              1st              |
+    +-------------------------------+-------------------------------+
+
+
+    In section 3.6.4, Rasterization of Pixel Rectangles, on page 104,
+    add the following to Table 3.12 (Packed pixel field assignments):
+
+                       First       Second     Third      Fourth
+    Format             Element     Element    Element    Element
+    ------             -------     -------    -------    -------
+    YCBCR_MESA         luminance   chroma
+
+
+    In section 3.8.1, Texture Image Specification, on page 125, add
+    another item to the list of TexImage2D and TexImage3D equivalence
+    exceptions:
+
+    * The value of internalformat and format may be YCBCR_MESA to
+      indicate that the image data is in YCbCr format.  type must
+      be either UNSIGNED_SHORT_8_8_MESA or UNSIGNED_SHORT_8_8_REV_MESA
+      as seen in tables 3.8 and 3.10.  Table 3.12 describes the mapping
+      between Y and Cb/Cr to the components.
+      If NV_texture_rectangle is supported target may also be
+      TEXTURE_RECTANGLE_NV or PROXY_TEXTURE_RECTANGLE_NV.
+      All pixel transfer operations are bypassed.  The texture is stored as
+      YCbCr, not RGB.  Queries of the texture's red, green and blue component
+      sizes will return zero.  The YCbCr colors are converted to RGB during
+      texture sampling using an implementation dependent conversion.
+
+
+    In section 3.8.1, Texture Image Specification, on page 126, add
+    another item to the list of TexImage1D and TexImage2D equivalence
+    exceptions:
+
+    * The value of internalformat and format can not be YCBCR_MESA.
+
+
+    In section 3.8.2, Alternate Texture Image Specification Commands, on
+    page 129, insert this paragraph after the first full paragraph on the
+    page:
+
+         "If the internal storage format of the image being updated by
+    TexSubImage2D is YCBCR_MESA then format must be YCBCR_MESA.
+    The error INVALID_OPERATION will be generated otherwise."
+
+
+Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
+Operations and the Frame Buffer)
+
+    None
+
+Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
+State Requests)
+
+    None
+
+Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
+
+    None
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None
+
+GLX Protocol
+
+    None
+
+Errors
+
+    INVALID_ENUM is generated by TexImage2D if <internalFormat> is
+    MESA_YCBCR but <format> is not MESA_YCBCR.
+
+    INVALID_ENUM is generated by TexImage2D if <format> is MESA_YCBCR but
+    <internalFormat> is not MESA_YCBCR.
+
+    INVALID_VALUE is generated by TexImage2D if <format> is MESA_YCBCR and
+    <internalFormat> is MESA_YCBCR and <border> is not zero.
+
+    INVALID_OPERATION is generated by TexSubImage2D if the internal image
+    format is YCBCR_MESA and <format> is not YCBCR_MESA.
+
+    INVALID_OPERATION is generated by CopyTexSubImage2D if the internal
+    image is YCBCR_MESA.
+    
+New State
+
+    Edit table 6.16 on page 231: change the type of TEXTURE_INTERNAL_FORMAT
+    from n x Z42 to n x Z43 to indicate that internal format may also be
+    YCBCR_MESA.
+
+Revision History
+
+    20 September 2002 - Initial draft
+    29 April 2003 - minor updates
+     3 September 2003 - further clarify when YCbCr->RGB conversion takes place
+    19 September 2003 - a few more updates prior to submitting to extension
+                        registry.
+     3 April 2004 - fix assorted inaccuracies

mesa 3D driver/docs/_extra/specs/OLD/EGL_MESA_screen_surface.txt

@@ -0,0 +1,564 @@
+Name
+
+    MESA_screen_surface
+
+Name Strings
+
+    EGL_MESA_screen_surface
+
+Contact
+
+    Brian Paul
+
+    To discuss, join the dri-egl@lists.freedesktop.org list.
+
+Status
+
+    Obsolete.
+
+Version
+
+    11 (27 January 2006)
+
+Number
+
+    TBD
+
+Dependencies
+
+    EGL 1.0 or later.
+
+Overview
+
+    EGL 1.1 supports three types of drawing surfaces:
+      * Window surfaces
+      * Pixmap surfaces
+      * Pbuffer surfaces
+    This extension defines a fourth type of drawing surface:
+      * Screen surface
+
+    A screen surface is a surface for which the (front) color buffer can
+    be directly displayed (i.e. scanned out) on a monitor (such as a flat
+    panel or CRT).  In particular the color buffer memory will be allocated
+    at a location in VRAM (and in a suitable format) which can be displayed
+    by the graphics hardware.
+
+    Note that the width and height of the screen surface need not exactly
+    match the monitor's current resolution.  For example, while the monitor
+    may be configured to to show 1024x768 pixels, the associated screen
+    surface may be larger, such as 1200x1000.  The "screen origin" attribute
+    will specify which region of the screen surface which is visible on the
+    monitor.  The screen surface can be scrolled by changing this origin.
+
+    This extension also defines functions for controlling the monitor's
+    display mode (width, height, refresh rate, etc), and specifing which
+    screen surface is to be displayed on a monitor.
+
+    The new EGLModeMESA type and related functions are very similar to the
+    EGLConfig type and related functions.  The user may get a list of
+    supported modes for a screen and specify the mode to be used when
+    displaying a screen surface.
+
+
+Issues
+
+    1. Should EGL_INTERLACE be a supported mode attribute?
+
+       Arguments against:
+
+           No, this should be provided by another extension which would
+           also provide the mechanisms needed to play back interlaced video
+           material correctly on hardware that supports it.
+           This extension should prefer non-interlaced modes. [M. Danzer]
+
+       Arguments for:
+
+           An interlaced display can be of use without considering video
+           material.  Being able to query whether a screen is operating in
+           interlaced mode can be used by applications to control their
+           drawing.  For example: avoid drawing 1-pixel-wide horizontal lines
+           if screen is interlaced. [B. Paul]
+
+       Resolution: Defer for future extension?
+
+
+    2. Should EGL_REFRESH_RATE be a supported mode attribute?
+
+       Arguments for:
+
+           Yes, it's been shown that applications and/or users need to select
+           modes by this.  [M. Danzer]
+
+           Many examples have been given in which it's desirable to let the
+           user choose from a variety of refresh rates without having to
+           restart/reconfigure.  [B. Paul]
+
+       Arguments against:
+
+           TBD.
+
+       Resolution: Yes.
+
+
+    3. Exactly how should the list of modes returned by eglChooseConfigMESA
+       be sorted?
+
+       Current method is described in the text below.  Subject to change.
+
+       Alternately, leave the sorting order undefined so that each
+       implementation can return the modes in order of "most desirable"
+       to "least desirable" which may depend on the display technology
+       (CRT vs LCD, etc) or other factors.
+
+
+    4. How should screen blanking be supported?  Note that a screen can be
+       disabled or turned off by calling eglShowSurface(dpy, scrn,
+       EGL_NO_SURFACE, EGL_NO_MODE_MESA).  But what about power-save mode?
+
+       I would defer this to other extensions that depend on this one.
+       I can imagine people wanting different semantics not just in
+       relation to the power management API being exposed (DPMS or whatever)
+       but also relating to what events can trigger EGL_CONTEXT_LOST.  Also
+       I'm not sure whether power management commands are properly operations
+       on the Display or on a screen surface. [A. Jackson]
+
+
+    5. Should the EGL_PHYSICAL_SIZE_EGL query be kept?  The size information
+       isn't always reliable (consider video projectors) but can still be
+       used to determine the pixel aspect ratio.
+
+       Resolution: Omit.  The EGL 1.2 specification includes queries for
+       the display resolution and pixel aspect ratio.
+
+
+    6. Should detailed mode timing information be exposed by this API?
+
+       Probably not.  Instead, offer that information in a layered extension.
+
+
+    7. How should the notion of a screen's "native" mode be expressed?
+       For example, LCD panels have a native resolution and refresh rate
+       that looks best but other sub-optimal resolutions may be supported.
+
+       The mode attribute EGL_OPTIMAL_MESA will be set for modes which
+       best match the screen.  [M. Danzer]
+
+
+    8. Should eglQueryModeStringMESA() be included?  This function returns
+       a human-readable string which corresponds to an EGLMode.
+
+       Arguments for:
+
+           A mode name such as "HDTV-720P" might mean more to users than
+           "1280x720@60Hz" if the later were generated via code.
+
+       Arguments against:
+
+           There's no standard syntax for the strings.  May cause more
+           trouble than it's worth.
+
+       Postpone for future extension. [A. Jackson]
+
+       Latest discussion leaning toward omitting this function.
+
+
+    9. Should we use "Get" or "Query" for functions which return state?
+       The EGL 1.x specification doesn't seem to be totally consistent
+       in this regard, but "Query" is used more often.
+
+       Use "Get" for mode-related queries (as for EGLConfigs) but "Query"
+       for everything else.
+
+
+    10. What should be the default size for screen surfaces?
+
+        For Pbuffer surfaces the default width and height are zero.
+        We'll do the same for screen surfaces.  Since there's no function
+        to resize surfaces it's useless to have a 0x0 screen, but this isn't
+        a situation that'll normally be encountered.
+
+
+    11. Should there be a function for resizing a screen surface?
+
+        Suppose one wants to change the screen's size in the EGL application.
+        Also suppose there's a hardware restriction such that only one screen
+        surface can exist at a time (either for lack of memory or because of
+        memory layout restrictions).
+
+        The basic idea is that the currently displayed screen surface must
+        be deallocated before a new one can be created.  Perhaps a resize
+        function would work better?
+
+
+    12. How should sub-pixel LCD color information be made available?
+        What about the display's gamma value?
+
+        Perhaps expose as additional read-only mode attributes.
+
+        Perhaps postpone for a layered extension.
+
+
+    13. What happens if the user attempts to delete a screen surface that
+        is currently being shown?
+
+        Spec currently says that's illegal and that an error (TBD) will be
+        generated.
+
+
+    14. What if the physical screen size can't be determined?  Should
+        a query of EGL_PHYSICAL_SIZE_MESA return [0,0]?
+
+        Obsolete: EGL_PHYSICAL_SIZE_MESA not used.
+
+
+    15. Suppose the device's number of RAMDACs is different from the
+        number of output ports.  For example, a graphics card with
+        two RAMDACs but three ports (VGA, DVI, TV).
+
+        Address this in a follow-on extension. [Matthias Hopf]
+
+
+    16. How should we deal with on-the-fly device changes?  For example,
+        the monitor being unplugged and replaced by another with different
+        characteristics?
+
+        A HAL event could be received via DBUS in the application [J. Smirl,
+        A. Jackson].
+
+        Should there be an EGL mechanism for detecting this?  Maybe an
+        EGL_SCREEN_LOST error (similar to EGL_CONTEXT_LOST) can be recorded
+        when there's a screen change.  At least then the application can
+        poll to detect this situation.
+
+        Maybe leave that to a future extension.
+
+        See also the EGL_SCREEN_COUNT_MESA query.
+
+
+    17. What if pixel-accurate panning is not supported (see
+        eglScreenPositionMESA)? [M. Danzer]
+
+        Is this a common problem?  Can we ignore it for now?
+
+
+    18. Should eglShowSurfaceMESA be renamed to eglShowScreenSurfaceMESA?
+
+        Probably.
+
+
+
+New Procedures and Functions
+
+    EGLBoolean eglChooseModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                 const EGLint *attrib_list,
+                                 EGLModeMESA *modes, EGLint modes_size,
+                                 EGLint *num_modes)
+
+    EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                               EGLModeMESA *modes, EGLint modes_size,
+                               EGLint *num_modes)
+
+    EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
+                                    EGLint attrib, EGLint *value)
+
+
+    EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
+                                 EGLint screens_size, EGLint *num_screens)
+
+    EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
+                                          const EGLint *attrib_list)
+
+    EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                  EGLSurface surface, EGLModeMESA mode)
+
+    EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                     EGLint x, EGLint y)
+
+
+    EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                  EGLint attrib, EGLint *value);
+
+    EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                         EGLSurface *surface)
+
+    EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                      EGLModeMESA *mode)
+
+    const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLMode mode);
+
+
+New Types
+
+    EGLModeMESA
+    EGLScreenMESA
+
+New Tokens
+
+    New error codes:
+
+    EGL_BAD_SCREEN_MESA        
+    EGL_BAD_MODE_MESA          
+
+    Screen-related tokens:
+
+    EGL_SCREEN_COUNT_MESA      
+    EGL_SCREEN_POSITION_MESA   
+    EGL_SCREEN_BIT_MESA        
+    EGL_SCREEN_POSITION_GRANULARITY_MESA
+
+    Mode-related tokens:
+
+    EGL_MODE_ID_MESA           
+    EGL_REFRESH_RATE_MESA      
+    EGL_INTERLACED_MESA
+    EGL_OPTIMAL_MESA
+    EGL_NO_MODE_MESA
+
+
+Additions to Chapter X of the EGL 1.1 Specification
+
+    [XXX this all has to be rewritten to fit into the EGL specification
+    and match the conventions of an EGL extension.  For now, just list
+    all the functions with brief descriptions.]
+
+
+    EGLBoolean eglChooseModeMESA(EGLDisplay dpy, const EGLScreenMESA screen,
+                                 EGLint *attrib_list, EGLModeMESA *modes,
+                                 EGLint modes_size, EGLint *num_modes)
+
+    Like eglChooseConfig, returns a list of EGLModes which match the given
+    attribute list.  This does not set the screen's current display mode.
+    The attribute list is a list of token/value pairs terminated with
+    EGL_NONE.  Supported attributes include:
+
+        Name                   Description
+        ---------------------  ---------------------------------------------
+        EGL_WIDTH              Mode width (resolution)
+        EGL_HEIGHT             Mode height (resolution)
+        EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
+        EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
+        EGL_OPTIMAL_MESA       Set if the most is especially optimal for the
+                               screen (ex. for particular LCD resolutions)
+
+    Any other token will generate the error EGL_BAD_ATTRIBUTE.
+
+    The list of modes returned by eglChooseModeMESA will be sorted
+    according to the following criteria.  See the discussion of table 3.3
+    in the EGL specification for more information.
+
+                                            Selection   Sort   Sort
+        Attribute            Default        Criteria    Order  Priority
+        -------------------- -------------- ----------- ------ --------
+        EGL_OPTIMAL_MESA     EGL_DONT_CARE  Exact       1,0      1
+        EGL_INTERLACED_MESA  EGL_DONT_CARE  Exact       0,1      2
+        EGL_REFRESH_RATE     EGL_DONT_CARE  AtLeast     Larger   3
+        EGL_WIDTH            EGL_DONT_CARE  AtLeast     Larger   4
+        EGL_HEIGHT           EGL_DONT_CARE  AtLeast     Larger   5
+        EGL_MODE_ID_MESA     EGL_DONT_CARE  Exact       Smaller  6
+
+
+    EGLBoolean eglGetModesMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                               EGLModeMESA *modes, EGLint modes_size,
+                               EGLint *num_modes)
+
+    Like eglGetConfigs, returns a list of all modes supported by the
+    given screen.  The returned modes will be sorted in the same manner
+    as for eglChooseModeMESA().
+
+
+
+    EGLBoolean eglGetModeAttribMESA(EGLDisplay dpy, EGLModeMESA mode,
+                                    EGLint attrib, EGLint *value)
+
+    Used to query mode attributes.  The following attributes are supported:
+
+        Name                   Return value description
+        ---------------------  ----------------------------------------------
+        EGL_OPTIMAL_MESA       1 indicates an optimal mode, 0 otherwise
+        EGL_INTERLACED_MESA    1 indicates an interlaced mode, 0 otherwise
+        EGL_REFRESH_RATE_MESA  The mode's refresh rate, multiplied by 1000
+        EGL_WIDTH              Mode width (resolution)
+        EGL_HEIGHT             Mode height (resolution)
+        EGL_MODE_ID_MESA       A unique small integer identifier for the mode
+
+    Any other token will generate the error EGL_BAD_ATTRIBUTE.
+
+
+
+    EGLBoolean eglGetScreensMESA(EGLDisplay dpy, EGLScreenMESA *screens,
+                                 EGLint screens_size, EGLint *num_screens)
+
+    This function returns an array of all available screen handles.
+    <screens_size> is the maximum number of screens to return in the
+    <screens> array.  <num_screens> will return the number of screen handles
+    placed in the array, even if <screens> is NULL.
+
+    The number of screens and the availability of each may change over
+    time (hot-plugging).  Screen handles will not be reused.  When a
+    screen handle becomes invalid, function calls which reference an
+    invalid handle will generate EGL_BAD_SCREEN_MESA.
+
+    The first screen handle returned will be considered to be the primary
+    one.
+
+
+
+    EGLSurface eglCreateScreenSurfaceMESA(EGLDisplay dpy, EGLConfig config,
+                                          const EGLint *attrib_list)
+
+    Create a surface that can be displayed on a screen.  <attrib_list> is
+    an array of token/value pairs terminated with EGL_NONE.  Valid tokens
+    include:
+
+        Name              Description
+        ----------------  --------------------------------
+        EGL_WIDTH         desired surface width in pixels
+        EGL_HEIGHT        desired surface height in pixels
+
+    Any other token will generate the error EGL_BAD_ATTRIBUTE.
+    The default width and height are zero.
+
+    
+
+    EGLBoolean eglShowSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                  EGLSurface surface, EGLModeMESA mode)
+
+    This function causes a screen to show the given surface (or more
+    precisely, the surface's front color buffer) with the given mode.
+
+    If the surface is in any way incompatible with the mode, the error
+    EGL_BAD_MATCH will be generated, EGL_FALSE will be returned, and the
+    previous screen state will remain in effect.  This might occur when
+    the bandwidth of the video-out subsystem is exceeded, or if the mode
+    specifies a width or height that's greater than the width or height
+    of the surface.
+
+    To disable a screen, the values EGL_NO_SURFACE and EGL_NO_MODE_MESA
+    be passed as the <surface> and <mode> parameters.
+
+    The values of EGL_SCREEN_POSITION_MESA are clamped to the new valid
+    range computed from the screen size and surface size.  If the new
+    surface is EGL_NO_SURFACE, EGL_SCREEN_POSITION_MESA is set to [0, 0].
+
+
+    Attempting to delete a screen surface which is currently being
+    displayed will result in the error EGL_BAD_ACCESS being generated.
+
+
+
+    EGLBoolean eglScreenPositionMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                     EGLint x, EGLint y)
+
+    Specifies the origin of the screen's view into the surface, if the
+    surface is larger than the screen.  Valid values for x and y are
+    [0, surfaceWidth - screenWidth] and [0, surfaceHeight - screenHeight],
+    respectively.
+
+    The x and y values are also constrained to be integer multiples of the
+    EGL_SCREEN_POSITION_GRANULARITY_MESA values.
+
+
+
+
+    EGLBoolean eglQueryScreenMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                  EGLint attrib, EGLint *value);
+
+    Used to query screen attributes.  <attrib> may be one of the following:
+
+        Name                      Return value description
+        ------------------------  ---------------------------------------------
+        EGL_SCREEN_POSITION_MESA  x, y position of the screen's origin with
+                                  respect to the surface.  If no surface is
+                                  attached to the screen, [0, 0] is returned.
+        EGL_SCREEN_POSITION_GRANULARITY_MESA
+                                  Returns the granularity, in pixels, for
+                                  which the screen position is constrained.
+
+    Any other token will generate the error EGL_BAD_ATTRIBUTE.
+
+
+
+
+    EGLBoolean eglQueryScreenSurfaceMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                         EGLSurface *surface)
+
+    Returns the surface currently displayed on the given screen.  <surface>
+    may be EGL_NO_SURFACE if the screen isn't currently showing any surface.
+
+
+
+
+    EGLBoolean eglQueryScreenModeMESA(EGLDisplay dpy, EGLScreenMESA screen,
+                                      EGLModeMESA *mode)
+
+    Returns the given screen's current display mode.  The mode may be
+    EGL_NO_MODE_MESA if the screen is currently disabled.
+
+
+
+    const char *eglQueryModeStringMESA(EGLDisplay dpy, EGLModeMESA mode);
+
+    Returns a human-readable string for the given mode.  The string is a
+    zero-terminated C string which the user should not attempt to free.
+    There is no standard syntax for mode strings.  Applications should
+    not directly rely on mode strings.
+
+
+
+Version History
+
+    1. 15 March 2005 - BrianP
+        Initial version
+
+    2. 16 March 2005 - BrianP
+        Removed EGL_DEPTH_MESA
+        Added EGL_PHYSICAL_WIDTH_MESA, EGL_PHYSICAL_HEIGHT_MESA queries
+        Added EGL_OPTIMAL_MESA for width/height/refresh rate selection
+        Added possible eglQueryModeStringMESA() function
+        More details of the new functions explained.
+
+    3. 18 March 2005 - BrianP
+        Added screen_number to eglChooseModeMESA().
+        Fix off by one mistake in value range for ORIGIN attributes
+        Added Issues section
+
+    4. 21 March 2005 - BrianP
+        Removed eglScreenAttribsMESA().
+        Added eglScreenPositionMESA() to set screen origin.
+        Replaced EGL_SCREEN_X/Y_OFFSET_MESA with EGL_SCREEN_POSITION_MESA.
+        Replaced EGL_PHYSICAL_WIDTH/HEIGHT_MESA with EGL_PHYSICAL_SIZE_MESA.
+        Use EGL_OPTIMAL_MESA as a new mode attribute. (Michel Danzer)
+        Added a few more issues.
+
+    5. 6 April 2005 - BrianP
+        More language for eglGetModeStringMESA().
+        Added issues 10, 11, 12, 13, 14.
+        Updated issue 3 discussion about mode sorting.
+
+    6. 22 April 2005 - BrianP
+        Fixed "LDC" typo.
+        Added issues 15, 16.
+        Changed dependency on EGL 1.1 to EGL 1.0
+        s/EGL_NUM_SCREENS_MESA/EGL_SCREEN_COUNT_MESA/
+        Added eglQueryDisplayMESA() to New Functions section.
+        Clarified language for the EGL_SCREEN_COUNT_MESA query.
+
+    7. 29 April 2005 - BrianP
+        Added EGLScreenMESA type and eglGetScreensMESA() function. [J. Smirl].
+        Replaced EGLint screen_number parameters with EGLScreenMESA screen.
+        Added issue 17 (pixel-accurate panning)
+
+    8. 2 May 2005 - BrianP
+        Removed eglQueryDisplayMESA.
+        Fixed a few more EGLint -> EGLScreenMESA changes.
+
+    9. 20 May 2005 - BrianP
+        Fixed a few typos.
+        Updated some open issues text.
+
+    10. 10 August 2005 - BrianP
+        Added EGL_SCREEN_POSITION_GRANULARITY_MESA.
+
+    11. 27 January 2006 - BrianP
+        EGL_PHYSICAL_SIZE_MESA removed since EGL 1.2 has a similar feature.
+

mesa 3D driver/docs/_extra/specs/OLD/MESA_agp_offset.spec

@@ -0,0 +1,94 @@
+Name
+
+    MESA_agp_offset
+
+Name Strings
+
+    GLX_MESA_agp_offset
+
+Contact
+
+    Brian Paul, Tungsten Graphics, Inc. (brian.paul 'at' tungstengraphics.com)
+    Keith Whitwell, Tungsten Graphics, Inc.  (keith 'at' tungstengraphics.com)
+
+Status
+
+    Obsolete. Effectively superseded by ARB_vertex_buffer_object.
+
+Version
+
+    1.0
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.0 or later is required
+    GLX_NV_vertex_array_range is required.
+    This extensions is written against the OpenGL 1.4 Specification.
+
+Overview
+
+    This extensions provides a way to convert pointers in an AGP memory
+    region into byte offsets into the AGP aperture.
+    Note, this extension depends on GLX_NV_vertex_array_range, for which
+    no real specification exists.  See GL_NV_vertex_array_range for more
+    information.
+
+IP Status
+
+    None
+
+Issues
+
+    None
+
+New Procedures and Functions
+
+    unsigned int glXGetAGPOffsetMESA( const void *pointer )
+
+New Tokens
+
+    None
+
+Additions to the OpenGL 1.4 Specification
+
+    None
+
+Additions to Chapter 3 the GLX 1.4 Specification (Functions and Errors)
+
+    Add a new section, 3.6 as follows:
+
+    3.6 AGP Memory Access
+
+    On "PC" computers, AGP memory can be allocated with glXAllocateMemoryNV
+    and freed with glXFreeMemoryNV.  Sometimes it's useful to know where a
+    block of AGP memory is located with respect to the start of the AGP
+    aperture.  The function
+
+        GLuint glXGetAGPOffsetMESA( const GLvoid *pointer )
+
+    Returns the offset of the given memory block from the start of AGP
+    memory in basic machine units (i.e. bytes).  If pointer is invalid
+    the value ~0 will be returned.
+
+GLX Protocol
+
+    None.  This is a client side-only extension.
+
+Errors
+
+    glXGetAGPOffsetMESA will return ~0 if the pointer does not point to
+    an AGP memory region.
+
+New State
+
+    None
+
+Revision History
+
+    20 September 2002 - Initial draft
+    2 October 2002 - finished GLX chapter 3 additions
+    27 July 2004 - use unsigned int instead of GLuint, void instead of GLvoid

mesa 3D driver/docs/_extra/specs/OLD/MESA_packed_depth_stencil.spec

@@ -0,0 +1,230 @@
+Name
+
+    MESA_packed_depth_stencil
+
+Name Strings
+
+    GL_MESA_packed_depth_stencil
+
+Contact
+
+    Keith Whitwell, VA Linux Systems Inc. (keithw 'at' valinux.com)
+    Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
+
+Status
+
+    Obsolete.
+
+Version
+
+
+Number
+
+    ???
+
+Dependencies
+
+    EXT_abgr affects the definition of this extension
+    SGIS_texture4D affects the definition of this extension
+    EXT_cmyka affects the definition of this extension
+    ARB_packed_pixels affects the definition of this extension
+
+Overview
+	
+    Provides a mechanism for DrawPixels and ReadPixels to efficiently
+    transfer depth and stencil image data.  Specifically, we defined new
+    packed pixel formats and types which pack both stencil and depth
+    into one value.
+
+Issues:
+
+    1. Is this the right way to distinguish between 24/8 and 8/24
+       pixel formats?  Should we instead provide both:
+	
+       GL_DEPTH_STENCIL_MESA
+       GL_STENCIL_DEPTH_MESA
+
+       And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ?
+
+    2. If not, is it correct to use _REV to indicate that stencil
+       preceeds depth in the 1_15 and 8_24 formats?
+
+    3. Do we really want the GL_UNSIGNED_SHORT formats?  
+
+	
+New Procedures and Functions
+
+    None.
+
+New Tokens
+    
+    Accepted by the <format> parameter of ReadPixels and DrawPixels:
+
+	GL_DEPTH_STENCIL_MESA		0x8750
+
+    Accepted by the <type> parameter of ReadPixels and DrawPixels:
+
+	GL_UNSIGNED_INT_24_8_MESA	0x8751
+	GL_UNSIGNED_INT_8_24_REV_MESA	0x8752
+	GL_UNSIGNED_SHORT_15_1_MESA	0x8753
+	GL_UNSIGNED_SHORT_1_15_REV_MESA	0x8754
+
+Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the 1.1 Specification (Rasterization)
+
+    One entry is added to table 3.5 (DrawPixels and ReadPixels formats).
+    The new table is:
+
+			Target
+	Format Name	Buffer	Element Meaning and Order
+	-----------	------	-------------------------
+	COLOR_INDEX	Color	Color index
+	STENCIL_INDEX	Stencil Stencil index
+	DEPTH_COMPONENT Depth	Depth component
+	RED		Color	R component
+	GREEN		Color	G component
+	BLUE		Color	B component
+	ALPHA		Color	A component
+	RGB		Color	R, G, B components
+	RGBA		Color	R, G, B, A components
+	BGRA	        Color   B, G, R, A components
+	ABGR_EXT	Color	A, B, G, R components
+	CMYK_EXT	Color	Cyan, Magenta, Yellow, Black components
+	CMYKA_EXT	Color	Cyan, Magenta, Yellow, Black, A components
+	LUMINANCE	Color	Luminance component
+	LUMINANCE_ALPHA Color	Luminance, A components
+	DEPTH_STENCIL   Depth,  Depth component, stencil index.
+			Stencil
+
+	Table 3.5: DrawPixels and ReadPixels formats.  The third column
+	gives a description of and the number and order of elements in a
+	group.
+
+    Add to the description of packed pixel formats:
+
+	<type> Parameter		Data	of	  Matching
+	Token Name			Type	Elements  Pixel Formats
+	----------------		----	--------  -------------
+
+	UNSIGNED_BYTE_3_3_2	      ubyte   3	      RGB
+	UNSIGNED_BYTE_2_3_3_REV       ubyte   3	      RGB
+	UNSIGNED_SHORT_5_6_5	      ushort  3	      RGB
+	UNSIGNED_SHORT_5_6_5_REV      ushort  3	      RGB
+	UNSIGNED_SHORT_4_4_4_4	      ushort  4	      RGBA,BGRA,ABGR_EXT,CMYK_EXT
+	UNSIGNED_SHORT_4_4_4_4_REV    ushort  4	      RGBA,BGRA
+	UNSIGNED_SHORT_5_5_5_1	      ushort  4	      RGBA,BGRA,ABGR_EXT,CMYK_EXT
+	UNSIGNED_SHORT_1_5_5_5_REV    ushort  4	      RGBA,BGRA
+	UNSIGNED_INT_8_8_8_8	      uint    4	      RGBA,BGRA,ABGR_EXT,CMYK_EXT
+	UNSIGNED_INT_8_8_8_8_REV      uint    4	      RGBA,BGRA
+	UNSIGNED_INT_10_10_10_2       uint    4	      RGBA,BGRA,ABGR_EXT,CMYK_EXT
+	UNSIGNED_INT_2_10_10_10_REV   uint    4	      RGBA,BGRA
+	UNSIGNED_SHORT_15_1_MESA      ushort  2       DEPTH_STENCIL_MESA
+	UNSIGNED_SHORT_1_15_REV_MESA  ushort  2       DEPTH_STENCIL_MESA
+	UNSIGNED_SHORT_24_8_MESA      ushort  2       DEPTH_STENCIL_MESA
+	UNSIGNED_SHORT_8_24_REV_MESA  ushort  2       DEPTH_STENCIL_MESA
+
+	UNSIGNED_INT_8_24:
+
+	     31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10	9  8  7  6  5  4  3  2	1  0
+	    +-----------------------+-----------------------------------------------------------------------+
+	    |			    |			     			    			    |
+	    +-----------------------+-----------------------------------------------------------------------+
+
+		    first					second		    
+		    element					element		    
+
+
+	UNSIGNED_INT_24_8:
+
+	     31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10	9  8  7  6  5  4  3  2	1  0
+	    +----------------------------------------------------------------------+------------------------+
+	    |			    			     			   | 			    |
+	    +----------------------------------------------------------------------+------------------------+
+
+		    first								  second		    
+		    element								  element		    
+
+	UNSIGNED_SHORT_15_1:
+
+	      15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
+	    +-----------------------------------------------------------+---+
+	    |					    			|   |
+	    +-----------------------------------------------------------+---+
+
+	    		first						second	
+			element						element	
+
+
+	UNSIGNED_SHORT_1_15_REV:
+
+	      15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
+	    +---+-----------------------------------------------------------+
+	    |	|		     					    |
+	    +---+-----------------------------------------------------------+
+
+	    second		    first
+	    element		    element
+
+    The assignment of elements to fields in the packed pixel is as
+    described in the table below:
+
+			   First       Second	Third	    Fourth
+	Format		   Element     Element	Element     Element
+	------		   -------     -------	-------     -------
+	RGB		   red	       green	blue
+	RGBA		   red	       green	blue	    alpha
+	BGRA		   blue	       green	red	    alpha
+	ABGR_EXT	   alpha       blue	green	    red
+	CMYK_EXT	   cyan	       magenta	yellow	    black
+	DEPTH_STENCIL_MESA depth       stencil
+
+Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
+and the Frame Buffer)
+
+    The new format is added to the discussion of Obtaining Pixels from the
+    Framebuffer.  It should read " If the <format> is one of RED, GREEN,
+    BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and
+    the GL is in color index mode, then the color index is obtained."
+
+    The new format is added to the discussion of Index Lookup.  It should
+    read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA,
+    ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to
+    reference 4 tables of color components: PIXEL_MAP_I_TO_R,
+    PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A."
+
+
+Additions to Chapter 5 of the 1.1 Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
+
+    None
+
+Additions to the GLX Specification
+
+    None
+
+GLX Protocol
+
+    TBD
+
+Errors
+
+    None
+
+New State
+
+    None
+
+Revision History
+
+    Version 1.0 - 23 Sep 2000
+        Keith's original version.
+
+    Version 1.1 - 3 Nov 2000
+        Brian's edits, assigned values to new enums.
+

mesa 3D driver/docs/_extra/specs/OLD/MESA_program_debug.spec

@@ -0,0 +1,356 @@
+Name
+
+    MESA_program_debug
+
+Name Strings
+
+    GL_MESA_program_debug
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Obsolete.
+
+Version
+
+    Last Modified Date: July 20, 2003
+    Author Revision: 1.0
+
+Number
+
+    TBD
+
+Dependencies
+
+    OpenGL 1.4 is required
+    The extension is written against the OpenGL 1.4 specification.
+    ARB_vertex_program or ARB_fragment_program or NV_vertex_program
+    or NV_fragment_program is required.
+
+Overview
+
+    The extension provides facilities for implementing debuggers for
+    vertex and fragment programs.
+
+    The concept is that vertex and fragment program debuggers will be
+    implemented outside of the GL as a utility package.  This extension
+    only provides the minimal hooks required to implement a debugger.
+
+    There are facilities to do the following:
+    1. Have the GL call a user-specified function prior to executing
+       each vertex or fragment instruction.
+    2. Query the current program string's execution position.
+    3. Query the current values of intermediate program values.
+
+    The main feature is the ProgramCallbackMESA function.  It allows the
+    user to register a callback function with the GL.  The callback will
+    be called prior to executing each vertex or fragment program instruction.
+
+    From within the callback, the user may issue Get* commands to
+    query current GL state.  The GetProgramRegisterfvMESA function allows
+    current program values to be queried (such as temporaries, input
+    attributes, and result registers).
+
+    There are flags for enabling/disabling the program callbacks.
+
+    The current execution position (as an offset from the start of the
+    program string) can be queried with
+    GetIntegerv(GL_FRAGMENT_PROGRAM_POSITION_MESA, &pos) or
+    GetIntegerv(GL_VERTEX_PROGRAM_POSITION_MESA, &pos).
+
+
+IP Status
+
+    None
+
+Issues
+
+    1. Is this the right model for a debugger?
+
+       It seems prudent to minimize the scope of this extension and leave
+       it up to the developer (or developer community) to write debuggers
+       that layer on top of this extension.
+
+       If the debugger were fully implemented within the GL it's not
+       clear how terminal and GUI-based interfaces would work, for
+       example.
+
+    2. There aren't any other extensions that register callbacks with
+       the GL.  Isn't there another solution?
+
+       If we want to be able to single-step through vertex/fragment
+       programs I don't see another way to do it.
+
+    3. How do we prevent the user from doing something crazy in the
+       callback function, like trying to call glBegin (leading to
+       recursion)?
+
+       The rule is that the callback function can only issue glGet*()
+       functions and no other GL commands.  It could be difficult to
+       enforce this, however.  Therefore, calling any non-get GL
+       command from within the callback will result in undefined
+       results.    
+
+    4. Is this extension amenable to hardware implementation?
+
+       Hopefully, but if not, the GL implementation will have to fall
+       back to a software path when debugging.  This may be acceptable
+       for debugging.
+
+    5. What's the <data> parameter to ProgramCallbackMESA for?
+
+       It's a common programming practice to associate a user-supplied
+       value with callback functions.
+
+    6. Debuggers often allow one to modify intermediate program values,
+       then continue.  Does this extension support that?
+
+       No.
+
+
+New Procedures and Functions (and datatypes)
+
+    typedef void (*programcallbackMESA)(enum target, void *data)
+
+    void ProgramCallbackMESA(enum target, programcallbackMESA callback,
+                             void *data)
+
+    void GetProgramRegisterfvMESA(enum target, sizei len,
+                                  const ubyte *registerName, float *v)
+
+New Tokens
+
+    Accepted by the <cap> parameter of Enable, Disable, IsEnabled,
+    GetBooleanv, GetDoublev, GetFloatv and GetIntegerv:
+
+        FRAGMENT_PROGRAM_CALLBACK_MESA      0x8bb1
+        VERTEX_PROGRAM_CALLBACK_MESA        0x8bb4
+
+    Accepted by the <pname> parameter GetBooleanv, GetDoublev,
+    GetFloatv and GetIntegerv:
+
+        FRAGMENT_PROGRAM_POSITION_MESA      0x8bb0
+        VERTEX_PROGRAM_POSITION_MESA        0x8bb5
+
+    Accepted by the <pname> parameter of GetPointerv:
+
+        FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA 0x8bb2
+        FRAGMENT_PROGRAM_CALLBACK_DATA_MESA 0x8bb3
+        VERTEX_PROGRAM_CALLBACK_FUNC_MESA   0x8bb6
+        VERTEX_PROGRAM_CALLBACK_DATA_MESA   0x8bb7
+
+Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation)
+
+    None.
+
+Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization)
+
+    None.
+
+Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment
+Operations and the Frame Buffer)
+
+    None.
+
+Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions)
+
+    In section 5.4 "Display Lists", page 202, add the following command
+    to the list of those that are not compiled into display lists:
+
+        ProgramCallbackMESA.
+
+
+    Add a new section 5.7 "Callback Functions"
+
+    The function
+
+        void ProgramCallbackMESA(enum target, programcallbackMESA callback,
+                                 void *data)
+
+    registers a user-defined callback function with the GL.  <target>
+    may be FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.  The enabled
+    callback functions registered with these targets will be called
+    prior to executing each instruction in the current fragment or
+    vertex program, respectively.  The callbacks are enabled and
+    disabled by calling Enable or Disable with <cap>
+    FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB.
+
+    The callback function's signature must match the typedef
+
+        typedef void (*programcallbackMESA)(enum target, void *data)
+
+    When the callback function is called, <target> will either be
+    FRAGMENT_PROGRAM_ARB or VERTEX_PROGRAM_ARB to indicate which
+    program is currently executing and <data> will be the value
+    specified when ProgramCallbackMESA was called.
+
+    From within the callback function, only the following GL commands
+    may be called:
+
+        GetBooleanv
+        GetDoublev
+        GetFloatv
+        GetIntegerv
+        GetProgramLocalParameter
+        GetProgramEnvParameter
+        GetProgramRegisterfvMESA
+        GetProgramivARB
+        GetProgramStringARB
+        GetError
+
+    Calling any other command from within the callback results in
+    undefined behaviour.
+
+
+Additions to Chapter 6 of the OpenGL 1.4 Specification (State and
+State Requests)
+
+    Add a new section 6.1.3 "Program Value Queries":
+
+    The command
+
+        void GetProgramRegisterfvMESA(enum target, sizei len,
+                                      const ubyte *registerName,
+                                      float *v)
+        
+    Is used to query the value of program variables and registers
+    during program execution.  GetProgramRegisterfvMESA may only be
+    called from within a callback function registered with
+    ProgramCallbackMESA.
+
+    <registerName> and <len> specify the name a variable, input
+    attribute, temporary, or result register in the program string.
+    The current value of the named variable is returned as four
+    values in <v>.  If <name> doesn't exist in the program string,
+    the error INVALID_OPERATION is generated.
+
+Additions to Appendix A of the OpenGL 1.4 Specification (Invariance)
+
+    None.
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None.
+
+GLX Protocol
+
+    XXX TBD
+
+Dependencies on NV_vertex_program and NV_fragment_program
+
+    If NV_vertex_program and/or NV_fragment_program are supported,
+    vertex and/or fragment programs defined by those extensions may
+    be debugged as well.  Register queries will use the syntax used
+    by those extensions (i.e. "v[X]" to query vertex attributes,
+    "o[X]" for vertex outputs, etc.)
+
+Errors
+
+    INVALID_OPERATION is generated if ProgramCallbackMESA is called
+    between Begin and End.
+
+    INVALID_ENUM is generated by ProgramCallbackMESA if <target> is not
+    a supported vertex or fragment program type.
+
+    Note: INVALID_OPERAION IS NOT generated by GetProgramRegisterfvMESA,
+    GetBooleanv, GetDoublev, GetFloatv, or GetIntegerv if called between
+    Begin and End when a vertex or fragment program is currently executing.
+
+    INVALID_ENUM is generated by ProgramCallbackMESA,
+    GetProgramRegisterfvMESA if <target> is not a program target supported
+    by ARB_vertex_program, ARB_fragment_program (or NV_vertex_program or
+    NV_fragment_program).
+
+    INVALID_VALUE is generated by GetProgramRegisterfvMESA if <registerName>
+    does not name a known program register or variable.
+
+    INVALID_OPERATION is generated by GetProgramRegisterfvMESA when a
+    register query is attempted for a program target that's not currently
+    being executed.
+
+
+New State
+
+    XXX finish
+
+(table 6.N, p. ###)
+                                                            Initial
+    Get Value                            Type Get Command   Value    Description  Sec.  Attribute
+    ---------                            ---- -----------   -----    -----------  ----  ---------
+    FRAGMENT_PROGRAM_CALLBACK_MESA        B   IsEnabled     FALSE    XXX          XXX   enable
+    VERTEX_PROGRAM_CALLBACK_MESA          B   IsEnabled     FALSE    XXX          XXX   enable
+    FRAGMENT_PROGRAM_POSITION_MESA        Z+  GetIntegerv   -1       XXX          XXX   -
+    VERTEX_PROGRAM_POSITION_MESA          Z+  GetIntegerv   -1       XXX          XXX   -
+    FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA   P   GetPointerv   NULL     XXX          XXX   -
+    VERTEX_PROGRAM_CALLBACK_FUNC_MESA     P   GetPointerv   NULL     XXX          XXX   -
+    FRAGMENT_PROGRAM_CALLBACK_DATA_MESA   P   GetPointerv   NULL     XXX          XXX   -
+    VERTEX_PROGRAM_CALLBACK_DATA_MESA     P   GetPointerv   NULL     XXX          XXX   -
+
+    XXX more?
+
+New Implementation Dependent State
+
+    None.
+
+Revision History
+
+    8 July 2003
+        Initial draft. (Brian Paul)
+    11 July 2003
+        Second draft. (Brian Paul)
+    20 July 2003
+        Third draft.  Lots of fundamental changes. (Brian Paul)
+    23 July 2003
+        Added chapter 5 and 6 spec language. (Brian Paul)
+
+Example Usage
+
+   The following is a very simple example of how this extension may
+   be used to print the values of R0, R1, R2 and R3 while executing
+   vertex programs.
+
+
+    /* This is called by the GL when the vertex program is executing.
+     * We can only make glGet* calls from within this function!
+     */
+    void DebugCallback(GLenum target, GLvoid *data)
+    {
+       GLint pos;
+       GLuint i;
+
+       /* Get PC and current instruction string */
+       glGetIntegerv(GL_VERTEX_PROGRAM_POSITION_ARB, &pos);
+
+       printf("Current position: %d\n", pos);
+
+       printf("Current temporary registers:\n");
+       for (i = 0; i < 4; i++) {
+	  GLfloat v[4];
+	  char s[10];
+	  sprintf(s, "R%d", i);
+	  glGetProgramRegisterfvMESA(GL_VERTEX_PROGRAM_ARB, strlen(s), s, v);
+	  printf("R%d = %g, %g, %g, %g\n", i, v[0], v[1], v[2], v[3]);
+       }
+    }
+
+
+    /*
+     * elsewhere...
+     */
+
+    /* Register our debugger callback function */
+    glProgramCallbackMESA(GL_VERTEX_PROGRAM_ARB, DebugCallback, NULL);
+    glEnable(GL_VERTEX_PROGRAM_CALLBACK_MESA);
+
+    /* define/bind a vertex program */
+
+    glEnable(GL_VERTEX_PROGRAM);
+
+    /* render something */
+    glBegin(GL_POINTS);
+    glVertex2f(0, 0);
+    glEnd();
+

mesa 3D driver/docs/_extra/specs/OLD/MESA_resize_buffers.spec

@@ -0,0 +1,81 @@
+Name
+
+    MESA_resize_buffers
+
+Name Strings
+
+    GL_MESA_resize_buffers
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Obsolete.
+
+Version
+
+
+Number
+
+    196
+
+Dependencies
+
+    Mesa 2.2 or later is required.
+
+Overview
+
+    Mesa is often used as a client library with no integration with
+    the computer's window system (an X server, for example).  And since
+    Mesa does not have an event loop nor window system callbacks, it
+    cannot properly respond to window system events.  In particular,
+    Mesa cannot automatically detect when a window has been resized.
+
+    Mesa's glViewport command queries the current window size and updates
+    its internal data structors accordingly.  This normally works fine
+    since most applications call glViewport in response to window size
+    changes.
+
+    In some situations, however, the application may not call glViewport
+    when a window size changes but would still like Mesa to adjust to
+    the new window size.  This extension exports a new function to solve
+    this problem.
+
+New Procedures and Functions
+
+    void glResizeBuffersMESA( void )
+
+New Tokens
+
+    none
+
+Additions to the OpenGL Specification (no particular section)
+
+    The glResizeBuffersMESA command may be called when the client
+    determines that a window has been resized.  Calling
+    glResizeBuffersMESA causes Mesa to query the current window size
+    and adjust its internal data structures.  This may include
+    reallocating depth, stencil, alpha and accumulation buffers.
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None
+
+Errors
+
+    INVALID_OPERATION is generated if glResizeBuffersMESA is called between
+    Begin and End.
+
+New State
+
+    None.
+
+New Implementation Dependent State
+
+    None.
+
+Revision History
+
+  * Revision 1.0 - Initial specification

mesa 3D driver/docs/_extra/specs/OLD/MESA_set_3dfx_mode.spec

@@ -0,0 +1,85 @@
+Name
+
+    MESA_set_3dfx_mode
+
+Name Strings
+
+    GLX_MESA_set_3dfx_mode
+
+Contact
+
+    Brian Paul (brian.paul 'at' tungstengraphics.com)
+
+Status
+
+    Obsolete.
+
+Version
+
+    Last Modified Date:  8 June 2000
+
+Number
+
+    218
+
+Dependencies
+
+    OpenGL 1.0 or later is required.
+    GLX 1.0 or later is required.
+
+Overview
+
+    The Mesa Glide driver allows full-screen rendering or rendering into
+    an X window.  The glXSet3DfxModeMESA() function allows an application
+    to switch between full-screen and windowed rendering.
+
+IP Status
+
+    Open-source; freely implementable.
+
+Issues
+
+    None.
+
+New Procedures and Functions
+
+    GLboolean glXSet3DfxModeMESA( GLint mode );
+
+New Tokens
+
+    GLX_3DFX_WINDOW_MODE_MESA	    0x1
+    GLX_3DFX_FULLSCREEN_MODE_MESA   0x2
+
+Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors)
+
+    The Mesa Glide device driver allows either rendering in full-screen
+    mode or rendering into an X window.  An application can switch between
+    full-screen and window rendering with the command:
+
+	GLboolean glXSet3DfxModeMESA( GLint mode );
+
+    <mode> may either be GLX_3DFX_WINDOW_MODE_MESA to indicate window
+    rendering or GLX_3DFX_FULLSCREEN_MODE_MESA to indicate full-screen mode.
+
+    GL_TRUE is returned if <mode> is valid and the operation completed
+    normally.  GL_FALSE is returned if <mode> is invalid or if the Glide
+    driver is not being used.
+
+    Note that only one drawable and context can be created at any given
+    time with the Mesa Glide driver.
+
+GLX Protocol
+
+    None since this is a client-side extension.
+
+Errors
+
+    None.
+
+New State
+
+    None.
+
+Revision History
+
+    8 June 2000 - initial specification

mesa 3D driver/docs/_extra/specs/OLD/MESA_sprite_point.spec

@@ -0,0 +1,190 @@
+Name
+
+    MESA_sprite_point
+
+Name Strings
+
+    GL_MESA_sprite_point
+
+Contact
+
+    Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
+
+Status
+
+    Obsolete - see GL_ARB_point_sprite.
+
+Version
+
+
+Number
+
+    ???
+
+Dependencies
+
+    GL_EXT_point_parameters effects the definition of this extension
+    GL_ARB_multitexture effects the definition of this extension
+
+Overview
+	
+    This extension modifies the way in which points are rendered,
+    specifically when they're textured.  When SPRITE_POINT_MESA is enabled
+    a point is rendered as if it were a quadrilateral with unique texture
+    coordinates at each vertex.  This extension effectively turns points
+    into sprites which may be rendered more easily and quickly than using
+    conventional textured quadrilaterals.
+
+    When using point size > 1 or attenuated points this extension is an
+    effective way to render many small sprite images for particle systems
+    or other effects.
+
+Issues:
+
+    1. How are the texture coordinates computed?
+
+       The lower-left corner has texture coordinate (0,0,r,q).
+       The lower-right, (1,0,r,q).  The upper-right, (1,1,r,q).
+       The upper-left, (0,1,r,q).
+
+    2. What about texgen and texture matrices?
+
+       Texgen and the texture matrix have no effect on the point's s and t
+       texture coordinates.  The r and q coordinates may have been computed
+       by texgen or the texture matrix.  Note that with a 3D texture and/or
+       texgen that the r coordinate could be used to select a slice in the
+       3D texture.
+
+    3. What about point smoothing?
+
+       When point smoothing is enabled, a triangle fan could be rendered
+       to approximate a circular point.  This could be problematic to
+       define and implement so POINT_SMOOTH is ignored when drawing sprite
+       points.
+
+       Smoothed points can be approximated by using an appropriate texture
+       images, alpha testing and blending.
+
+       POLYGON_SMOOTH does effect the rendering of the quadrilateral, however.
+
+    4. What about sprite rotation?
+
+       There is none.  Sprite points are always rendered as window-aligned
+       squares.  One could define rotated texture images if desired.  A 3D
+       texture and appropriate texture r coordinates could be used to
+       effectively specify image rotation per point.
+
+    5. What about POLYGON_MODE?
+
+       POLYGON_MODE does not effect the rasterization of the quadrilateral.
+
+    6. What about POLYGON_CULL?
+
+       TBD.  Polygon culling is normally specified and implemented in the
+       transformation stage of OpenGL.  However, some rasterization hardware
+       implements it later during triangle setup.
+
+       Polygon culling wouldn't be useful for sprite points since the
+       quadrilaterals are always defined in counter-clockwise order in
+       window space.  For that reason, polygon culling should probably be
+       ignored.
+
+    7. Should sprite points be alpha-attenuated if their size is below the
+       point parameter's threshold size?
+
+    8. Should there be an advertisized maximum sprite point size?
+
+       No.  Since we're rendering the point as a quadrilateral there's no
+       need to limit the size.
+
+
+New Procedures and Functions
+
+    None.
+
+New Tokens
+    
+    Accepted by the <pname> parameter of Enable, Disable, IsEnabled,
+    GetIntegerv, GetBooleanv, GetFloatv and GetDoublev:
+
+	SPRITE_POINT_MESA		0x????
+        MAX_SPRITE_POINT_SIZE_MESA      0x????   (need this?)
+
+Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
+
+    None
+
+Additions to Chapter 3 of the 1.1 Specification (Rasterization)
+
+    Section ???.
+
+    When SPRITE_POINT_MESA is enabled points are rasterized as screen-
+    aligned quadrilaterals.  If the four vertices of the quadrilateral
+    are labeled A, B, C, and D, starting at the lower-left corner and moving
+    counter-clockwise around the quadrilateral, then the vertex and
+    texture coordinates are computed as follows:
+
+      vertex   window coordinate       texture coordinate
+        A      (x-r, y-r, z, w)          (0, 0, r, q)
+        B      (x+r, y-r, z, w)          (1, 0, r, q)
+        C      (x+r, y+r, z, w)          (1, 1, r, q)
+        D      (x-r, y+r, z, w)          (0, 1, r, q)
+
+    where x, y, z, w are the point's window coordinates, r and q are the
+    point's 3rd and 4th texture coordinates  and r is half the point's
+    size.  The other vertex attributes (such as the color and fog coordinate)
+    are simply duplicated from the original point vertex.
+
+    Point size may either be specified with PointSize or computed
+    according to the EXT_point_parameters extension.
+
+    The new texture coordinates are not effected by texgen or the texture
+    matrix.  Note, however, that the texture r and q coordinates are passed
+    unchanged and may have been computed with texgen and/or the texture
+    matrix.
+
+    If multiple texture units are present the same texture coordinate is
+    used for all texture units.
+
+    The point is then rendered as if it were a quadrilateral using the
+    normal point sampling rules.  POLYGON_MODE does not effect the
+    rasterization of the quadrilateral but POLYGON_SMOOTH does.
+
+    POINT_SMOOTH has no effect when SPRITE_POINT_MESA is enabled.
+
+Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
+and the Frame Buffer)
+
+    None.
+
+Additions to Chapter 5 of the 1.1 Specification (Special Functions)
+
+    None
+
+Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
+
+    None
+
+Additions to the GLX Specification
+
+    None
+
+GLX Protocol
+
+    TBD
+
+Errors
+
+    None
+
+New State
+
+    Add boolean variable SPRITE_POINT_MESA to the point attribute group.
+
+Revision History
+
+    Version 1.0 - 4 Dec 2000
+        Original draft.
+
+
+

mesa 3D driver/docs/_extra/specs/OLD/MESA_trace.spec

@@ -0,0 +1,359 @@
+Name
+
+     MESA_trace
+
+Name Strings
+
+     GL_MESA_trace
+
+Contact
+    
+    Bernd Kreimeier, Loki Entertainment, bk 'at' lokigames.com
+    Brian Paul, VA Linux Systems, Inc., brianp 'at' valinux.com
+
+Status
+
+    Obsolete.
+
+Version
+
+
+Number
+
+    none yet
+
+Dependencies
+
+    OpenGL 1.2 is required.
+    The extension is written against the OpenGL 1.2 Specification
+
+Overview
+
+    Provides the application with means to enable and disable logging
+    of GL calls including parameters as readable text. The verbosity
+    of the generated log can be controlled. The resulting logs are
+    valid (but possibly incomplete) C code and can be compiled and 
+    linked for standalone test programs. The set of calls and the 
+    amount of static data that is logged can be controlled at runtime. 
+    The application can add comments and enable or disable tracing of GL 
+    operations at any time. The data flow from the application to GL
+    and back is unaffected except for timing.
+
+    Application-side implementation of these features raises namespace
+    and linkage issues. In the driver dispatch table a simple
+    "chain of responsibility" pattern (aka "composable piepline")
+    can be added.
+
+IP Status
+
+    The extension spec is in the public domain.  The current implementation
+    in Mesa is covered by Mesa's XFree86-style copyright by the authors above.
+    This extension is partially inspired by the Quake2 QGL wrapper.
+
+Issues
+
+ 
+    (1) Is this Extension obsolete because it can
+    be implemented as a wrapper DLL?
+
+      RESOLVED: No. While certain operating systems (Win32) provide linkers 
+      that facilitate this kind of solution, other operating systems
+      (Linux) do not support hierarchical linking, so a wrapper solution
+      would result in symbol collisions.
+      Further, IHV's might have builtin support for tracing GL execution 
+      that enjoys privileged access, or that they do not wish to separate
+      the tracing code from their driver code base.
+
+    (2) Should the Trace API explicitely support the notion of "frames? 
+    This would require hooking into glXSwapBuffers calls as well.
+
+      RESOLVED: No. The application can use NewTraceMESA/EndTraceMESA
+      and TraceComment along with external parsing tools to split the 
+      trace into frames, in whatever way considered adequate.
+
+    (2a) Should GLX calls be traced?
+
+      PBuffers and other render-to-texture solutions demonstrate that
+      context level commands beyond SwapBuffers might have to be
+      traced. The GL DLL exports the entry points, so this would not
+      be out of the question. 
+
+    (3) Should the specification mandate the actual output format?
+
+      RESOLVED: No. It is sufficient to guarantee that all data and commands 
+      will be traced as requested by Enable/DisableTraceMESA, in the order
+      encountered. Whether the resulting trace is available as a readable 
+      text file, binary metafile, compilable source code, much less which 
+      indentation and formatting has been used, is up to the implementation. 
+      For the same reason this specification does not enforce or prohibit
+      additional information added to the trace (statistics, profiling/timing, 
+      warnings on possible error conditions).
+
+    (4) Should the comment strings associated with names and pointer (ranges) 
+    be considered persistent state?
+
+      RESOLVED: No. The implementation is not forced to use this information 
+      on subsequent occurences of name/pointer, and is free to consider it 
+      transient state.
+ 
+    (5) Should comment commands be prohibited between Begin/End?
+
+      RESOLVED: Yes, with the exception of TraceCommentMESA. TraceCommentMESA 
+      is transient, the other commands might cause storage of persistent
+      data in the context. There is no need to have the ability mark names 
+      or pointers between Begin and End.
+
+
+New Procedures and Functions
+ 
+    void NewTraceMESA( bitfield mask, const ubyte * traceName )
+
+    void EndTraceMESA( void )
+
+    void EnableTraceMESA( bitfield mask )
+
+    void DisableTraceMESA( bitfield mask )
+
+    void TraceAssertAttribMESA( bitfield attribMask )
+
+    void TraceCommentMESA( const ubyte* comment )
+
+    void TraceTextureMESA( uint name, const ubyte* comment )
+
+    void TraceListMESA( uint name, const ubyte* comment )
+
+    void TracePointerMESA( void* pointer, const ubyte* comment )
+
+    void TracePointerRangeMESA( const void* first, 
+                                const void* last, 
+                                const ubyte* comment ) 
+
+New Tokens
+ 
+    Accepted by the <mask> parameter of EnableTrace and DisableTrace:
+
+       TRACE_ALL_BITS_MESA           0xFFFF
+       TRACE_OPERATIONS_BIT_MESA     0x0001
+       TRACE_PRIMITIVES_BIT_MESA     0x0002
+       TRACE_ARRAYS_BIT_MESA         0x0004
+       TRACE_TEXTURES_BIT_MESA       0x0008
+       TRACE_PIXELS_BIT_MESA         0x0010
+       TRACE_ERRORS_BIT_MESA         0x0020
+
+    Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
+    GetFloatv, and GetDoublev:
+
+       TRACE_MASK_MESA               0x8755
+
+    Accepted by the <pname> parameter to GetString:
+
+       TRACE_NAME_MESA               0x8756
+
+
+Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
+
+    None.
+
+Additions to Chapter 3 of the OpenGL 1.2.1 Specification (OpenGL Operation)
+
+    None.
+
+Additions to Chapter 4 of the OpenGL 1.2.1 Specification (OpenGL Operation)
+
+    None.
+
+Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
+
+    Add a new section:
+
+    5.7 Tracing
+
+    The tracing facility is used to record the execution of a GL program
+    to a human-readable log.  The log appears as a sequence of GL commands
+    using C syntax.  The primary intention of tracing is to aid in program
+    debugging.
+
+    A trace is started with the command
+
+      void NewTraceMESA( bitfield mask, const GLubyte * traceName )
+
+    <mask> may be any value accepted by PushAttrib and specifies a set of
+    attribute groups.  The state values included in those attribute groups
+    is written to the trace as a sequence of GL commands.
+
+    <traceName> specifies a name or label for the trace.  It is expected
+    that <traceName> will be interpreted as a filename in most implementations.
+
+    A trace is ended by calling the command
+
+      void EndTraceMESA( void )
+
+    It is illegal to call NewTraceMESA or EndTraceMESA between Begin and End. 
+
+    The commands
+
+      void EnableTraceMESA( bitfield mask )
+      void DisableTraceMESA( bitfield mask )
+
+    enable or disable tracing of different classes of GL commands.
+    <mask> may be the union of any of TRACE_OPERATIONS_BIT_MESA,
+    TRACE_PRIMITIVES_BIT_MESA, TRACE_ARRAYS_BIT_MESA, TRACE_TEXTURES_BIT_MESA,
+    and TRACE_PIXELS_BIT_MESA.  The special token TRACE_ALL_BITS_MESA
+    indicates all classes of commands are to be logged.
+
+    TRACE_OPERATIONS_BIT_MESA controls logging of all commands outside of
+    Begin/End, including Begin/End.
+  
+    TRACE_PRIMITIVES_BIT_MESA controls logging of all commands inside of
+    Begin/End, including Begin/End.
+ 
+    TRACE_ARRAYS_BIT_MESA controls logging of VertexPointer, NormalPointer,
+    ColorPointer, IndexPointer, TexCoordPointer and EdgeFlagPointer commands.
+
+    TRACE_TEXTURES_BIT_MESA controls logging of texture data dereferenced by
+    TexImage1D, TexImage2D, TexImage3D, TexSubImage1D, TexSubImage2D, and
+    TexSubImage3D commands.
+
+    TRACE_PIXELS_BIT_MESA controls logging of image data dereferenced by
+    Bitmap and DrawPixels commands.
+
+    TRACE_ERRORS_BIT_MESA controls logging of all errors. If this bit is 
+    set, GetError will be executed whereever applicable, and the result will 
+    be added to the trace as a comment. The error returns are cached and 
+    returned to the application on its GetError calls. If the user does not 
+    wish the additional GetError calls to be performed, this bit should not
+    be set.
+    
+    The command
+
+      void TraceCommentMESA( const ubyte* comment )
+
+    immediately adds the <comment> string to the trace output, surrounded
+    by C-style comment delimiters.
+
+    The commands
+
+      void TraceTextureMESA( uint name, const ubyte* comment )
+      void TraceListMESA( uint name, const ubyte* comment )
+
+    associates <comment> with the texture object or display list specified
+    by <name>.  Logged commands which reference the named texture object or
+    display list will be annotated with <comment>.  If IsTexture(name) or
+    IsList(name) fail (respectively) the command is quietly ignored.
+
+    The commands
+
+      void TracePointerMESA( void* pointer, const ubyte* comment )
+
+      void TracePointerRangeMESA( const void* first, 
+                                  const void* last,
+                                  const ubyte* comment ) 
+
+    associate <comment> with the address specified by <pointer> or with
+    a range of addresses specified by <first> through <last>.
+    Any logged commands which reference <pointer> or an address between
+    <first> and <last> will be annotated with <comment>.
+
+    The command
+
+      void TraceAssertAttribMESA( bitfield attribMask )
+
+    will add GL state queries and assertion statements to the log to
+    confirm that the current state at the time TraceAssertAttrib is
+    executed matches the current state when the trace log is executed
+    in the future.
+
+    <attribMask> is any value accepted by PushAttrib and specifies
+    the groups of state variables which are to be asserted.
+
+    The commands NewTraceMESA, EndTraceMESA, EnableTraceMESA, DisableTraceMESA,
+    TraceAssertAttribMESA, TraceCommentMESA, TraceTextureMESA, TraceListMESA, 
+    TracePointerMESA and TracePointerRangeMESA are not compiled into display lists.
+
+
+    Examples:
+
+    The command NewTraceMESA(DEPTH_BUFFER_BIT, "log") will query the state
+    variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
+    to get the values <test>, <func>, <mask>, and <clear> respectively.
+    Statements equivalent to the following will then be logged:
+
+       glEnable(GL_DEPTH_TEST);   (if <test> is true)
+       glDisable(GL_DEPTH_TEST);  (if <test> is false)
+       glDepthFunc(<func>); 
+       glDepthMask(<mask>);
+       glClearDepth(<clear>);
+   
+
+    The command TraceAssertAttribMESA(DEPTH_BUFFER_BIT) will query the state
+    variables DEPTH_TEST, DEPTH_FUNC, DEPTH_WRITEMASK, and DEPTH_CLEAR_VALUE
+    to get the values <test>, <func>, <mask>, and <clear> respectively.
+    The resulting trace might then look will like this:
+
+    {
+      GLboolean b;
+      GLint i;
+      GLfloat f;
+      b = glIsEnabled(GL_DEPTH_TEST);
+      assert(b == <test>);
+      glGetIntegerv(GL_DEPTH_FUNC, &i);
+      assert(i == <func>);
+      glGetIntegerv(GL_DEPTH_MASK, &i);
+      assert(i == <mask>);
+      glGetFloatv(GL_DEPTH_CLEAR_VALUE, &f);
+      assert(f == <clear>);
+    }
+
+
+Additions to Chapter 6 of the OpenGL 1.2.1 Specification 
+    (State and State Requests)
+
+    Querying TRACE_MASK_MESA with GetIntegerv, GetFloatv, GetBooleanv or
+    GetDoublev returns the current command class trace mask.
+
+    Querying TRACE_NAME_MESA with GetString returns the current trace name.
+
+
+Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
+
+    The MESA_trace extension can be used in a way that does not affect data 
+    flow from application to OpenGL, as well as data flow from OpenGL to 
+    application, except for timing, possible print I/O. TRACE_ERRORS_BIT_MESA
+    will add additional GetError queries. Setting a trace mask with NewTraceMESA
+    as well as use of TraceAssertAttribMESA might cause additional state queries.
+    With the possible exception of performance, OpenGL rendering should not be
+    affected at all by a properly chosen logging operation.
+
+Additions to the AGL/GLX/WGL Specifications
+
+    None.
+
+GLX Protocol
+
+    None. The logging operation is carried out client-side, by exporting
+    entry points to the wrapper functions that execute the logging operation.
+
+Errors
+
+    INVALID_OPERATION is generated if any trace command except TraceCommentMESA
+    is called between Begin and End.
+
+New State
+
+    The current trace name and current command class mask are stored
+    per-context.
+
+New Implementation Dependent State
+
+    None.
+
+Revision History
+
+  * Revision 0.1 - Initial draft from template (bk000415)
+  * Revision 0.2 - Draft (bk000906)
+  * Revision 0.3 - Draft (bk000913)
+  * Revision 0.4 - Reworked text, fixed typos (bp000914)
+  * Revision 0.5 - Assigned final GLenum values (bp001103)
+  * Revision 0.6 - TRACE_ERRORS_BIT_MESA (bk000916)
+  * Revision 0.7 - Added MESA postfix (bk010126)
+

mesa 3D driver/docs/_extra/specs/WL_bind_wayland_display.spec

@@ -0,0 +1,202 @@
+Name
+
+    WL_bind_wayland_display
+
+Name Strings
+
+    EGL_WL_bind_wayland_display
+
+Contact
+
+    Kristian Høgsberg <krh@bitplanet.net>
+    Benjamin Franzke <benjaminfranzke@googlemail.com>
+
+Status
+
+    Proposal
+
+Version
+
+    Version 5, July 16, 2013
+
+Number
+
+    EGL Extension #not assigned
+
+Dependencies
+
+    Requires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+    EGL_KHR_base_image is required.
+
+Overview
+
+    This extension provides entry points for binding and unbinding the
+    wl_display of a Wayland compositor to an EGLDisplay.  Binding a
+    wl_display means that the EGL implementation should provide one or
+    more interfaces in the Wayland protocol to allow clients to create
+    wl_buffer objects.  On the server side, this extension also
+    provides a new target for eglCreateImageKHR, to create an EGLImage
+    from a wl_buffer
+
+    Adding an implementation specific wayland interface, allows the
+    EGL implementation to define specific wayland requests and events,
+    needed for buffer sharing in an EGL wayland platform.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Procedures and Functions
+
+    EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
+                                       struct wl_display *display);
+
+    EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
+                                         struct wl_display *display);
+
+    EGLBoolean eglQueryWaylandBufferWL(EGLDisplay dpy,
+                                       struct wl_resource *buffer,
+                                       EGLint attribute, EGLint *value);
+
+New Tokens
+
+    Accepted as <target> in eglCreateImageKHR
+
+        EGL_WAYLAND_BUFFER_WL                   0x31D5
+
+    Accepted in the <attrib_list> parameter of eglCreateImageKHR:
+
+        EGL_WAYLAND_PLANE_WL                    0x31D6
+
+    Possible values for EGL_TEXTURE_FORMAT:
+
+        EGL_TEXTURE_Y_U_V_WL                    0x31D7
+        EGL_TEXTURE_Y_UV_WL                     0x31D8
+        EGL_TEXTURE_Y_XUXV_WL                   0x31D9
+        EGL_TEXTURE_EXTERNAL_WL                 0x31DA
+
+    Accepted in the <attribute> parameter of eglQueryWaylandBufferWL:
+
+        EGL_TEXTURE_FORMAT                      0x3080
+        EGL_WAYLAND_Y_INVERTED_WL               0x31DB
+
+
+Additions to the EGL 1.4 Specification:
+
+    To bind a server side wl_display to an EGLDisplay, call
+
+        EGLBoolean eglBindWaylandDisplayWL(EGLDisplay dpy,
+                                           struct wl_display *display);
+
+    To unbind a server side wl_display from an EGLDisplay, call
+    
+        EGLBoolean eglUnbindWaylandDisplayWL(EGLDisplay dpy,
+                                             struct wl_display *display);
+
+    eglBindWaylandDisplayWL returns EGL_FALSE when there is already a
+    wl_display bound to EGLDisplay otherwise EGL_TRUE.
+
+    eglUnbindWaylandDisplayWL returns EGL_FALSE when there is no
+    wl_display bound to the EGLDisplay currently otherwise EGL_TRUE.
+
+    A wl_buffer can have several planes, typically in case of planar
+    YUV formats.  Depending on the exact YUV format in use, the
+    compositor will have to create one or more EGLImages for the
+    various planes.  The eglQueryWaylandBufferWL function should be
+    used to first query the wl_buffer texture format using
+    EGL_TEXTURE_FORMAT as the attribute.  If the wl_buffer object is
+    not an EGL wl_buffer (wl_shm and other wayland extensions can
+    create wl_buffer objects of different types), this query will
+    return EGL_FALSE.  In that case the wl_buffer can not be used with
+    EGL and the compositor should have another way to get the buffer
+    contents.
+
+    If eglQueryWaylandBufferWL succeeds, the returned value will be
+    one of EGL_TEXTURE_RGB, EGL_TEXTURE_RGBA, EGL_TEXTURE_Y_U_V_WL,
+    EGL_TEXTURE_Y_UV_WL, EGL_TEXTURE_Y_XUXV_WL.  The value returned
+    describes how many EGLImages must be used, which components will
+    be sampled from each EGLImage and how they map to rgba components
+    in the shader.  The naming conventions separates planes by _ and
+    within each plane, the order or R, G, B, A, Y, U, and V indicates
+    how those components map to the rgba value returned by the
+    sampler.  X indicates that the corresponding component in the rgba
+    value isn't used.
+
+    RGB and RGBA buffer types:
+
+        EGL_TEXTURE_RGB
+                One plane, samples RGB from the texture to rgb in the
+                shader.  Alpha channel is not valid.
+
+        EGL_TEXTURE_RGBA
+                One plane, samples RGBA from the texture to rgba in the
+                shader.
+
+    YUV buffer types:
+
+        EGL_TEXTURE_Y_U_V_WL
+                Three planes, samples Y from the first plane to r in
+                the shader, U from the second plane to r, and V from
+                the third plane to r.
+
+        EGL_TEXTURE_Y_UV_WL
+                Two planes, samples Y from the first plane to r in
+                the shader, U and V from the second plane to rg.
+
+        EGL_TEXTURE_Y_XUXV_WL
+                Two planes, samples Y from the first plane to r in
+                the shader, U and V from the second plane to g and a.
+
+        EGL_TEXTURE_EXTERNAL_WL
+                Treated as a single plane texture, but sampled with
+                samplerExternalOES according to OES_EGL_image_external
+
+    After querying the wl_buffer layout, create EGLImages for the
+    planes by calling eglCreateImageKHR with wl_buffer as
+    EGLClientBuffer, EGL_WAYLAND_BUFFER_WL as the target, NULL
+    context.  If no attributes are given, an EGLImage will be created
+    for the first plane.  For multi-planar buffers, specify the plane
+    to create the EGLImage for by using the EGL_WAYLAND_PLANE_WL
+    attribute.  The value of the attribute is the index of the plane,
+    as defined by the buffer format.  Writing to an EGLImage created
+    from a wl_buffer in any way (such as glTexImage2D, binding the
+    EGLImage as a renderbuffer etc) will result in undefined behavior.
+
+    Further, eglQueryWaylandBufferWL accepts attributes EGL_WIDTH and
+    EGL_HEIGHT to query the width and height of the wl_buffer.
+
+    Also, eglQueryWaylandBufferWL may accept
+    EGL_WAYLAND_Y_INVERTED_WL attribute to query orientation of
+    wl_buffer. If EGL_WAYLAND_Y_INVERTED_WL is supported
+    eglQueryWaylandBufferWL returns EGL_TRUE and value is a boolean
+    that tells if wl_buffer is y-inverted or not. If
+    EGL_WAYLAND_Y_INVERTED_WL is not supported
+    eglQueryWaylandBufferWL returns EGL_FALSE, in that case
+    wl_buffer should be treated as if value of
+    EGL_WAYLAND_Y_INVERTED_WL was EGL_TRUE.
+
+Issues
+
+Revision History
+
+    Version 1, March 1, 2011
+        Initial draft (Benjamin Franzke)
+    Version 2, July 5, 2012
+        Add EGL_WAYLAND_PLANE_WL attribute to allow creating an EGLImage
+        for different planes of planar buffer. (Kristian Høgsberg)
+    Version 3, July 10, 2012
+        Add eglQueryWaylandBufferWL and the various buffer
+        formats. (Kristian Høgsberg)
+    Version 4, July 19, 2012
+        Use EGL_TEXTURE_FORMAT, EGL_TEXTURE_RGB, and EGL_TEXTURE_RGBA,
+        and just define the new YUV texture formats.  Add support for
+        EGL_WIDTH and EGL_HEIGHT in the query attributes (Kristian Høgsberg)
+    Version 5, July 16, 2013
+        Change eglQueryWaylandBufferWL to take a resource pointer to the
+        buffer instead of a pointer to a struct wl_buffer, as the latter has
+        been deprecated. (Ander Conselvan de Oliveira)
+    Version 6, September 16, 2013
+        Add EGL_WAYLAND_Y_INVERTED_WL attribute to allow specifying
+        wl_buffer's orientation.

mesa 3D driver/docs/_extra/specs/WL_create_wayland_buffer_from_image.spec

@@ -0,0 +1,101 @@
+Name
+
+    WL_create_wayland_buffer_from_image
+
+Name Strings
+
+    EGL_WL_create_wayland_buffer_from_image
+
+Contributors
+
+    Neil Roberts
+    Axel Davy
+    Daniel Stone
+
+Contact
+
+    Neil Roberts <neil.s.roberts@intel.com>
+
+Status
+
+    Proposal
+
+Version
+
+    Version 2, October 25, 2013
+
+Number
+
+    EGL Extension #not assigned
+
+Dependencies
+
+    Requires EGL 1.4 or later.  This extension is written against the
+    wording of the EGL 1.4 specification.
+
+    EGL_KHR_base_image is required.
+
+Overview
+
+    This extension provides an entry point to create a wl_buffer which shares
+    its contents with a given EGLImage. The expected use case for this is in a
+    nested Wayland compositor which is using subsurfaces to present buffers
+    from its clients. Using this extension it can attach the client buffers
+    directly to the subsurface without having to blit the contents into an
+    intermediate buffer. The compositing can then be done in the parent
+    compositor.
+
+    The nested compositor can create an EGLImage from a client buffer resource
+    using the existing WL_bind_wayland_display extension. It should also be
+    possible to create buffers using other types of images although there is
+    no expected use case for that.
+
+IP Status
+
+    Open-source; freely implementable.
+
+New Procedures and Functions
+
+    struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
+                                                        EGLImageKHR image);
+
+New Tokens
+
+    None.
+
+Additions to the EGL 1.4 Specification:
+
+    To create a client-side wl_buffer from an EGLImage call
+
+      struct wl_buffer *eglCreateWaylandBufferFromImageWL(EGLDisplay dpy,
+                                                          EGLImageKHR image);
+
+    The returned buffer will share the contents with the given EGLImage. Any
+    updates to the image will also be updated in the wl_buffer. Typically the
+    EGLImage will be generated in a nested Wayland compositor using a buffer
+    resource from a client via the EGL_WL_bind_wayland_display extension.
+
+    If there was an error then the function will return NULL. In particular it
+    will generate EGL_BAD_MATCH if the implementation is not able to represent
+    the image as a wl_buffer. The possible reasons for this error are
+    implementation-dependant but may include problems such as an unsupported
+    format or tiling mode or that the buffer is in memory that is inaccessible
+    to the GPU that the given EGLDisplay is using.
+
+Issues
+
+    1) Under what circumstances can the EGL_BAD_MATCH error be generated? Does
+       this include for example unsupported tiling modes?
+
+       RESOLVED: Yes, the EGL_BAD_MATCH error can be generated for any reason
+       which prevents the implementation from representing the image as a
+       wl_buffer. For example, these problems can be but are not limited to
+       unsupported tiling modes, inaccessible memory or an unsupported pixel
+       format.
+
+Revision History
+
+    Version 1, September 6, 2013
+        Initial draft (Neil Roberts)
+    Version 2, October 25, 2013
+        Added a note about more possible reasons for returning EGL_BAD_FORMAT.

mesa 3D driver/docs/_extra/specs/enums.txt

@@ -0,0 +1,107 @@
+The definitive source for enum values and reserved ranges are the XML files in
+the Khronos registry:
+
+    https://github.com/KhronosGroup/EGL-Registry/blob/master/api/egl.xml
+    https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/gl.xml
+    https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/glx.xml
+    https://github.com/KhronosGroup/OpenGL-Registry/blob/master/xml/wgl.xml
+
+GL blocks allocated to Mesa:
+       0x8750-0x875F
+       0x8BB0-0x8BBF
+
+Unused EGL blocks allocated to Mesa:
+       0x31DF
+       0x3290-0x329F
+
+GL_MESA_packed_depth_stencil
+	GL_DEPTH_STENCIL_MESA            0x8750
+	GL_UNSIGNED_INT_24_8_MESA        0x8751
+	GL_UNSIGNED_INT_8_24_REV_MESA    0x8752
+	GL_UNSIGNED_SHORT_15_1_MESA      0x8753
+	GL_UNSIGNED_SHORT_1_15_REV_MESA  0x8754
+
+GL_MESA_trace:
+	GL_TRACE_ALL_BITS_MESA           0xFFFF
+	GL_TRACE_OPERATIONS_BIT_MESA     0x0001
+	GL_TRACE_PRIMITIVES_BIT_MESA     0x0002
+	GL_TRACE_ARRAYS_BIT_MESA         0x0004
+	GL_TRACE_TEXTURES_BIT_MESA       0x0008
+	GL_TRACE_PIXELS_BIT_MESA         0x0010
+	GL_TRACE_ERRORS_BIT_MESA         0x0020
+	GL_TRACE_MASK_MESA               0x8755
+	GL_TRACE_NAME_MESA               0x8756
+
+GL_MESA_ycbcr_texture:
+	GL_YCBCR_MESA                    0x8757
+	GL_UNSIGNED_SHORT_8_8_MESA       0x85BA /* same as Apple's */
+	GL_UNSIGNED_SHORT_8_8_REV_MESA   0x85BB /* same as Apple's */
+
+GL_MESA_pack_invert:
+	GL_PACK_INVERT_MESA              0x8758
+
+GL_MESA_shader_debug.spec: (obsolete)
+        GL_DEBUG_OBJECT_MESA             0x8759
+        GL_DEBUG_PRINT_MESA              0x875A
+        GL_DEBUG_ASSERT_MESA             0x875B
+
+GL_MESA_program_debug: (obsolete)
+        GL_FRAGMENT_PROGRAM_POSITION_MESA       0x8BB0
+        GL_FRAGMENT_PROGRAM_CALLBACK_MESA       0x8BB1
+        GL_FRAGMENT_PROGRAM_CALLBACK_FUNC_MESA  0x8BB2
+        GL_FRAGMENT_PROGRAM_CALLBACK_DATA_MESA  0x8BB3
+        GL_VERTEX_PROGRAM_POSITION_MESA         0x8BB4
+        GL_VERTEX_PROGRAM_CALLBACK_MESA         0x8BB5
+        GL_VERTEX_PROGRAM_CALLBACK_FUNC_MESA    0x8BB6
+        GL_VERTEX_PROGRAM_CALLBACK_DATA_MESA    0x8BB7
+
+GL_MESAX_texture_stack:
+	GL_TEXTURE_1D_STACK_MESAX            0x8759
+	GL_TEXTURE_2D_STACK_MESAX            0x875A
+	GL_PROXY_TEXTURE_1D_STACK_MESAX      0x875B
+	GL_PROXY_TEXTURE_2D_STACK_MESAX      0x875C
+	GL_TEXTURE_1D_STACK_BINDING_MESAX    0x875D
+	GL_TEXTURE_2D_STACK_BINDING_MESAX    0x875E
+
+GL_MESA_program_binary_formats:
+        GL_PROGRAM_BINARY_FORMAT_MESA           0x875F
+
+GL_MESA_tile_raster_order
+	GL_TILE_RASTER_ORDER_FIXED_MESA		0x8BB8
+	GL_TILE_RASTER_ORDER_INCREASING_X_MESA	0x8BB9
+	GL_TILE_RASTER_ORDER_INCREASING_Y_MESA	0x8BBA
+
+GL_MESA_framebuffer_flip_y
+	GL_FRAMEBUFFER_FLIP_Y_MESA           0x8BBB
+
+EGL_MESA_drm_image
+        EGL_DRM_BUFFER_FORMAT_MESA		0x31D0
+        EGL_DRM_BUFFER_USE_MESA			0x31D1
+        EGL_DRM_BUFFER_FORMAT_ARGB32_MESA	0x31D2
+        EGL_DRM_BUFFER_MESA			0x31D3
+        EGL_DRM_BUFFER_STRIDE_MESA		0x31D4
+
+EGL_MESA_platform_gbm
+        EGL_PLATFORM_GBM_MESA                   0x31D7
+
+EGL_MESA_platform_surfaceless
+        EGL_PLATFORM_SURFACELESS_MESA           0x31DD
+
+EGL_MESA_drm_image
+        EGL_DRM_BUFFER_FORMAT_ARGB2101010_MESA  0x3290
+        EGL_DRM_BUFFER_FORMAT_ARGB1555_MESA     0x3291
+        EGL_DRM_BUFFER_FORMAT_RGB565_MESA       0x3292
+
+EGL_WL_bind_wayland_display
+        EGL_TEXTURE_FORMAT                      0x3080
+        EGL_WAYLAND_BUFFER_WL                   0x31D5
+        EGL_WAYLAND_PLANE_WL                    0x31D6
+        EGL_TEXTURE_Y_U_V_WL                    0x31D7
+        EGL_TEXTURE_Y_UV_WL                     0x31D8
+        EGL_TEXTURE_Y_XUXV_WL                   0x31D9
+        EGL_WAYLAND_Y_INVERTED_WL               0x31DB
+
+EGL_MESA_platform_xcb
+
+        EGL_PLATFORM_XCB_EXT                    0x31DC
+        EGL_PLATFORM_XCB_SCREEN_EXT             0x31DE

mesa 3D driver/docs/_exts/formatting.py

@@ -0,0 +1,33 @@
+# formatting.py
+# Sphinx extension providing formatting for Gallium-specific data
+# (c) Corbin Simpson 2010
+# Public domain to the extent permitted; contact author for special licensing
+
+import docutils.nodes
+import sphinx.addnodes
+
+def parse_envvar(env, sig, signode):
+    envvar, t, default = sig.split(" ", 2)
+    envvar = envvar.strip().upper()
+    t = "Type: %s" % t.strip(" <>").lower()
+    default = "Default: %s" % default.strip(" ()")
+    signode += sphinx.addnodes.desc_name(envvar, envvar)
+    signode += docutils.nodes.Text(' ')
+    signode += sphinx.addnodes.desc_type(t, t)
+    signode += docutils.nodes.Text(', ')
+    signode += sphinx.addnodes.desc_annotation(default, default)
+    return envvar
+
+def parse_opcode(env, sig, signode):
+    opcode, desc = sig.split("-", 1)
+    opcode = opcode.strip().upper()
+    desc = " (%s)" % desc.strip()
+    signode += sphinx.addnodes.desc_name(opcode, opcode)
+    signode += sphinx.addnodes.desc_annotation(desc, desc)
+    return opcode
+
+def setup(app):
+    app.add_object_type("envvar", "envvar", "%s (environment variable)",
+        parse_envvar)
+    app.add_object_type("opcode", "opcode", "%s (TGSI opcode)",
+        parse_opcode)

mesa 3D driver/docs/_exts/redirects.py

@@ -0,0 +1,27 @@
+import os
+import pathlib
+from urllib.parse import urlparse
+
+def create_redirect(dst):
+    tpl = '<html><head><meta http-equiv="refresh" content="0; url={0}"><script>window.location.replace("{0}")</script></head></html>'
+    return tpl.format(dst)
+
+def create_redirects(app, exception):
+    if exception is not None or not app.builder.name == 'html':
+        return
+    for src, dst in app.config.html_redirects:
+        path = os.path.join(app.outdir, '{0}.html'.format(src))
+
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+
+        if urlparse(dst).scheme == "":
+            dst = pathlib.posixpath.relpath(dst, start=os.path.dirname(src))
+            if not os.path.isfile(os.path.join(os.path.dirname(path), dst)):
+                raise Exception('{0} does not exitst'.format(dst))
+
+        with open(path, 'w') as f:
+            f.write(create_redirect(dst))
+
+def setup(app):
+    app.add_config_value('html_redirects', [], '')
+    app.connect('build-finished', create_redirects)

mesa 3D driver/docs/android.rst

@@ -0,0 +1,169 @@
+Android
+=======
+
+Mesa hardware drivers can be built for Android one of two ways: built
+into the Android OS using the Android.mk build system on older versions
+of Android, or out-of-tree using the Meson build system and the
+Android NDK.
+
+The Android.mk build system has proven to be hard to maintain, as one
+needs a built Android tree to build against, and it has never been
+tested in CI.  The meson build system flow is frequently used by
+Chrome OS developers for building and testing Android drivers.
+
+Building using the Android NDK
+------------------------------
+
+Download and install the NDK using whatever method you normally would.
+Then, create your meson cross file to use it, something like this
+``~/.local/share/meson/cross/android-aarch64`` file::
+
+    [binaries]
+    ar = 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-ar'
+    c = ['ccache', 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang']
+    cpp = ['ccache', 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang++', '-fno-exceptions', '-fno-unwind-tables', '-fno-asynchronous-unwind-tables', '-static-libstdc++']
+    c_ld = 'lld'
+    cpp_ld = 'lld'
+    strip = 'NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android-strip'
+    # Android doesn't come with a pkg-config, but we need one for meson to be happy not
+    # finding all the optional deps it looks for.  Use system pkg-config pointing at a
+    # directory we get to populate with any .pc files we want to add for Android
+    pkgconfig = ['env', 'PKG_CONFIG_LIBDIR=NDKDIR/pkgconfig', '/usr/bin/pkg-config']
+
+    [host_machine]
+    system = 'linux'
+    cpu_family = 'arm'
+    cpu = 'armv8'
+    endian = 'little'
+
+Now, use that cross file for your Android build directory (as in this
+one cross-compiling the turnip driver for a stock Pixel phone)
+
+.. code-block:: console
+
+    meson build-android-aarch64 \
+        --cross-file android-aarch64 \
+	-Dplatforms=android \
+	-Dplatform-sdk-version=26 \
+	-Dandroid-stub=true \
+	-Dgallium-drivers= \
+	-Dvulkan-drivers=freedreno \
+	-Dfreedreno-kgsl=true
+    ninja -C build-android-aarch64
+
+Replacing Android drivers on stock Android
+------------------------------------------
+
+The vendor partition with the drivers is normally mounted from a
+read-only disk image on ``/vendor``.  To be able to replace them for
+driver development, we need to unlock the device and remount
+``/vendor`` read/write.
+
+.. code-block:: console
+
+    adb disable-verity
+    adb reboot
+    adb remount -R
+
+Now you can replace drivers as in:
+
+.. code-block:: console
+
+    adb push build-android-aarch64/src/freedreno/vulkan/libvulkan_freedreno.so /vendor/lib64/hw/vulkan.sdm710.so
+
+Note this command doesn't quite work because libvulkan wants the
+SONAME to match.  For now, in turnip we have been using a hack to the
+meson.build to change the SONAME.
+
+Replacing Android drivers on Chrome OS
+--------------------------------------
+
+Chrome OS's ARC++ is an Android container with hardware drivers inside
+of it.  The vendor partition with the drivers is normally mounted from
+a read-only squashfs image on disk.  For doing rapid driver
+development, you don't want to regenerate that image.  So, we'll take
+the existing squashfs image, copy it out on the host, and then use a
+bind mount instead of a loopback mount so we can update our drivers
+using scp from outside the container.
+
+On your device, you'll want to make ``/`` read-write.  ssh in as root
+and run:
+
+.. code-block:: console
+
+    crossystem dev_boot_signed_only=0
+    /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification --partitions 4
+    reboot
+
+Then, we'll switch Android from using an image for ``/vendor`` to using a
+bind-mount from a directory we control.
+
+.. code-block:: console
+
+    cd /opt/google/containers/android/
+    mkdir vendor-ro
+    mount -o loop vendor.raw.img vendor-ro
+    cp -a vendor-ro vendor-rw
+    emacs config.json
+
+In the ``config.json``, you want to find the block for ``/vendor`` and
+change it to::
+
+            {
+                "destination": "/vendor",
+                "type": "bind",
+                "source": "/opt/google/containers/android/vendor-rw",
+                "options": [
+                    "bind",
+                    "rw"
+                ]
+            },
+
+Now, restart the UI to do a full reload:
+
+.. code-block:: console
+
+    restart ui
+
+At this point, your android container is restarted with your new
+bind-mount ``/vendor``, and if you use ``android-sh`` to shell into it
+then the ``mount`` command should show::
+
+    /dev/root on /vendor type ext2 (rw,seclabel,relatime)
+
+Now, replacing your DRI driver with a new one built for Android should
+be a matter of:
+
+.. code-block:: console
+
+    scp msm_dri.so $HOST:/opt/google/containers/android/vendor-rw/lib64/dri/
+
+You can do your build of your DRI driver using ``emerge-$BOARD
+arc-mesa-freedreno`` (for example) if you have a source tree with
+ARC++, but it should also be possible to build using the NDK as
+described above.  There are currently rough edges with this, for
+example the build will require that you have your arc-libdrm build
+available to the NDK, assuming you're building anything but the
+freedreno Vulkan driver for KGSL.  You can mostly put things in place
+with:
+
+.. code-block:: console
+
+    scp $HOST:/opt/google/containers/android/vendor-rw/lib64/libdrm.so \
+        NDKDIR/sysroot/usr/lib/aarch64-linux-android/lib/
+
+    ln -s \
+        /usr/include/xf86drm.h \
+	/usr/include/libsync.h \
+	/usr/include/libdrm \
+	NDKDIR/sysroot/usr/include/
+
+It seems that new invocations of an application will often reload the
+DRI driver, but depending on the component you're working on you may
+find you need to reload the whole Android container.  To do so without
+having to log in to Chrome again every time, you can just kill the
+container and let it restart:
+
+.. code-block:: console
+
+    kill $(cat /run/containers/android-run_oci/container.pid )

mesa 3D driver/docs/application-issues.rst

@@ -0,0 +1,48 @@
+Application Issues
+==================
+
+This page documents known issues with some OpenGL applications.
+
+Topogun
+-------
+
+`Topogun <http://www.topogun.com/>`__ for Linux (version 2, at least)
+creates a GLX visual without requesting a depth buffer. This causes bad
+rendering if the OpenGL driver happens to choose a visual without a
+depth buffer.
+
+Mesa 9.1.2 and later (will) support a DRI configuration option to work
+around this issue. Using the
+`driconf <https://dri.freedesktop.org/wiki/DriConf>`__ tool, set the
+"Create all visuals with a depth buffer" option before running Topogun.
+Then, all GLX visuals will be created with a depth buffer.
+
+Old OpenGL games
+----------------
+
+Some old OpenGL games (approx. ten years or older) may crash during
+start-up because of an extension string buffer-overflow problem.
+
+The problem is a modern OpenGL driver will return a very long string for
+the ``glGetString(GL_EXTENSIONS)`` query and if the application naively
+copies the string into a fixed-size buffer it can overflow the buffer
+and crash the application.
+
+The work-around is to set the ``MESA_EXTENSION_MAX_YEAR`` environment
+variable to the approximate release year of the game. This will cause
+the ``glGetString(GL_EXTENSIONS)`` query to only report extensions older
+than the given year.
+
+For example, if the game was released in 2001, do
+
+.. code-block:: console
+
+   export MESA_EXTENSION_MAX_YEAR=2001
+
+before running the game.
+
+Viewperf
+--------
+
+See the :doc:`Viewperf issues <viewperf>` page for a detailed list of
+Viewperf issues.

mesa 3D driver/docs/bugs.rst

@@ -0,0 +1,30 @@
+Report a Bug
+============
+
+The Mesa bug database is hosted on
+`freedesktop.org <https://freedesktop.org>`__. The old bug database on
+SourceForge is no longer used.
+
+To file a Mesa bug, go to `GitLab on
+freedesktop.org <https://gitlab.freedesktop.org/mesa/mesa/-/issues>`__
+
+Please follow these bug reporting guidelines:
+
+-  Check if a new version of Mesa is available which might have fixed
+   the problem.
+-  Check if your bug is already reported in the database.
+-  Monitor your bug report for requests for additional information, etc.
+-  Attach the output of running glxinfo or wglinfo. This will tell us
+   the Mesa version, which device driver you're using, etc.
+-  If you're reporting a crash, try to use your debugger (gdb) to get a
+   stack trace. Also, recompile Mesa in debug mode to get more detailed
+   information.
+-  Describe in detail how to reproduce the bug, especially with games
+   and applications that the Mesa developers might not be familiar with.
+-  Provide an `apitrace <https://github.com/apitrace/apitrace>`__ or
+   simple GLUT-based test program if possible.
+
+The easier a bug is to reproduce, the sooner it will be fixed. Please do
+everything you can to facilitate quickly fixing bugs. If your bug report
+is vague or your test program doesn't compile easily, the problem may
+not be fixed very quickly.

mesa 3D driver/docs/ci/LAVA.rst

@@ -0,0 +1,86 @@
+LAVA CI
+=======
+
+`LAVA <https://lavasoftware.org/>`_ is a system for functional testing
+of boards including deploying custom bootloaders and kernels.  This is
+particularly relevant to testing Mesa because we often need to change
+kernels for UAPI changes (and this lets us do full testing of a new
+kernel during development), and our workloads can easily take down
+boards when mistakes are made (kernel oopses, OOMs that take out
+critical system services).
+
+Mesa-LAVA software architecture
+-------------------------------
+
+The gitlab-runner will run on some host that has access to the LAVA
+lab, with tags like "lava-mesa-boardname" to control only taking in
+jobs for the hardware that the LAVA lab contains.  The gitlab-runner
+spawns a Docker container with lava-cli in it, and connects to the
+LAVA lab using a predefined token to submit jobs under a specific
+device type.
+
+The LAVA instance manages scheduling those jobs to the boards present.
+For a job, it will deploy the kernel, device tree, and the ramdisk
+containing the CTS.
+
+Deploying a new Mesa-LAVA lab
+-----------------------------
+
+You'll want to start with setting up your LAVA instance and getting
+some boards booting using test jobs.  Start with the stock QEMU
+examples to make sure your instance works at all.  Then, you'll need
+to define your actual boards.
+
+The device type in lava-gitlab-ci.yml is the device type you create in
+your LAVA instance, which doesn't have to match the board's name in
+``/etc/lava-dispatcher/device-types``.  You create your boards under
+that device type and the Mesa jobs will be scheduled to any of them.
+Instantiate your boards by creating them in the UI or at the command
+line attached to that device type, then populate their dictionary
+(using an "extends" line probably referencing the board's template in
+``/etc/lava-dispatcher/device-types``).  Now, go find a relevant
+healthcheck job for your board as a test job definition, or cobble
+something together from a board that boots using the same boot_method
+and some public images, and figure out how to get your boards booting.
+
+Once you can boot your board using a custom job definition, it's time
+to connect Mesa CI to it.  Install gitlab-runner and register as a
+shared runner (you'll need a GitLab admin for help with this).  The
+runner *must* have a tag (like "mesa-lava-db410c") to restrict the
+jobs it takes or it will grab random jobs from tasks across
+``gitlab.freedesktop.org``, and your runner isn't ready for that.
+
+The runner will be running an ARM Docker image (we haven't done any
+x86 LAVA yet, so that isn't documented).  If your host for the
+gitlab-runner is x86, then you'll need to install qemu-user-static and
+the binfmt support.
+
+The Docker image will need access to the lava instance.  If it's on a
+public network it should be fine.  If you're running the LAVA instance
+on localhost, you'll need to set ``network_mode="host"`` in
+``/etc/gitlab-runner/config.toml`` so it can access localhost.  Create a
+gitlab-runner user in your LAVA instance, log in under that user on
+the web interface, and create an API token.  Copy that into a
+``lavacli.yaml``:
+
+.. code-block:: yaml
+
+  default:
+    token: <token contents>
+    uri: <URL to the instance>
+    username: gitlab-runner
+
+Add a volume mount of that ``lavacli.yaml`` to
+``/etc/gitlab-runner/config.toml`` so that the Docker container can
+access it.  You probably have a ``volumes = ["/cache"]`` already, so now it would be::
+
+    volumes = ["/home/anholt/lava-config/lavacli.yaml:/root/.config/lavacli.yaml", "/cache"]
+
+Note that this token is visible to anybody that can submit MRs to
+Mesa!  It is not an actual secret.  We could just bake it into the
+GitLab CI yml, but this way the current method of connecting to the
+LAVA instance is separated from the Mesa branches (particularly
+relevant as we have many stable branches all using CI).
+
+Now it's time to define your test runner in
+``.gitlab-ci/lava-gitlab-ci.yml``.

mesa 3D driver/docs/ci/bare-metal.rst

@@ -0,0 +1,170 @@
+Bare-metal CI
+=============
+
+The bare-metal scripts run on a system with gitlab-runner and Docker,
+connected to potentially multiple bare-metal boards that run tests of
+Mesa.  Currently only "fastboot" and "ChromeOS Servo" devices are
+supported.
+
+In comparison with LAVA, this doesn't involve maintaining a separate
+web service with its own job scheduler and replicating jobs between the
+two.  It also places more of the board support in Git, instead of
+web service configuration.  On the other hand, the serial interactions
+and bootloader support are more primitive.
+
+Requirements (fastboot)
+-----------------------
+
+This testing requires power control of the DUTs by the gitlab-runner
+machine, since this is what we use to reset the system and get back to
+a pristine state at the start of testing.
+
+We require access to the console output from the gitlab-runner system,
+since that is how we get the final results back from the tests.  You
+should probably have the console on a serial connection, so that you
+can see bootloader progress.
+
+The boards need to be able to have a kernel/initramfs supplied by the
+gitlab-runner system, since the initramfs is what contains the Mesa
+testing payload.
+
+The boards should have networking, so that we can extract the dEQP .xml
+results to artifacts on GitLab.
+
+Requirements (servo)
+--------------------
+
+For servo-connected boards, we can use the EC connection for power
+control to reboot the board.  However, loading a kernel is not as easy
+as fastboot, so we assume your bootloader can do TFTP, and that your
+gitlab-runner mounts the runner's tftp directory specific to the board
+at /tftp in the container.
+
+Since we're going the TFTP route, we also use NFS root.  This avoids
+packing the rootfs and sending it to the board as a ramdisk, which
+means we can support larger rootfses (for piglit testing), at the cost
+of needing more storage on the runner.
+
+Telling the board about where its TFTP and NFS should come from is
+done using dnsmasq on the runner host.  For example, this snippet in
+the dnsmasq.conf.d in the google farm, with the gitlab-runner host we
+call "servo"::
+
+  dhcp-host=1c:69:7a:0d:a3:d3,10.42.0.10,set:servo
+
+  # Fixed dhcp addresses for my sanity, and setting a tag for
+  # specializing other DHCP options
+  dhcp-host=a0:ce:c8:c8:d9:5d,10.42.0.11,set:cheza1
+  dhcp-host=a0:ce:c8:c8:d8:81,10.42.0.12,set:cheza2
+
+  # Specify the next server, watch out for the double ',,'.  The
+  # filename didn't seem to get picked up by the bootloader, so we use
+  # tftp-unique-root and mount directories like
+  # /srv/tftp/10.42.0.11/jwerner/cheza as /tftp in the job containers.
+  tftp-unique-root
+  dhcp-boot=tag:cheza1,cheza1/vmlinuz,,10.42.0.10
+  dhcp-boot=tag:cheza2,cheza2/vmlinuz,,10.42.0.10
+
+  dhcp-option=tag:cheza1,option:root-path,/srv/nfs/cheza1
+  dhcp-option=tag:cheza2,option:root-path,/srv/nfs/cheza2
+
+Setup
+-----
+
+Each board will be registered in freedesktop.org GitLab.  You'll want
+something like this to register a fastboot board:
+
+.. code-block:: console
+
+  sudo gitlab-runner register \
+       --url https://gitlab.freedesktop.org \
+       --registration-token $1 \
+       --name MY_BOARD_NAME \
+       --tag-list MY_BOARD_TAG \
+       --executor docker \
+       --docker-image "alpine:latest" \
+       --docker-volumes "/dev:/dev" \
+       --docker-network-mode "host" \
+       --docker-privileged \
+       --non-interactive
+
+For a servo board, you'll need to also volume mount the board's NFS
+root dir at /nfs and TFTP kernel directory at /tftp.
+
+The registration token has to come from a freedesktop.org GitLab admin
+going to https://gitlab.freedesktop.org/admin/runners
+
+The name scheme for Google's lab is google-freedreno-boardname-n, and
+our tag is something like google-freedreno-db410c.  The tag is what
+identifies a board type so that board-specific jobs can be dispatched
+into that pool.
+
+We need privileged mode and the /dev bind mount in order to get at the
+serial console and fastboot USB devices (--device arguments don't
+apply to devices that show up after container start, which is the case
+with fastboot, and the servo serial devices are actually links to
+/dev/pts).  We use host network mode so that we can spin up a nginx
+server to collect XML results for fastboot.
+
+Once you've added your boards, you're going to need to add a little
+more customization in ``/etc/gitlab-runner/config.toml``.  First, add
+``concurrent = <number of boards>`` at the top ("we should have up to
+this many jobs running managed by this gitlab-runner").  Then for each
+board's runner, set ``limit = 1`` ("only 1 job served by this board at a
+time").  Finally, add the board-specific environment variables
+required by your bare-metal script, something like::
+
+  [[runners]]
+    name = "google-freedreno-db410c-1"
+    environment = ["BM_SERIAL=/dev/ttyDB410c8", "BM_POWERUP=google-power-up.sh 8", "BM_FASTBOOT_SERIAL=15e9e390", "FDO_CI_CONCURRENT=4"]
+
+The ``FDO_CI_CONCURRENT`` variable should be set to the number of CPU threads on
+the board, which is used for auto-tuning of job parallelism.
+
+If you want to collect the results for fastboot you need to add the following
+two board-specific environment variables ``BM_WEBDAV_IP`` and ``BM_WEBDAV_PORT``.
+These represent the IP address of the Docker host and the board specific port number
+that gets used to start a nginx server.
+
+Once you've updated your runners' configs, restart with ``sudo service
+gitlab-runner restart``
+
+Caching downloads
+-----------------
+
+To improve the runtime for downloading traces during traces job runs, you will
+want a pass-through HTTP cache.  On your runner box, install nginx:
+
+.. code-block:: console
+
+  sudo apt install nginx libnginx-mod-http-lua
+
+Add the server setup files:
+
+.. literalinclude: fdo-cache:
+   :name: /etc/nginx/sites-available/fdo-cache
+
+.. literalinclude: uri-caching.conf:
+   :name: /etc/nginx/sites-available/snippets/uri-caching.conf
+
+Edit the listener addresses in fdo-cache to suit the ethernet interface that
+your devices are on.
+
+Enable the site and restart nginx:
+
+.. code-block:: console
+
+  sudo ln -s /etc/nginx/sites-available/fdo-cache /etc/nginx/sites-enabled/fdo-cache
+  sudo service nginx restart
+
+  # First download will hit the internet
+  wget http://localhost/cache/?uri=https://minio-packet.freedesktop.org/mesa-tracie-public/itoral-gl-terrain-demo/demo.trace
+  # Second download should be cached.
+  wget http://localhost/cache/?uri=https://minio-packet.freedesktop.org/mesa-tracie-public/itoral-gl-terrain-demo/demo.trace
+
+Now, set ``download-url`` in your ``traces-*.yml`` entry to something like
+``http://10.42.0.1:8888/cache/?uri=https://minio-packet.freedesktop.org/mesa-tracie-public``
+and you should have cached downloads for traces.  Add it to
+``FDO_HTTP_CACHE_URI=`` in your ``config.toml`` runner environment lines and you
+can use it for cached artifact downloads instead of going all the way to
+freedesktop.org on each job.

mesa 3D driver/docs/ci/docker.rst

@@ -0,0 +1,74 @@
+Docker CI
+=========
+
+For llvmpipe and swrast CI, we run tests in a container containing
+VK-GL-CTS, on the shared GitLab runners provided by `freedesktop
+<http://freedesktop.org>`_
+
+Software architecture
+---------------------
+
+The Docker containers are rebuilt using the shell scripts under
+.gitlab-ci/container/ when the FDO\_DISTRIBUTION\_TAG changes in
+.gitlab-ci.yml. The resulting images are around 1 GB, and are
+expected to change approximately weekly (though an individual
+developer working on them may produce many more images while trying to
+come up with a working MR!).
+
+gitlab-runner is a client that polls gitlab.freedesktop.org for
+available jobs, with no inbound networking requirements.  Jobs can
+have tags, so we can have DUT-specific jobs that only run on runners
+with that tag marked in the GitLab UI.
+
+Since dEQP takes a long time to run, we mark the job as "parallel" at
+some level, which spawns multiple jobs from one definition, and then
+deqp-runner.sh takes the corresponding fraction of the test list for
+that job.
+
+To reduce dEQP runtime (or avoid tests with unreliable results), a
+deqp-runner.sh invocation can provide a list of tests to skip.  If
+your driver is not yet conformant, you can pass a list of expected
+failures, and the job will only fail on tests that aren't listed (look
+at the job's log for which specific tests failed).
+
+DUT requirements
+----------------
+
+In addition to the general :ref:`CI-farm-expectations`, using
+Docker requires:
+
+* DUTs must have a stable kernel and GPU reset (if applicable).
+
+If the system goes down during a test run, that job will eventually
+time out and fail (default 1 hour).  However, if the kernel can't
+reliably reset the GPU on failure, bugs in one MR may leak into
+spurious failures in another MR.  This would be an unacceptable impact
+on Mesa developers working on other drivers.
+
+* DUTs must be able to run Docker
+
+The Mesa gitlab-runner based test architecture is built around Docker,
+so that we can cache the Debian package installation and CTS build
+step across multiple test runs.  Since the images are large and change
+approximately weekly, the DUTs also need to be running some script to
+prune stale Docker images periodically in order to not run out of disk
+space as we rev those containers (perhaps `this script
+<https://gitlab.com/gitlab-org/gitlab-runner/issues/2980#note_169233611>`_).
+
+Note that Docker doesn't allow containers to be stored on NFS, and
+doesn't allow multiple Docker daemons to interact with the same
+network block device, so you will probably need some sort of physical
+storage on your DUTs.
+
+* DUTs must be public
+
+By including your device in .gitlab-ci.yml, you're effectively letting
+anyone on the internet run code on your device.  Docker containers may
+provide some limited protection, but how much you trust that and what
+you do to mitigate hostile access is up to you.
+
+* DUTs must expose the dri device nodes to the containers.
+
+Obviously, to get access to the HW, we need to pass the render node
+through.  This is done by adding ``devices = ["/dev/dri"]`` to the
+``runners.docker`` section of /etc/gitlab-runner/config.toml.

mesa 3D driver/docs/ci/fdo-cache

@@ -0,0 +1,44 @@
+proxy_cache_path /var/cache/nginx/ levels=1:2 keys_zone=my_cache:10m max_size=24g inactive=48h use_temp_path=off;
+
+server {
+	listen 10.42.0.1:8888 default_server;
+	listen 127.0.0.1:8888 default_server;
+	listen [::]:8888 default_server;
+	resolver 8.8.8.8;
+
+	root /var/www/html;
+
+	# Add index.php to the list if you are using PHP
+	index index.html index.htm index.nginx-debian.html;
+
+	server_name _;
+
+        add_header X-GG-Cache-Status $upstream_cache_status;
+        proxy_cache my_cache;
+
+        location /cache_gitlab_artifacts {
+                internal;
+                # Gitlabs http server puts everything as no-cache even though
+                # the artifacts URLS don't change. So enforce a long validity
+                # time and ignore the headers that defeat caching
+                proxy_cache_valid 200 48h;
+                proxy_ignore_headers Cache-Control Set-Cookie;
+                include snippets/uri-caching.conf;
+        }
+
+        location /cache {
+                # special case gitlab artifacts
+                if ($arg_uri ~*  /.*gitlab.*artifacts(\/|%2F)raw/ ) {
+                        rewrite ^ /cache_gitlab_artifacts;
+                }
+                # Set a really low validity together with cache revalidation; Our goal
+                # for caching isn't to lower the number of http requests but to
+                # lower the amount of data transfer. Also for some test
+                # scenarios (typical manual tests) the file at a given url
+                # might get modified so avoid confusion by ensuring
+                # revalidations happens often.
+                proxy_cache_valid 200 10s;
+                proxy_cache_revalidate on;
+                include snippets/uri-caching.conf;
+        }
+}

mesa 3D driver/docs/ci/index.rst

@@ -0,0 +1,211 @@
+Continuous Integration
+======================
+
+GitLab CI
+---------
+
+GitLab provides a convenient framework for running commands in response to Git pushes.
+We use it to test merge requests (MRs) before merging them (pre-merge testing),
+as well as post-merge testing, for everything that hits ``main``
+(this is necessary because we still allow commits to be pushed outside of MRs,
+and even then the MR CI runs in the forked repository, which might have been
+modified and thus is unreliable).
+
+The CI runs a number of tests, from trivial build-testing to complex GPU rendering:
+
+- Build testing for a number of build systems, configurations and platforms
+- Sanity checks (``meson test``)
+- Some drivers (softpipe, llvmpipe, freedreno and panfrost) are also tested
+  using `VK-GL-CTS <https://github.com/KhronosGroup/VK-GL-CTS>`__
+- Replay of application traces
+
+A typical run takes between 20 and 30 minutes, although it can go up very quickly
+if the GitLab runners are overwhelmed, which happens sometimes. When it does happen,
+not much can be done besides waiting it out, or cancel it.
+
+Due to limited resources, we currently do not run the CI automatically
+on every push; instead, we only run it automatically once the MR has
+been assigned to ``Marge``, our merge bot.
+
+If you're interested in the details, the main configuration file is ``.gitlab-ci.yml``,
+and it references a number of other files in ``.gitlab-ci/``.
+
+If the GitLab CI doesn't seem to be running on your fork (or MRs, as they run
+in the context of your fork), you should check the "Settings" of your fork.
+Under "CI / CD" → "General pipelines", make sure "Custom CI config path" is
+empty (or set to the default ``.gitlab-ci.yml``), and that the
+"Public pipelines" box is checked.
+
+If you're having issues with the GitLab CI, your best bet is to ask
+about it on ``#freedesktop`` on Freenode and tag `Daniel Stone
+<https://gitlab.freedesktop.org/daniels>`__ (``daniels`` on IRC) or
+`Eric Anholt <https://gitlab.freedesktop.org/anholt>`__ (``anholt`` on
+IRC).
+
+The three GitLab CI systems currently integrated are:
+
+
+.. toctree::
+   :maxdepth: 1
+
+   bare-metal
+   LAVA
+   docker
+
+Intel CI
+--------
+
+The Intel CI is not yet integrated into the GitLab CI.
+For now, special access must be manually given (file a issue in
+`the Intel CI configuration repo <https://gitlab.freedesktop.org/Mesa_CI/mesa_jenkins>`__
+if you think you or Mesa would benefit from you having access to the Intel CI).
+Results can be seen on `mesa-ci.01.org <https://mesa-ci.01.org>`__
+if you are *not* an Intel employee, but if you are you
+can access a better interface on
+`mesa-ci-results.jf.intel.com <http://mesa-ci-results.jf.intel.com>`__.
+
+The Intel CI runs a much larger array of tests, on a number of generations
+of Intel hardware and on multiple platforms (X11, Wayland, DRM & Android),
+with the purpose of detecting regressions.
+Tests include
+`Crucible <https://gitlab.freedesktop.org/mesa/crucible>`__,
+`VK-GL-CTS <https://github.com/KhronosGroup/VK-GL-CTS>`__,
+`dEQP <https://android.googlesource.com/platform/external/deqp>`__,
+`Piglit <https://gitlab.freedesktop.org/mesa/piglit>`__,
+`Skia <https://skia.googlesource.com/skia>`__,
+`VkRunner <https://github.com/Igalia/vkrunner>`__,
+`WebGL <https://github.com/KhronosGroup/WebGL>`__,
+and a few other tools.
+A typical run takes between 30 minutes and an hour.
+
+If you're having issues with the Intel CI, your best bet is to ask about
+it on ``#dri-devel`` on Freenode and tag `Clayton Craft
+<https://gitlab.freedesktop.org/craftyguy>`__ (``craftyguy`` on IRC) or
+`Nico Cortes <https://gitlab.freedesktop.org/ngcortes>`__ (``ngcortes``
+on IRC).
+
+.. _CI-farm-expectations:
+
+CI farm expectations
+--------------------
+
+To make sure that testing of one vendor's drivers doesn't block
+unrelated work by other vendors, we require that a given driver's test
+farm produces a spurious failure no more than once a week.  If every
+driver had CI and failed once a week, we would be seeing someone's
+code getting blocked on a spurious failure daily, which is an
+unacceptable cost to the project.
+
+Additionally, the test farm needs to be able to provide a short enough
+turnaround time that we can get our MRs through marge-bot without the
+pipeline backing up.  As a result, we require that the test farm be
+able to handle a whole pipeline's worth of jobs in less than 15 minutes
+(to compare, the build stage is about 10 minutes).
+
+If a test farm is short the HW to provide these guarantees, consider dropping
+tests to reduce runtime.  dEQP job logs print the slowest tests at the end of
+the run, and piglit logs the runtime of tests in the results.json.bz2 in the
+artifacts.  Or, you can add the following to your job to only run some fraction
+(in this case, 1/10th) of the deqp tests.
+
+.. code-block:: yaml
+
+    variables:
+      DEQP_FRACTION: 10
+
+to just run 1/10th of the test list.
+
+If a HW CI farm goes offline (network dies and all CI pipelines end up
+stalled) or its runners are consistently spuriously failing (disk
+full?), and the maintainer is not immediately available to fix the
+issue, please push through an MR disabling that farm's jobs by adding
+'.' to the front of the jobs names until the maintainer can bring
+things back up.  If this happens, the farm maintainer should provide a
+report to mesa-dev@lists.freedesktop.org after the fact explaining
+what happened and what the mitigation plan is for that failure next
+time.
+
+Personal runners
+----------------
+
+Mesa's CI is currently run primarily on packet.net's m1xlarge nodes
+(2.2Ghz Sandy Bridge), with each job getting 8 cores allocated.  You
+can speed up your personal CI builds (and marge-bot merges) by using a
+faster personal machine as a runner.  You can find the gitlab-runner
+package in Debian, or use GitLab's own builds.
+
+To do so, follow `GitLab's instructions
+<https://docs.gitlab.com/ce/ci/runners/#create-a-specific-runner>`__ to
+register your personal GitLab runner in your Mesa fork.  Then, tell
+Mesa how many jobs it should serve (``concurrent=``) and how many
+cores those jobs should use (``FDO_CI_CONCURRENT=``) by editing these
+lines in ``/etc/gitlab-runner/config.toml``, for example::
+
+  concurrent = 2
+
+  [[runners]]
+    environment = ["FDO_CI_CONCURRENT=16"]
+
+
+Docker caching
+--------------
+
+The CI system uses Docker images extensively to cache
+infrequently-updated build content like the CTS.  The `freedesktop.org
+CI templates
+<https://gitlab.freedesktop.org/freedesktop/ci-templates/>`_ help us
+manage the building of the images to reduce how frequently rebuilds
+happen, and trim down the images (stripping out manpages, cleaning the
+apt cache, and other such common pitfalls of building Docker images).
+
+When running a container job, the templates will look for an existing
+build of that image in the container registry under
+``MESA_IMAGE_TAG``.  If it's found it will be reused, and if
+not, the associated `.gitlab-ci/containers/<jobname>.sh`` will be run
+to build it.  So, when developing any change to container build
+scripts, you need to update the associated ``MESA_IMAGE_TAG`` to
+a new unique string.  We recommend using the current date plus some
+string related to your branch (so that if you rebase on someone else's
+container update from the same day, you will get a Git conflict
+instead of silently reusing their container)
+
+When developing a given change to your Docker image, you would have to
+bump the tag on each ``git commit --amend`` to your development
+branch, which can get tedious.  Instead, you can navigate to the
+`container registry
+<https://gitlab.freedesktop.org/mesa/mesa/container_registry>`_ for
+your repository and delete the tag to force a rebuild.  When your code
+is eventually merged to main, a full image rebuild will occur again
+(forks inherit images from the main repo, but MRs don't propagate
+images from the fork into the main repo's registry).
+
+Building locally using CI docker images
+---------------------------------------
+
+It can be frustrating to debug build failures on an environment you
+don't personally have.  If you're experiencing this with the CI
+builds, you can use Docker to use their build environment locally.  Go
+to your job log, and at the top you'll see a line like::
+
+    Pulling docker image registry.freedesktop.org/anholt/mesa/debian/android_build:2020-09-11
+
+We'll use a volume mount to make our current Mesa tree be what the
+Docker container uses, so they'll share everything (their build will
+go in _build, according to ``meson-build.sh``).  We're going to be
+using the image non-interactively so we use ``run --rm $IMAGE
+command`` instead of ``run -it $IMAGE bash`` (which you may also find
+useful for debug).  Extract your build setup variables from
+.gitlab-ci.yml and run the CI meson build script:
+
+.. code-block:: console
+
+    IMAGE=registry.freedesktop.org/anholt/mesa/debian/android_build:2020-09-11
+    sudo docker pull $IMAGE
+    sudo docker run --rm -v `pwd`:/mesa -w /mesa $IMAGE env PKG_CONFIG_PATH=/usr/local/lib/aarch64-linux-android/pkgconfig/:/android-ndk-r21d/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/pkgconfig/ GALLIUM_DRIVERS=freedreno UNWIND=disabled EXTRA_OPTION="-D android-stub=true -D llvm=disabled" DRI_LOADERS="-D glx=disabled -D gbm=disabled -D egl=enabled -D platforms=android" CROSS=aarch64-linux-android ./.gitlab-ci/meson-build.sh
+
+All you have left over from the build is its output, and a _build
+directory.  You can hack on mesa and iterate testing the build with:
+
+.. code-block:: console
+
+    sudo docker run --rm -v `pwd`:/mesa $IMAGE ninja -C /mesa/_build

mesa 3D driver/docs/ci/uri-caching.conf

@@ -0,0 +1,35 @@
+set $authorization '';
+
+set_by_lua $proxyuri '
+        unescaped =  ngx.unescape_uri(ngx.var.arg_uri);
+        it, err = ngx.re.match(unescaped, "(https?://)(.*@)?([^/]*)(/.*)?");
+        if not it then
+                -- Hack to cause nginx to return 404
+                return "http://localhost/404"
+        end
+
+        scheme = it[1];
+        authstring = it[2];
+        host = it[3];
+        query = it[4];
+
+        if authstring then
+                auth = string.sub(authstring, 0, -2);
+                auth64 = ngx.encode_base64(auth);
+                ngx.var.authorization = "Basic " .. auth64;
+        end
+
+        -- Default to / if none is set to avoid using the request_uri query
+        if not query then
+                query = "/";
+        end
+
+        return scheme .. host .. query;
+';
+
+add_header X-GG-Cache-Status $upstream_cache_status;
+proxy_set_header Authorization $authorization;
+
+proxy_pass $proxyuri;
+# Redirect back to ourselves on 301 replies
+proxy_redirect ~^(.*)$ /cache/?uri=$1;

mesa 3D driver/docs/codingstyle.rst

@@ -0,0 +1,132 @@
+Coding Style
+============
+
+Mesa is over 20 years old and the coding style has evolved over time.
+Some old parts use a style that's a bit out of date. Different sections
+of mesa can use different coding style as set in the local EditorConfig
+(.editorconfig) and/or Emacs (.dir-locals.el) file. Alternatively the
+following is applicable. If the guidelines below don't cover something,
+try following the format of existing, neighboring code.
+
+Basic formatting guidelines
+
+-  3-space indentation, no tabs.
+-  Limit lines to 78 or fewer characters. The idea is to prevent line
+   wrapping in 80-column editors and terminals. There are exceptions,
+   such as if you're defining a large, static table of information.
+-  Opening braces go on the same line as the if/for/while statement. For
+   example:
+
+   .. code-block:: c
+
+      if (condition) {
+         foo;
+      } else {
+         bar;
+      }
+
+-  Put a space before/after operators. For example, ``a = b + c;`` and
+   not ``a=b+c;``
+-  This GNU indent command generally does the right thing for
+   formatting:
+
+   .. code-block:: console
+
+      indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
+
+-  Use comments wherever you think it would be helpful for other
+   developers. Several specific cases and style examples follow. Note
+   that we roughly follow `Doxygen <http://www.doxygen.nl>`__
+   conventions.
+
+   Single-line comments:
+
+   .. code-block:: c
+
+      /* null-out pointer to prevent dangling reference below */
+      bufferObj = NULL;
+
+   Or,
+
+   .. code-block:: c
+
+      bufferObj = NULL;  /* prevent dangling reference below */
+
+   Multi-line comment:
+
+   .. code-block:: c
+
+      /* If this is a new buffer object id, or one which was generated but
+       * never used before, allocate a buffer object now.
+       */
+
+   We try to quote the OpenGL specification where prudent:
+
+   .. code-block:: c
+
+      /* Page 38 of the PDF of the OpenGL ES 3.0 spec says:
+       *
+       *     "An INVALID_OPERATION error is generated for any of the following
+       *     conditions:
+       *
+       *     * <length> is zero."
+       *
+       * Additionally, page 94 of the PDF of the OpenGL 4.5 core spec
+       * (30.10.2014) also says this, so it's no longer allowed for desktop GL,
+       * either.
+       */
+
+   Function comment example:
+
+   .. code-block:: c
+
+      /**
+       * Create and initialize a new buffer object.  Called via the
+       * ctx->Driver.CreateObject() driver callback function.
+       * \param  name  integer name of the object
+       * \param  type  one of GL_FOO, GL_BAR, etc.
+       * \return  pointer to new object or NULL if error
+       */
+      struct gl_object *
+      _mesa_create_object(GLuint name, GLenum type)
+      {
+         /* function body */
+      }
+
+-  Put the function return type and qualifiers on one line and the
+   function name and parameters on the next, as seen above. This makes
+   it easy to use ``grep ^function_name dir/*`` to find function
+   definitions. Also, the opening brace goes on the next line by itself
+   (see above.)
+-  Function names follow various conventions depending on the type of
+   function:
+
+   +---------------------+------------------------------------------+
+   | Convention          | Explanation                              |
+   +=====================+==========================================+
+   | ``glFooBar()``      | a public GL entry point (in              |
+   |                     | :file:`glapi_dispatch.c`)                |
+   +---------------------+------------------------------------------+
+   | ``_mesa_FooBar()``  | the internal immediate mode function     |
+   +---------------------+------------------------------------------+
+   | ``save_FooBar()``   | retained mode (display list) function in |
+   |                     | :file:`dlist.c`                          |
+   +---------------------+------------------------------------------+
+   | ``foo_bar()``       | a static (private) function              |
+   +---------------------+------------------------------------------+
+   | ``_mesa_foo_bar()`` | an internal non-static Mesa function     |
+   +---------------------+------------------------------------------+
+
+-  Constants, macros and enum names are ``ALL_UPPERCASE``, with \_
+   between words.
+-  Mesa usually uses camel case for local variables (Ex:
+   ``localVarname``) while Gallium typically uses underscores (Ex:
+   ``local_var_name``).
+-  Global variables are almost never used because Mesa should be
+   thread-safe.
+-  Booleans. Places that are not directly visible to the GL API should
+   prefer the use of ``bool``, ``true``, and ``false`` over
+   ``GLboolean``, ``GL_TRUE``, and ``GL_FALSE``. In C code, this may
+   mean that ``#include <stdbool.h>`` needs to be added. The
+   ``try_emit_*`` methods in ``src/mesa/program/ir_to_mesa.cpp`` and
+   ``src/mesa/state_tracker/st_glsl_to_tgsi.cpp`` can serve as examples.

mesa 3D driver/docs/conf.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import sphinx_rtd_theme
+
+#
+# The Mesa 3D Graphics Library documentation build configuration file, created by
+# sphinx-quickstart on Wed Mar 29 14:08:51 2017.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(os.path.abspath('_exts'))
+
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.graphviz', 'formatting', 'redirects']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'The Mesa 3D Graphics Library'
+copyright = '1995-2018, Brian Paul'
+author = 'Brian Paul'
+html_show_copyright = False
+
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = 'latest'
+# The full version, including alpha/beta/rc tags.
+release = 'latest'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# Disable highlighting unless a language is specified, otherwise we'll get
+# python keywords highlit in literal blocks.
+highlight_language = "none"
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+html_favicon = "favicon.ico"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+html_theme_options = {
+  'display_version': False,
+}
+
+html_context = {
+  'display_gitlab': True,
+  'gitlab_host': 'gitlab.freedesktop.org',
+  'gitlab_user': 'mesa',
+  'gitlab_repo': 'mesa',
+  'gitlab_version': 'master',
+  'conf_py_path': '/docs/',
+}
+
+html_copy_source = False
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+html_extra_path = [
+  '_extra/',
+  'release-maintainers-keys.asc',
+  'features.txt',
+  'libGL.txt',
+  'README.UVD',
+  'README.VCE',
+]
+
+html_redirects = [
+  ('gallium/drivers/freedreno', 'drivers/freedreno.html'),
+  ('gallium/drivers/freedreno/ir3-notes', 'drivers/freedreno/ir3-notes.html'),
+  ('gallium/drivers/llvmpipe', 'drivers/llvmpipe.html'),
+  ('gallium/drivers/openswr', 'drivers/openswr.html'),
+  ('gallium/drivers/openswr/faq', 'drivers/openswr/faq.html'),
+  ('gallium/drivers/openswr/knobs', 'drivers/openswr/knobs.html'),
+  ('gallium/drivers/openswr/profiling', 'drivers/openswr/profiling.html'),
+  ('gallium/drivers/openswr/usage', 'drivers/openswr/usage.html'),
+  ('gallium/drivers/zink', 'drivers/zink.html'),
+  ('llvmpipe', 'drivers/llvmpipe.html'),
+  ('postprocess', 'gallium/postprocess.html'),
+  ('versions', 'relnotes.html'),
+  ('vmware-guest', 'drivers/vmware-guest.html'),
+  ('webmaster', 'https://www.mesa3d.org/website/'),
+]
+
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'TheMesa3DGraphicsLibrarydoc'
+
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'TheMesa3DGraphicsLibrary.tex', 'The Mesa 3D Graphics Library Documentation',
+     'Brian Paul', 'manual'),
+]
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'themesa3dgraphicslibrary', 'The Mesa 3D Graphics Library Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'TheMesa3DGraphicsLibrary', 'The Mesa 3D Graphics Library Documentation',
+     author, 'TheMesa3DGraphicsLibrary', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# -- Options for Graphviz -------------------------------------------------
+
+graphviz_output_format = 'svg'

mesa 3D driver/docs/conform.rst

@@ -0,0 +1,26 @@
+Conformance Testing
+===================
+
+Mesa as a project does not get certified conformant by Khronos for the
+APIs it implements.  Rather, individual driver teams run the
+conformance tests and submit their results on a set of hardware on a
+particular operating system.  The canonical list is at Khronos' list
+of `conformant
+products <https://www.khronos.org/conformance/adopters/conformant-products/>`_
+and you can find some reports there by searching for "Mesa",
+"Raspbian" and "RADV" for example.
+
+Submitting conformance results to Khronos
+-----------------------------------------
+
+If your driver team is associated with an organization that is a
+Khronos member and has submitted conformance for your API on another
+software stack (likely you're a hardware company), it will probably be
+easiest to submit your conformance through them.
+
+If you are an individual developer or your organization hasn't
+submitted results for the given API yet, X.Org is a member through
+Software in the Public Interest, and they can help submit your
+conformance results to get added to the list of conformant products.
+You should probably coordinate with board@foundation.x.org for your
+first submission.

mesa 3D driver/docs/debugging.rst

@@ -0,0 +1,17 @@
+Debugging Tips
+==============
+
+Normally Mesa (and OpenGL) records but does not notify the user of
+errors. It is up to the application to call ``glGetError`` to check for
+errors. Mesa supports an environment variable, ``MESA_DEBUG``, to help
+with debugging. If ``MESA_DEBUG`` is defined, a message will be printed
+to stdout whenever an error occurs.
+
+More extensive error checking is done in DEBUG builds
+(``--buildtype debug`` for Meson).
+
+In your debugger you can set a breakpoint in ``_mesa_error()`` to trap
+Mesa errors.
+
+There is a display list printing/debugging facility. See the end of
+``src/dlist.c`` for details.

mesa 3D driver/docs/developers.rst

@@ -0,0 +1,25 @@
+Developers
+==========
+
+Both professional and volunteer developers contribute to Mesa.
+
+`VMware <https://www.vmware.com/>`__ employs several of the main Mesa
+developers including Brian Paul and Keith Whitwell.
+
+In the past, Tungsten Graphics contracts implemented many Mesa features
+including:
+
+-  DRI drivers for Intel i965, i945, i915 and other chips
+-  Advanced memory manager and framebuffer object support
+-  Shading language compiler and OpenGL 2.0 support
+-  MiniGLX environment
+
+Other companies including `Intel <https://01.org/linuxgraphics>`__ and
+RedHat also actively contribute to the project. Intel has recently
+contributed the new GLSL compiler in Mesa 7.9.
+
+`LunarG <https://www.lunarg.com/>`__ can be contacted for custom Mesa /
+3D graphics development.
+
+Volunteers have made significant contributions to all parts of Mesa,
+including complete device drivers.

mesa 3D driver/docs/devinfo.rst

@@ -0,0 +1,40 @@
+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/mapi/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 ``mtypes.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``.
+-  The dispatch tests ``check_table.cpp`` and ``dispatch_sanity.cpp``
+   should be updated with details about the new extensions functions.
+   These tests are run using ``meson test``.

mesa 3D driver/docs/dispatch.rst

@@ -0,0 +1,257 @@
+GL Dispatch
+===========
+
+Several factors combine to make efficient dispatch of OpenGL functions
+fairly complicated. This document attempts to explain some of the issues
+and introduce the reader to Mesa's implementation. Readers already
+familiar with the issues around GL dispatch can safely skip ahead to the
+:ref:`overview of Mesa's implementation <overview>`.
+
+1. Complexity of GL Dispatch
+----------------------------
+
+Every GL application has at least one object called a GL *context*. This
+object, which is an implicit parameter to every GL function, stores all
+of the GL related state for the application. Every texture, every buffer
+object, every enable, and much, much more is stored in the context.
+Since an application can have more than one context, the context to be
+used is selected by a window-system dependent function such as
+``glXMakeContextCurrent``.
+
+In environments that implement OpenGL with X-Windows using GLX, every GL
+function, including the pointers returned by ``glXGetProcAddress``, are
+*context independent*. This means that no matter what context is
+currently active, the same ``glVertex3fv`` function is used.
+
+This creates the first bit of dispatch complexity. An application can
+have two GL contexts. One context is a direct rendering context where
+function calls are routed directly to a driver loaded within the
+application's address space. The other context is an indirect rendering
+context where function calls are converted to GLX protocol and sent to a
+server. The same ``glVertex3fv`` has to do the right thing depending on
+which context is current.
+
+Highly optimized drivers or GLX protocol implementations may want to
+change the behavior of GL functions depending on current state. For
+example, ``glFogCoordf`` may operate differently depending on whether or
+not fog is enabled.
+
+In multi-threaded environments, it is possible for each thread to have a
+different GL context current. This means that poor old ``glVertex3fv``
+has to know which GL context is current in the thread where it is being
+called.
+
+.. _overview:
+
+2. Overview of Mesa's Implementation
+------------------------------------
+
+Mesa uses two per-thread pointers. The first pointer stores the address
+of the context current in the thread, and the second pointer stores the
+address of the *dispatch table* associated with that context. The
+dispatch table stores pointers to functions that actually implement
+specific GL functions. Each time a new context is made current in a
+thread, these pointers are updated.
+
+The implementation of functions such as ``glVertex3fv`` becomes
+conceptually simple:
+
+-  Fetch the current dispatch table pointer.
+-  Fetch the pointer to the real ``glVertex3fv`` function from the
+   table.
+-  Call the real function.
+
+This can be implemented in just a few lines of C code. The file
+``src/mesa/glapi/glapitemp.h`` contains code very similar to this.
+
+.. code-block:: c
+   :caption: Sample dispatch function
+
+   void glVertex3f(GLfloat x, GLfloat y, GLfloat z)
+   {
+       const struct _glapi_table * const dispatch = GET_DISPATCH();
+
+       (*dispatch->Vertex3f)(x, y, z);
+   }
+
+The problem with this simple implementation is the large amount of
+overhead that it adds to every GL function call.
+
+In a multithreaded environment, a naive implementation of
+``GET_DISPATCH`` involves a call to ``pthread_getspecific`` or a similar
+function. Mesa provides a wrapper function called
+``_glapi_get_dispatch`` that is used by default.
+
+3. Optimizations
+----------------
+
+A number of optimizations have been made over the years to diminish the
+performance hit imposed by GL dispatch. This section describes these
+optimizations. The benefits of each optimization and the situations
+where each can or cannot be used are listed.
+
+3.1. Dual dispatch table pointers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The vast majority of OpenGL applications use the API in a single
+threaded manner. That is, the application has only one thread that makes
+calls into the GL. In these cases, not only do the calls to
+``pthread_getspecific`` hurt performance, but they are completely
+unnecessary! It is possible to detect this common case and avoid these
+calls.
+
+Each time a new dispatch table is set, Mesa examines and records the ID
+of the executing thread. If the same thread ID is always seen, Mesa
+knows that the application is, from OpenGL's point of view, single
+threaded.
+
+As long as an application is single threaded, Mesa stores a pointer to
+the dispatch table in a global variable called ``_glapi_Dispatch``. The
+pointer is also stored in a per-thread location via
+``pthread_setspecific``. When Mesa detects that an application has
+become multithreaded, ``NULL`` is stored in ``_glapi_Dispatch``.
+
+Using this simple mechanism the dispatch functions can detect the
+multithreaded case by comparing ``_glapi_Dispatch`` to ``NULL``. The
+resulting implementation of ``GET_DISPATCH`` is slightly more complex,
+but it avoids the expensive ``pthread_getspecific`` call in the common
+case.
+
+.. code-block:: c
+   :caption: Improved ``GET_DISPATCH`` Implementation
+
+   #define GET_DISPATCH() \
+       (_glapi_Dispatch != NULL) \
+           ? _glapi_Dispatch : pthread_getspecific(&_glapi_Dispatch_key)
+
+3.2. ELF TLS
+~~~~~~~~~~~~
+
+Starting with the 2.4.20 Linux kernel, each thread is allocated an area
+of per-thread, global storage. Variables can be put in this area using
+some extensions to GCC. By storing the dispatch table pointer in this
+area, the expensive call to ``pthread_getspecific`` and the test of
+``_glapi_Dispatch`` can be avoided.
+
+The dispatch table pointer is stored in a new variable called
+``_glapi_tls_Dispatch``. A new variable name is used so that a single
+libGL can implement both interfaces. This allows the libGL to operate
+with direct rendering drivers that use either interface. Once the
+pointer is properly declared, ``GET_DISPACH`` becomes a simple variable
+reference.
+
+.. code-block:: c
+   :caption: TLS ``GET_DISPATCH`` Implementation
+
+   extern __thread struct _glapi_table *_glapi_tls_Dispatch
+       __attribute__((tls_model("initial-exec")));
+
+   #define GET_DISPATCH() _glapi_tls_Dispatch
+
+Use of this path is controlled by the preprocessor define
+``USE_ELF_TLS``. Any platform capable of using ELF TLS should use this
+as the default dispatch method.
+
+Windows has a similar concept, and beginning with Windows Vista, shared
+libraries can take advantage of compiler-assisted TLS. This TLS data
+has no fixed size and does not compete with API-based TLS (``TlsAlloc``)
+for the limited number of slots available there, and so ``USE_ELF_TLS`` can
+be used on Windows too, even though it's not truly ELF.
+
+3.3. Assembly Language Dispatch Stubs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Many platforms have difficulty properly optimizing the tail-call in the
+dispatch stubs. Platforms like x86 that pass parameters on the stack
+seem to have even more difficulty optimizing these routines. All of the
+dispatch routines are very short, and it is trivial to create optimal
+assembly language versions. The amount of optimization provided by using
+assembly stubs varies from platform to platform and application to
+application. However, by using the assembly stubs, many platforms can
+use an additional space optimization (see :ref:`below <fixedsize>`).
+
+The biggest hurdle to creating assembly stubs is handling the various
+ways that the dispatch table pointer can be accessed. There are four
+different methods that can be used:
+
+#. Using ``_glapi_Dispatch`` directly in builds for non-multithreaded
+   environments.
+#. Using ``_glapi_Dispatch`` and ``_glapi_get_dispatch`` in
+   multithreaded environments.
+#. Using ``_glapi_Dispatch`` and ``pthread_getspecific`` in
+   multithreaded environments.
+#. Using ``_glapi_tls_Dispatch`` directly in TLS enabled multithreaded
+   environments.
+
+People wishing to implement assembly stubs for new platforms should
+focus on #4 if the new platform supports TLS. Otherwise, implement #2
+followed by #3. Environments that do not support multithreading are
+uncommon and not terribly relevant.
+
+Selection of the dispatch table pointer access method is controlled by a
+few preprocessor defines.
+
+-  If ``USE_ELF_TLS`` is defined, method #3 is used.
+-  If ``HAVE_PTHREAD`` is defined, method #2 is used.
+-  If none of the preceding are defined, method #1 is used.
+
+Two different techniques are used to handle the various different cases.
+On x86 and SPARC, a macro called ``GL_STUB`` is used. In the preamble of
+the assembly source file different implementations of the macro are
+selected based on the defined preprocessor variables. The assembly code
+then consists of a series of invocations of the macros such as:
+
+.. code-block:: c
+   :caption: SPARC Assembly Implementation of ``glColor3fv``
+
+   GL_STUB(Color3fv, _gloffset_Color3fv)
+
+The benefit of this technique is that changes to the calling pattern
+(i.e., addition of a new dispatch table pointer access method) require
+fewer changed lines in the assembly code.
+
+However, this technique can only be used on platforms where the function
+implementation does not change based on the parameters passed to the
+function. For example, since x86 passes all parameters on the stack, no
+additional code is needed to save and restore function parameters around
+a call to ``pthread_getspecific``. Since x86-64 passes parameters in
+registers, varying amounts of code needs to be inserted around the call
+to ``pthread_getspecific`` to save and restore the GL function's
+parameters.
+
+The other technique, used by platforms like x86-64 that cannot use the
+first technique, is to insert ``#ifdef`` within the assembly
+implementation of each function. This makes the assembly file
+considerably larger (e.g., 29,332 lines for ``glapi_x86-64.S`` versus
+1,155 lines for ``glapi_x86.S``) and causes simple changes to the
+function implementation to generate many lines of diffs. Since the
+assembly files are typically generated by scripts, this isn't a
+significant problem.
+
+Once a new assembly file is created, it must be inserted in the build
+system. There are two steps to this. The file must first be added to
+``src/mesa/sources``. That gets the file built and linked. The second
+step is to add the correct ``#ifdef`` magic to
+``src/mesa/glapi/glapi_dispatch.c`` to prevent the C version of the
+dispatch functions from being built.
+
+.. _fixedsize:
+
+3.4. Fixed-Length Dispatch Stubs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To implement ``glXGetProcAddress``, Mesa stores a table that associates
+function names with pointers to those functions. This table is stored in
+``src/mesa/glapi/glprocs.h``. For different reasons on different
+platforms, storing all of those pointers is inefficient. On most
+platforms, including all known platforms that support TLS, we can avoid
+this added overhead.
+
+If the assembly stubs are all the same size, the pointer need not be
+stored for every function. The location of the function can instead be
+calculated by multiplying the size of the dispatch stub by the offset of
+the function in the table. This value is then added to the address of
+the first dispatch stub.
+
+This path is activated by adding the correct ``#ifdef`` magic to
+``src/mesa/glapi/glapi.c`` just before ``glprocs.h`` is included.

mesa 3D driver/docs/download.rst

@@ -0,0 +1,64 @@
+Downloading and Unpacking
+=========================
+
+Downloading
+-----------
+
+You can download the released versions of Mesa via
+`HTTPS <https://mesa.freedesktop.org/archive/>`__ or
+`FTP <ftp://ftp.freedesktop.org/pub/mesa/>`__.
+
+Our release tarballs are GPG-signed, and the public keys are available
+here: `release-maintainers-keys.asc <release-maintainers-keys.asc>`__.
+
+Starting with the first release of 2017, Mesa's version scheme is
+year-based. Filenames are in the form ``mesa-Y.N.P.tar.gz``, where ``Y``
+is the year (two digits), ``N`` is an incremental number (starting at 0)
+and ``P`` is the patch number (0 for the first release, 1 for the first
+patch after that).
+
+When a new release is coming, release candidates (betas) may be found in
+the same directory, and are recognizable by the
+``mesa-Y.N.P-rcX.tar.gz`` filename.
+
+Unpacking
+---------
+
+Mesa releases are available in two formats: ``.tar.xz`` and ``.tar.gz``.
+
+To unpack the tarball:
+
+.. code-block:: console
+
+      tar xf mesa-Y.N.P.tar.xz
+
+or
+
+.. code-block:: console
+
+      tar xf mesa-Y.N.P.tar.gz
+
+Contents
+--------
+
+Proceed to the :doc:`compilation and installation
+instructions <install>`.
+
+Demos, GLUT, and GLU
+--------------------
+
+A package of SGI's GLU library is available
+`here <ftp://ftp.freedesktop.org/pub/mesa/glu/>`__
+
+A package of Mark Kilgard's GLUT library is available
+`here <ftp://ftp.freedesktop.org/pub/mesa/glut/>`__
+
+The Mesa demos collection is available
+`here <ftp://ftp.freedesktop.org/pub/mesa/demos/>`__
+
+In the past, GLUT, GLU and the Mesa demos were released in conjunction
+with Mesa releases. But since GLUT, GLU and the demos change
+infrequently, they were split off into their own Git repositories:
+`GLUT <https://gitlab.freedesktop.org/mesa/glut>`__,
+`GLU <https://gitlab.freedesktop.org/mesa/glu>`__ and
+`Demos <https://gitlab.freedesktop.org/mesa/demos>`__,

mesa 3D driver/docs/drivers/d3d12.rst

@@ -0,0 +1,49 @@
+D3D12
+=====
+
+Overview
+--------
+
+The D3D12 driver is a Gallium driver that emits API calls for Microsoft's
+:abbr:`D3D12 (Direct3D 12)` API instead of targeting a specific GPU
+architecture. This can be used to get full desktop OpenGL 3.3 support on
+devices that only support D3D12.
+
+Debugging
+---------
+
+There's a few tools that are useful for debugging D3D12, such as these
+environment variables:
+
+.. envvar:: D3D12_DEBUG <flags> ("")
+
+``verbose``
+   Enable verbose output to stdout
+``blit``
+   Trace blit and copy resource calls
+``experimental``
+   Enable experimental shader models feature
+``dxil``
+   Dump DXIL during program compile
+``disass``
+   Dump disassambly of created DXIL shader
+``res``
+   Debug resources
+``debuglayer``
+   Enable `debug layer`_
+``gpuvalidator``
+   Enable `GPU validator`_
+
+.. envvar:: DXIL_DEBUG <flags> ("")
+
+``verbose``
+   Enable verbose output to stdout
+``dump_blob``
+   Write shader blobs
+``trace``
+   Trace instruction conversion
+``dump_module``
+   dump module tree to stderr
+
+.. _debug layer: https://docs.microsoft.com/en-us/windows/win32/direct3d12/understanding-the-d3d12-debug-layer
+.. _GPU validator: https://docs.microsoft.com/en-us/windows/win32/direct3d12/using-d3d12-debug-layer-gpu-based-validation

mesa 3D driver/docs/drivers/freedreno.rst

@@ -0,0 +1,9 @@
+Freedreno
+=========
+
+Freedreno driver specific docs.
+
+.. toctree::
+   :glob:
+
+   freedreno/*