Attachment 343303 Details for Bug 186906 – WIP

[patch] WIP

bug-186906-20180621200001.patch (text/plain), 11.08 KB, created by Myles C. Maxfield on 2018-06-21 20:00:02 PDT

(hide)

Description:

Filename:

MIME Type:

Creator: Myles C. Maxfield

Created: 2018-06-21 20:00:02 PDT

Size: 11.08 KB

patch

obsolete

>Subversion Revision: 233058
>diff --git a/Tools/WebGPUShadingLanguageRI/SpecWork/source/index.rst b/Tools/WebGPUShadingLanguageRI/SpecWork/source/index.rst
>index a15347e8664e75a7b635305ed546c2cd115ec974..308b7213fe4fbcaf3dd652d526c00bca36ef305f 100644
>--- a/Tools/WebGPUShadingLanguageRI/SpecWork/source/index.rst
>+++ b/Tools/WebGPUShadingLanguageRI/SpecWork/source/index.rst
>@@ -6,12 +6,92 @@
> WSL Specification
> #################
> 
>+General
>+=======
>+
>+A shader passes through a series of compilation steps, eventually ending up
>+represented as machine code for the specific device the user is running. Any
>+intermediate forms the source may take throughout this transformation are beyond
>+the scope of this specification.
>+
>+.. Note:: The WebGPU Shading Language is designed to target other high-level shading
>+   languages as compilation targets.
>+
>+The WebGPU Shading Language is designed to be as portable as possible; therefore,
>+implementations must reject any shader which does not strictly adhere to this
>+specification. Optimizations such as dead code removal must be unobservable, and must not
>+affect error reporting.
>+
>+WSL shaders are used with the WebGPU API. Specific WebGPU API entry points to compile
>+and manipulate shaders are specified in the WebGPU specification, not this document.
>+
>+Implementations must not support functionality beyond the mandated parts of this
>+specification.
>+
>+WSL does not support extensions or optional behavior.
>+
>+Basics
>+======
>+
>+A shader is a compilation unit which includes type definitions and function definitions.
>+
>+WSL is used to describe different types of shaders:
>+
>+#. Vertex shaders
>+#. Fragment shaders
>+#. Compute shaders
>+
>+Each shader type represents software which may execute on a specialized processor. Different
>+draw calls, different shader types, or different invocations of the same shader, may execute
>+on independent processors.
>+
>+FIXME: Describe the three shader types
>+
>+A shader of a particular type may describe three
>+
>+Exactly one WSL shader occupies one stage in the [[!WEBGPU]] pipeline at a time. Two shaders
>+of the same shader type must not be used together in the same draw call or dispatch call.
>+Every stage of the appropriate [[!WEBGPU]] pipeline must be occupied by a shader in order to
>+execute a draw call or dispatch call.
>+
>+A WSL string passes through the following stages of processing before it is executed:
>+
>+#. Tokenization
>+#. Parsing
>+#. Validation
>+
>+Once a WSL string passes all the validation checks, it is then available to be used in a
>+draw call or dispatch call. A WSL string contains zero or more shaders, and each shader is
>+of a specific shader type. Compute shaders must only be used for dispatch calls, and vertex
>+and fragment shaders must only be used in draw calls.
>+
> Grammar
> =======
> 
> Lexical analysis
> ----------------
> 
>+Shaders exist as a Unicode string, and therefore support all the code points
>+Unicode supports.
>+
>+WSL does not include any digraphs or trigraphs. WSL is case-sensitive. It does not include any
>+escape sequences.
>+
>+.. Note:: WSL does not include a string type, so escape characters are not present in the
>+   language.
>+
>+WSL does not include a preprocessor step.
>+
>+.. Note:: Because there is no processor step, tokens such as '#if' are generally considered
>+   parse errors.
>+
>+Comments are replaced as if they are handled by a single space. Nested block comments are
>+not supported; instead, the first '/*' sequence is matched with the first '*/' sequence
>+following it.
>+
>+Reserved keywords
>+"""""""""""""""""
>+
> Parsing
> -------
> 
>@@ -65,6 +145,8 @@ I am afraid it may require several steps.
> The first step would do most of the work, gathering all function signatures, as well as typedefs, etc..
> The second step would go through the resulting environment, resolving all types, in particular all typedefs (as well as connecting function parameters to the corresponding type variables, etc..)
> 
>+We need to give consideration to the tons of qualifiers on variables that GLSL / Metal have.
>+
> Phase 3: Local typing and early validation
> ------------------------------------------
> 
>@@ -113,7 +195,7 @@ Typing statements
> Typing expressions
> """"""""""""""""""
> 
>- typing rules (this and everything that follows can be managed by just a pair of judgements that type stmts/exprs)
>+typing rules (this and everything that follows can be managed by just a pair of judgements that type stmts/exprs)
> - checking returns
> - check that every variable declaration is in a block or at the top-level
> - check that no variable declaration shadows another one at the same scope
>@@ -146,12 +228,105 @@ Execution of expressions
> Memory model
> ------------
> 
>+There are 4 address spaces:
>+
>+#. global (read-write)
>+#. constant
>+#. threadgroup
>+#. thread
>+
>+How do these interact with pointers? How can you have a pointer in one address space that points to a value in another address space?
>+
> Standard library
> ================
> 
>+Built-in Types
>+--------------
>+
>+Built-in Scalars
>+""""""""""""""""
>+
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| Type Name | Description                                                                    | Representable values                                                              |
>++===========+================================================================================+===================================================================================+
>+| void      | Must only be used as a return type from functions which don't return anything. | None                                                                              |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| bool      | A conditional type.                                                            | true or false                                                                     |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| uint8     | An unsigned 8-bit integer.                                                     | 0, 1, 2, ... 255                                                                  |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| uint32    | An unsigned 32-bit integer.                                                    | 0, 1, 2, ... 4294967295                                                           |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| uint64    | An unsigned 64-bit integer.                                                    | 0, 1, 2, ... 18446744073709551615                                                 |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| int8      | A signed 8-bit integer.                                                        | -128, -127, ... -1, 0, 1, ... 127                                                 |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| int32     | A signed 32-bit integer.                                                       | -2147483648, -2147483647, ... -1, 0, 1, ... 2147483647                            |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| int64     | A signed 64-bit integer.                                                       | -9223372036854775808, -9223372036854775807, ... -1, 0, 1, ... 9223372036854775807 |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| float32   | A 32-bit floating-point number.                                                | See below for details on representable values.                                    |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+| float64   | A 64-bit floating-point number.                                                | See below for details on representable values.                                    |
>++-----------+--------------------------------------------------------------------------------+-----------------------------------------------------------------------------------+
>+
>+In addition, the standard library includes some typedefs:
>+
>++---------------+----------------------------------------------+
>+| This new type | is defined to be equal to this existing type |
>++===============+==============================================+
>+| int           | int32                                        |
>++---------------+----------------------------------------------+
>+| uint          | uint32                                       |
>++---------------+----------------------------------------------+
>+| float         | float32                                      |
>++---------------+----------------------------------------------+
>+| double        | float64                                      |
>++---------------+----------------------------------------------+
>+
>+.. Note:: The following types are not present in WSL: dword, half, min16float, min10float, min16int, min12int, min16uint, string, short, unsigned short, size_t, ptrdiff_t
>+
>+Built-in aggregate types
>+""""""""""""""""""""""""
>+
>+#. Vectors (only hold primitive types, and only 1-4 of them)
>+#. Matrices
>+
>+Opaque types
>+""""""""""""
>+
>+#. Samplers (in the Metal notion of Sampler)
>+#. Textures (of all the various types), possibly discriminating between read-only and read-write
>+#. Should we treat buffers differently than arrays? HLSL does, but Metal doesn't.
>+#. Buffer blocks?
>+#. Pointers
>+#. We should figure out how we want to handle atomics.
>+
>+Numerical Compliance
>+""""""""""""""""""""
>+
>+Built-in Variables
>+------------------
>+
>+Different for each shader stage
>+
>+Represented by magic name?
>+
>+Built-in Functions
>+------------------
>+
>+Some of these (like barriers) require uniform control flow. We probably can't enforce dynamically uniform expressions, so without a strong use case, we should not include that concept.
>+
>+Some of these functions only appear in specific shader stages.
>+
>+We should figure out if atomic handling goes here.
>+
> Interface with JavaScript
> =========================
> 
>+Shaders are supplied to the Javascript WebGPU API as a single argument
>+which is understood to be of type 'DOMString'.
>+
> Indices and tables
> ##################
>

Actions: View | Formatted Diff | Diff

Attachments on bug 186906: 343303 | 343493 | 343494 | 343495