Prepare for move to hardware/google/gfxstream

Move codegen into what will become
hardware/google/gfxstream/codegen/vulkan
and move generated vulkan headers into what will become
hardware/google/gfxstream/common/vulkan.

Bug: 271464937
Test: presubmit
Test: python android/build/python/cmake.py --gfxstream
Change-Id: Ie0465ac72b4a2f7444b595cd1421e2e3cb1d0997

1 files changed, 381 insertions, 0 deletions

diff --git a/codegen/vulkan/styleguide.txt b/codegen/vulkan/styleguide.txt
new file mode 100644
index 00000000..3c1a8dd6
--- /dev/null
+++ b/codegen/vulkan/styleguide.txt
@@ -0,0 +1,381 @@
+// Copyright 2014-2021 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Vulkan^®^ Documentation and Extensions: Procedures and Conventions
+Jon Leech, Tobias Hector
+:data-uri:
+:icons: font
+:toc2:
+:toclevels: 3
+:numbered:
+:source-highlighter: rouge
+:rouge-style: github
+:doctype: book
+:imagewidth: 800
+:fullimagewidth: width="800"
+:cl: :
+
+// Various special / math symbols. This is easier to edit with than Unicode.
+include::{config}/attribs.txt[]
+
+// Where the current Asciidoctor documentation is found.
+:docguide: https://docs.asciidoctor.org/asciidoc/latest
+
+:leveloffset: 1
+
+<<<<
+
+include::{config}/copyright-ccby.txt[]
+
+<<<<
+
+[[introduction]]
+= Introduction
+
+This document contains required procedures and conventions when writing
+specifications for new Vulkan APIs, extensions and layers, or related
+Khronos^{reg}^ documentation such as white papers and tutorials; or
+contributing to existing Vulkan specifications.
+These are collectively referred to as _Vulkan Documentation_ or just
+_documentation_ below.
+The primary focus is the API Specification and API extensions, although all
+of the markup and most of the writing style is equally applicable to other
+documentation.
+
+The primary purpose is to achieve consistency across the API, as well as
+across all of our source and output documents.
+Consistency makes it easier for developers, editors, reviewers, and users of
+our documentation to understand and modify it.
+
+This document is now formally voted on and approved by the Vulkan Working
+Group.
+This means that unless explicitly stated otherwise, the procedures and
+conventions must be followed.
+If you have a strong desire to modify the procedures and conventions, such
+changes must be made through the normal Vulkan Working Group processes.
+
+
+[[introduction-terminology]]
+== Terminology
+
+The key words *must*, *required*, *should*, *recommend*, *may*, and
+*optional* in this document are to be interpreted as described in RFC 2119
+and by the Vulkan Specification in the "`Terminology`" section.
+
+
+[[introduction-structure]]
+== Document Structure
+
+The style guide is broken into four sections:
+
+  * <<naming,API Naming Conventions>> - the required rules for choosing
+    names of Vulkan identifiers of all types.
+  * <<extensions,Extensions and Layers>> - the required procedures for
+    creating formal Vulkan extensions and layers.
+  * <<markup,Markup Style>> - the required and recommended markup style for
+    writing asciidoctor and XML source that follows consistent formatting
+    and layout guidelines, tags special terms and phrases for proper
+    processing by the spec generation tools, etc.
+  * <<writing,Writing Style>> - the required and recommended writing style
+    for overall and fine-grained structure and conventions, normative
+    language use, API naming conventions, common words and phrases to use
+    and to avoid, linking and cross-referencing, etc.
+
+
+[[introduction-asciidoc]]
+== Asciidoctor Markup
+
+Vulkan Documentation is primarily written in Asciidoctor, a text markup
+language.
+We use the command-line asciidoctor client that is actively maintained by
+asciidoctor, which is documented on its website at https://asciidoctor.org.
+
+References to the Asciidoctor User Manual are to sections in the document at
+https://asciidoctor.org/docs/user-manual/.
+
+Asciidoctor is implemented in Ruby (https://www.ruby-lang.org/), which is
+available for Linux, MacOS, and Microsoft Windows.
+
+[NOTE]
+.Note
+====
+There are other implementations of asciidoctor, such as AsciidoctorJ
+(https://github.com/asciidoctor/asciidoctorj) and asciidoctor.js
+(https://github.com/asciidoctor/asciidoctor.js).
+In particular, GitHub and GitLab both have preview renderers for .adoc or
+.asciidoc files in repositories, and live preview extensions exist for
+Chrome and Firefox.
+
+However, because of the use of custom Ruby macros in the Vulkan
+Specification toolchain, and the high complexity of the documents and
+toolchain used to generate it, these web tools cannot currently render the
+Specification from source.
+Instead, we generate HTML and PDF versions of the Specification and publish
+them on the Khronos website.
+
+The Asciidoctor toolchain and build process are not addressed by this
+document, which concentrates solely on source documents.
+====
+
+
+[[introduction-normative]]
+== Normative References
+
+Normative references are references to external documents or resources to
+which documentation authors must comply.
+
+[[acm-references]]
+Association for Computing Machinery.
+_Citation Style and Reference Formats_.
+Retrieved July 27, 2019.
+https://www.acm.org/publications/authors/reference-formatting .
+
+[[iso-8601]]
+International Organization for Standardization.
+_Data elements and interchange formats -- Information interchange --
+Representation of dates and times_ (2004-12-01).
+https://www.iso.org/standard/40874.html .
+Also see https://www.w3.org/QA/Tips/iso-date for colloquial examples.
+
+[[vulkan-docs]]
+Khronos Vulkan Working Group.
+`KhronosGroup/Vulkan-Docs` project on GitHub (July 5, 2016).
+https://github.com/KhronosGroup/Vulkan-Docs .
+
+[[vulkan-spec]]
+Khronos Vulkan Working Group.
+_Vulkan 1.1.116 - A Specification_ (July 20, 2019).
+https://www.khronos.org/registry/vulkan/ .
+
+Version 1.1.116 is the latest patch release of the Vulkan API Specification
+as of the time this reference was created, but that Specification is
+frequently updated with minor bugfixes and clarifications.
+When a more recent patch release is made, it becomes the normative reference
+for the API.
+
+
+// Chapters of the text are included below
+
+include::style/naming.txt[]
+
+include::style/extensions.txt[]
+
+include::style/markup.txt[]
+
+include::style/writing.txt[]
+
+include::style/misc.txt[]
+
+// Appendices are included below
+include::style/vuid.txt[]
+
+
+= Revision History
+
+* 2021-11-04 - Remove backquote markup around recommended use of the
+  `apiext:` macro, since that macro now styles the extension name argument
+  itself.
+* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound
+  Words and Preferred Orthography>> section.
+* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for
+  New Extensions>> section to require use of the `apiext:` macro for links
+  to extension names (internal issue 2831).
+* 2021-09-12 - Add a new subsection with more details on using
+  tilde-delimited source blocks <<markup-blocks-source, inside reference
+  page open blocks>>, and rewrite the <<sample-command, Sample Command
+  Description>> section to follow current phrasing and markup patterns
+  (internal issue 2040).
+* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized
+  Enumerant Names>> section to clarify how to write wildcard enumerant names
+  with imbedded italicized text.
+* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>>
+  section based on the Khronos Inclusive Language list (internal issue
+  2293).
+* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound
+  Words and Preferred Orthography>> section (internal merge request 4794).
+* 2021-07-20 - Add additional contraction examples to the table in the
+  <<markup-avoid-contractions, Avoid Abbreviations and Contractions>>
+  section.
+* 2021-05-31 - Add "`implementation-dependent`" as an exception in the
+  <<writing-compound-words, Compound Words and Preferred Orthography>>
+  section (internal merge request 4611).
+* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few
+  places where markup examples are given.
+* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to
+  include avoiding abbreviations, as well as contractions.
+* 2021-05-07 - Add <<markup-word-choices, preferred way to write
+  "`drawing/dispatching command">>.
+* 2021-04-28 - Add <<markup-word-choices, disambiguations for
+  "`executable`">>.
+* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and
+  handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively
+  (internal issue 2662).
+* 2021-04-14 - Add "`side effect`" and "`reuse`" as
+  <<writing-compound-words, preferred orthography>> (public issue 1484).
+* 2021-03-31 - Update description of the code{cl} macro in the
+  <<markup-macros-api, API Markup Macros>> section to match current
+  behavior.
+* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit
+  should be reserved>> for the same purpose in comparable 32- and 64-bit
+  bitmask types (internal issue 2565).
+* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and
+  Notes>> section to track actual usage and update the description of the
+  undefined{cl} macro to further clarify its purpose and uses (internal
+  issue 2195).
+* 2020-08-16 - Add "`reference monitor`" to the preferred
+  <<markup-word-choices, Word Choices>> (internal issue 2291).
+* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return
+  Error Codes>> section to guide authors of new commands (internal issue
+  2290).
+* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section
+  describing how to properly attribute this information.
+* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for
+  New Extensions>> section to recommend placing most extension language
+  inline in existing specification source files, rather than in separate
+  files, and to base extension revision numbers at `1` starting with initial
+  public release (public issue 1263).
+* 2020-04-29 - Expand use of `basetype` macros to include external API
+  types.
+* 2020-03-16 - Add documentation of writing links to extension appendices in
+  the <<extensions-documenting-extensions, Changes for New Extensions>>
+  section and document the apiext{cl} and reflink{cl} macros in the
+  <<markup-macros-api, API Markup Macros>> section.
+  Improve documentation of writing <<writing-refpages, Markup For Automatic
+  Reference Page Extraction>> including how to mark up content in the
+  Specification source so it only appears in generated reference pages;
+  however, this section is still out of date (internal issue 1999).
+* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>>
+  section that a valid usage statement must be defined at the place (command
+  or structure specification) that all information need to evaluate the
+  statement is known.
+  Update the description of <<appendix-vuid-creating, Creating VUID tags>>
+  to match the current scripts.
+  Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere.
+  Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the
+  Specification can only be built using the command-line asciidoctor client,
+  not by asciidoctor web clients.
+* 2020-02-22 - Document that it is no longer needed to escape C arrows in
+  macros.
+* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime
+  Symbols>> (internal issue 1110).
+* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension
+  Structure Chains>> section and make all spec language consistent with it
+  (internal issue 1814).
+* 2019-09-09 - Define markup for nested structure members in the
+  <<markup-macros-api, API Markup Macros>> section (internal issue 1765).
+* 2019-09-08 - Add language to the end of the
+  <<extensions-documenting-extensions, Changes for New Extensions>> section
+  describing how to mark up asciidoctor conditionals (internal issue 1808).
+* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of
+  Equations>> section (internal issue 1793).
+* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping
+  Related Language>> section (internal issue 979) and the
+  <<markup-minimize-indentation, Minimize Indentation>> section (internal
+  issue 747).
+  Disallow use of standalone `+` except in latexmath and source blocks, in
+  the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal
+  issue 736).
+* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and
+  Instances>> section (internal issue 1553).
+* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID
+  Tags>> appendix specifying allowed characters in VUID tags (based on
+  discussion for internal merge request 3239).
+* 2019-07-27 - Add the <<writing-references, References>> section and
+  rewrite external references accordingly.
+* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new
+  flags and bitmask types>> (internal issue 1649).
+* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values,
+  Reserving Bitmask Values>> (internal issue 1411).
+* 2018-11-19 - Add details to the <<extensions-documenting-extensions,
+  Changes for New Extensions>> section including the new "`Description`"
+  section, and other standard parts of extension appendices.
+* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images,
+  Figures>> section (public pull request 734).
+* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined
+  Behavior>> (as part of the fixes for public issue 379), and describing why
+  the undefined{cl} macro should always be used.
+* 2018-07-08 - Remove requirement to explicitly include extension appendices
+  in the <<extensions-documenting-extensions, Changes for New Extensions>>
+  section.
+* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a
+  Vendor ID with Khronos>> to define vendor ID values as part of an
+  enumerated type.
+* 2018-03-07 - Updated for Vulkan 1.1 release.
+* 2018-01-10 - Move details of mandated extension compatibility from the
+  <<extensions-rules, General Rules/Guidelines>> section into the
+  Fundamentals section of the API Specification, where they are changed
+  slightly to allow explicit incompatibilies (public issue 638).
+* 2017-10-27 - Add language about proper use of "`valid pointer`" and
+  "`pointer to valid object`" for valid usage statements, in the
+  <<sample-command, Sample Command Description>> section (related to public
+  pull request 547).
+* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells,
+  LaTeX Math in Table Cells>> (internal issue 908).
+* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX`
+  extensions>> (public issues 536, 580).
+* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and
+  `any`>> to refer to properties of elments of arrays (internal issue 884).
+* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and
+  Extension pname:pNext Chains>> language specifying where to describe
+  interactions of structures in a pname:pNext chain (internal issue 715).
+* 2017-09-10 - Add example of marking up an enumerated type all of whose
+  values are defined by extensions (internal issue 864).
+* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions,
+  and Layers>> chapter describing how to write new API versions (internal
+  issue 892).
+* 2017-06-12 - Add sections describing when to use the
+  <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text,
+  *text{cl}>> markup macros instead of the *link{cl} macros, and clarify
+  that slink{cl} should be used for handle as well as structure names
+  (internal issue 886).
+* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID
+  Tags>> and how they're generated.
+* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension
+  Structure Names>>.
+* 2017-02-11 - Finish transitioning to asciidoctor markup.
+* 2016-09-28 - Add asciidoc math markup guidelines.
+* 2016-09-16 - Make style guide markup more consistent with its own
+  recommendations.
+  Simplify some tables of preferred terms.
+  Add sections on block and table markup.
+* 2016-09-12 - Describe writing and markup style for labelled lists.
+  Require use of the ISO 8601 date format except in rare legacy cases.
+  Expand the description of <<markup-layout,Line Lengths>> and add a
+  description of markup for <<markup-footnotes,Footnotes>>.
+* 2016-09-08 - Add a writing section about proper use of
+  <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432).
+* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which
+  are no longer used in the Specification (internal issue 407).
+* 2016-08-29 - Add spelling and compound word rules (public issue 352).
+* 2016-08-23 - Modify description of specifying extensions in the
+  <<extensions,Layers and Extensions>> chapter to refer to the new
+  single-branch model for extensions (internal issue 397).
+* 2016-07-26 - Add section describing <<writing-refpages,markup for
+  automatic reference page extraction>>.
+* 2016-07-18 - Add examples of function-parameter and structure-member
+  markup (based on public issue 286).
+* 2016-07-11 - Change the document title.
+* 2016-07-07 - Rename document, change license to CC BY, clarify required
+  and recommended actions, and reserve use of "`normative`" for the
+  Specifications.
+* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the
+  Vulkan API Specification and merge content with the naming guide.
+  Put extension and naming chapters into their own source files.
+* 2016-06-20 - Add API naming guide.
+* 2016-05-22 - Add markup and image creation rules, after fixing missing
+  figure captions for public issue 219.
+* 2016-05-01 - Include feedback from public issues 120 and 190.
+  Use consistent conventions for defining structures.
+  Use American rather than British spelling conventions.
+* 2016-03-12 - Recommend against "the value of".
+* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not".
+* 2016-02-16 - Place asciidoc conversion post-release.
+* 2016-02-09 - Added quotation mark convention.
+* 2016-02-01 - Add the Oxford Comma section and issue resolution.
+* 2016-01-26 - Add bullet-list style description of command parameters.
+* 2016-01-11 - Add "`Numbers in Text`" section from WSI work.
+* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`".
+* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`".
+* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types.
+* 2015-12-10 - Initial release for feedback.