summaryrefslogtreecommitdiffstats
path: root/docs/design
diff options
context:
space:
mode:
authorJay Kwak <82421531+jkwak-work@users.noreply.github.com>2024-10-25 21:12:37 -0700
committerGitHub <noreply@github.com>2024-10-25 21:12:37 -0700
commita508b264eda4bc3c99ba1f44eab1dec6e5ce06c0 (patch)
tree717722aefcae6b2a5adbccfbcd8aece4ed81f0b7 /docs/design
parent49c691e86862d092cd389a02beb4003ee59a4417 (diff)
Swap the term StdLib with Core-Module or Standard-Module in documents (#5414)
This PR is limited to documents. All use of "Standard library" or "StdLib" are replaced with either "core module" or "standard modules", depending on the context.
Diffstat (limited to 'docs/design')
-rw-r--r--docs/design/autodiff/decorators.md6
-rw-r--r--docs/design/autodiff/types.md4
-rw-r--r--docs/design/capabilities.md6
-rw-r--r--docs/design/coding-conventions.md4
-rw-r--r--docs/design/interfaces.md2
-rw-r--r--docs/design/overview.md4
-rw-r--r--docs/design/serialization.md4
-rw-r--r--docs/design/stdlib-intrinsics.md14
8 files changed, 22 insertions, 22 deletions
diff --git a/docs/design/autodiff/decorators.md b/docs/design/autodiff/decorators.md
index b08da2912..626f8bc4c 100644
--- a/docs/design/autodiff/decorators.md
+++ b/docs/design/autodiff/decorators.md
@@ -50,11 +50,11 @@ In such cases, we provide the `[TreatAsDifferentiable]` decoration (AST node: `T
## Custom derivative decorators
In many cases, it is desirable to manually specify the derivative code for a method rather than let the auto-diff pass synthesize it from the method body. This is usually desirable if:
1. The body of the method is too complex, and there is a simpler, mathematically equivalent way to compute the same value (often the case for intrinsics like `sin(x)`, `arccos(x)`, etc..)
-2. The method involves global/shared memory accesses, and synthesized derivative code may cause race conditions or be very slow due to overuse of synchronization. For this reason Slang assumes global memory accesses are non-differentiable by default, and requires that the user (or stdlib) define separate accessors with different derivative semantics.
+2. The method involves global/shared memory accesses, and synthesized derivative code may cause race conditions or be very slow due to overuse of synchronization. For this reason Slang assumes global memory accesses are non-differentiable by default, and requires that the user (or the core module) define separate accessors with different derivative semantics.
The Slang front-end provides two sets of decorators to facilitate this:
1. To reference a custom derivative function from a primal function: `[ForwardDerivative(fn)]` and `[BackwardDerivative(fn)]` (AST Nodes: `ForwardDerivativeAttribute`/`BackwardDerivativeAttribute`, IR: `OpForwardDervativeDecoration`/`OpBackwardDerivativeDecoration`), and
-2. To reference a primal function from its custom derivative function: `[ForwardDerivativeOf(fn)]` and `[BackwardDerivativeOf(fn)]` (AST Nodes: `ForwardDerivativeAttributeOf`/`BackwardDerivativeAttributeOf`). These attributes are useful to provide custom derivatives for existing methods in a different file without having to edit/change that module. For instance, we use `diff.meta.slang` to provide derivatives for stdlib functions in `hlsl.meta.slang`. When lowering to IR, these references are placed on the target (primal function). That way both sets of decorations are lowered on the primal function.
+2. To reference a primal function from its custom derivative function: `[ForwardDerivativeOf(fn)]` and `[BackwardDerivativeOf(fn)]` (AST Nodes: `ForwardDerivativeAttributeOf`/`BackwardDerivativeAttributeOf`). These attributes are useful to provide custom derivatives for existing methods in a different file without having to edit/change that module. For instance, we use `diff.meta.slang` to provide derivatives for the core module functions in `hlsl.meta.slang`. When lowering to IR, these references are placed on the target (primal function). That way both sets of decorations are lowered on the primal function.
These decorators also work on generically defined methods, as well as struct methods. Similar to how function calls work, these decorators also work on overloaded methods (and reuse the `ResolveInoke` infrastructure to perform resolution)
@@ -89,4 +89,4 @@ void sampleTexture_bwd(TexHandle2D tex, inout DifferentialPair<float2> dp_uv, fl
}
```
-The implementation of `[PrimalSubstitute(fn)]` is relatively straightforward. When the transcribers are asked to synthesize a derivative of a function, they check for a `OpPrimalSubstituteDecoration`, and swap the current function out for the substitute function before proceeding with derivative synthesis. \ No newline at end of file
+The implementation of `[PrimalSubstitute(fn)]` is relatively straightforward. When the transcribers are asked to synthesize a derivative of a function, they check for a `OpPrimalSubstituteDecoration`, and swap the current function out for the substitute function before proceeding with derivative synthesis.
diff --git a/docs/design/autodiff/types.md b/docs/design/autodiff/types.md
index 12b468a6e..2655b5c25 100644
--- a/docs/design/autodiff/types.md
+++ b/docs/design/autodiff/types.md
@@ -8,7 +8,7 @@ Here we detail the main components of the type system: the `IDifferentiable` int
We also detail how auto-diff operators are type-checked (the higher-order function checking system), how the `no_diff` decoration can be used to avoid differentiation through attributed types, and the derivative data flow analysis that warns the the user of unintentionally stopping derivatives.
## `interface IDifferentiable`
-Defined in core.meta.slang, `IDifferentiable` forms the basis for denoting differentiable types, both within the stdlib, and otherwise.
+Defined in core.meta.slang, `IDifferentiable` forms the basis for denoting differentiable types, both within the core module, and otherwise.
The definition of `IDifferentiable` is designed to encapsulate the following 4 items:
1. `Differential`: The type of the differential value of the conforming type. This allows custom data-structures to be defined to carry the differential values, which may be optimized for space instead of relying solely on compiler synthesis/
@@ -110,7 +110,7 @@ void bwd_myFunc<T:IDifferentiable>(
Existential types are interface-typed values, where there are multiple possible implementations at run-time. The existential type carries information about the concrete type at run-time and is effectively a 'tagged union' of all possible types.
#### Differential type of an Existential
-The differential type of an existential type is tricky to define since our type system's only restriction on the `.Differential` type is that it also conforms to `IDifferentiable`. The differential type of any interface `IInterface : IDifferentiable` is therefore the interface type `IDifferentiable`. This is problematic since Slang generally requires a static `anyValueSize` that must be a strict upper bound on the sizes of all conforming types (since this size is used to allocate space for the union). Since `IDifferentiable` is defined in the stdlib `core.meta.slang` and can be used by the user, it is impossible to define a reliable bound.
+The differential type of an existential type is tricky to define since our type system's only restriction on the `.Differential` type is that it also conforms to `IDifferentiable`. The differential type of any interface `IInterface : IDifferentiable` is therefore the interface type `IDifferentiable`. This is problematic since Slang generally requires a static `anyValueSize` that must be a strict upper bound on the sizes of all conforming types (since this size is used to allocate space for the union). Since `IDifferentiable` is defined in the core module `core.meta.slang` and can be used by the user, it is impossible to define a reliable bound.
We instead provide a new **any-value-size inference** pass (`slang-ir-any-value-inference.h`/`slang-ir-any-value-inference.cpp`) that assembles a list of types that conform to each interface in the final linked IR and determines a relevant upper bound. This allows us to ignore types that conform to `IDifferentiable` but aren't used in the final IR, and generate a tighter upper bound.
**Future work:**
diff --git a/docs/design/capabilities.md b/docs/design/capabilities.md
index 74c08fca9..a4f4fa396 100644
--- a/docs/design/capabilities.md
+++ b/docs/design/capabilities.md
@@ -9,7 +9,7 @@ Slang aims to be a portable language for shader programming, which introduces tw
Item (2) is traditionally handled with preprocessor techniques (e.g., `#ifdef`ing the body of a function based on target platform), but that of course requires that the user invoke the Slang front end once for each target platform, and target-specific coding in a library will then "infect" code that uses that library, forcing them to invoke the front-end once per target as well.
-We are especially sensitive to this problem in the compiler itself, because we have to author and maintain the Slang standard library, which needs to (1) expose the capabilities of many platforms and (2) work across all those platforms. It would be very unfortunate if we had to build different copies of our standard library per-target.
+We are especially sensitive to this problem in the compiler itself, because we have to author and maintain the Slang standard modules, which needs to (1) expose the capabilities of many platforms and (2) work across all those platforms. It would be very unfortunate if we had to build different copies of our standard modules per-target.
The intention in Slang is to solve both of these problems with a system of *capabilities*.
@@ -19,7 +19,7 @@ What is a capability?
For our purposes a capability is a discrete feature that a compilation target either does or does not support.
We could imagine defining a capability for the presence of texture sampling operations with implicit gradients; this capability would be supported when generating fragment shader kernel code, but not when generating code for other stages.
-Let's imagine a language syntax that the standard library could use to define some *atomic* capabilities:
+Let's imagine a language syntax that the standard modules could use to define some *atomic* capabilities:
```
capability implicit_gradient_texture_fetches;
@@ -268,4 +268,4 @@ Conclusion
----------
Overall, the hope is that in many cases developers will be able to use capability-based partitioning and overloading of APIs to build code that only has to pass through the Slang front-end once, but that can then go through back-end code generation for each target.
-In cases where this can't be achieved, the way that capability-based overloading is built into the Slang IR design means that we should be able to merge multiple target-specific definitions into one IR module, so that a library can employ target-specific specializations while still presenting a single API to consumers.
+In cases where this can't be achieved, the way that capability-based overloading is built into the Slang IR design means that we should be able to merge multiple target-specific definitions into one IR module, so that a module can employ target-specific specializations while still presenting a single API to consumers.
diff --git a/docs/design/coding-conventions.md b/docs/design/coding-conventions.md
index b2492685f..228b26de7 100644
--- a/docs/design/coding-conventions.md
+++ b/docs/design/coding-conventions.md
@@ -72,7 +72,7 @@ As a general rule, default to making the implementation of a type `public`, and
### Slang
-The Slang project codebase also includes `.slang` files implementing the Slang standard library, as well as various test cases and examples.
+The Slang project codebase also includes `.slang` files implementing the Slang core module, as well as various test cases and examples.
The conventions described here are thus the "official" recommendations for how users should format Slang code.
To the extent possible, we will try to apply the same basic conventions to both C++ and Slang.
@@ -132,7 +132,7 @@ Namespaces
Favor fewer namespaces when possible.
Small programs may not need any.
-All library code that a Slang user might link against should go in the `Slang` namespace for now, to avoid any possibility of clashes in a static linking scenario.
+All standard module code that a Slang user might link against should go in the `Slang` namespace for now, to avoid any possibility of clashes in a static linking scenario.
The public C API is obviously an exception to this.
diff --git a/docs/design/interfaces.md b/docs/design/interfaces.md
index 29740694e..c0e284f59 100644
--- a/docs/design/interfaces.md
+++ b/docs/design/interfaces.md
@@ -163,7 +163,7 @@ That is intentional, because at the most basic level, interfaces are designed to
### Generic Declarations
-The Slang compiler currently has some ad hoc support for generic declarations that it uses to implement the HLSL standard library (which has a few generic types).
+The Slang compiler currently has some ad hoc support for generic declarations that it uses to implement the HLSL standard module (which has a few generic types).
The syntax for those is currently very bad, and it makes sense to converge on the style for generic declarations used by C# and Swift:
float myGenericFunc<T>(T someValue);
diff --git a/docs/design/overview.md b/docs/design/overview.md
index 7c2b16cf3..c81853f1a 100644
--- a/docs/design/overview.md
+++ b/docs/design/overview.md
@@ -71,7 +71,7 @@ This means that most of the language "keywords" in Slang aren't keywords at all,
Syntax declarations are associated with a callback that is invoked to parse the construct they name.
The design of treating syntax as ordinary declarations has a long-term motivation (we'd like to support a flexible macro system) but it also has short-term practical benefits.
-It is easy for us to add new modifier keywords to the language without touching the lexer or parser (just adding them to the standard library), and we also don't have to worry about any of Slang's extended construct (e.g., `import`) breaking existing HLSL code that just happens to use one of those new keywords as a local variable name.
+It is easy for us to add new modifier keywords to the language without touching the lexer or parser (just adding them to the core module), and we also don't have to worry about any of Slang's extended construct (e.g., `import`) breaking existing HLSL code that just happens to use one of those new keywords as a local variable name.
What the parser produces is an abstract syntax tree (AST).
The AST currently uses a strongly-typed C++ class hierarchy with a "visitor" API generated via some ugly macro magic.
@@ -186,7 +186,7 @@ We make a copy of things so that any optimization/transformation passes we do fo
While copying IR code into the fresh module, we have cases where there might be multiple definitions of the same function or other entity.
In those cases, we apply "target specialization" to pick the definition that is the best for the chosen target.
-This step is where we can select between, say, a built-in definition of the `saturate` function for D3D targets, vs. a hand-written one in the Slang standard library to use for GLSL-based targets.
+This step is where we can select between, say, a built-in definition of the `saturate` function for D3D targets, vs. a hand-written one in a Slang standard module to use for GLSL-based targets.
### API Legalization
diff --git a/docs/design/serialization.md b/docs/design/serialization.md
index 1f69eb61d..c05c60ad8 100644
--- a/docs/design/serialization.md
+++ b/docs/design/serialization.md
@@ -268,7 +268,7 @@ AST Serialization
AST serialization uses the generalized serialization mechanism.
-When serializing out an AST module it is typical to want to just serialize out the definitions within that module. Without this, the generalized serializer will crawl over the whole of the AST structure serializing every thing that can be reached - including the whole of the standard library.
+When serializing out an AST module it is typical to want to just serialize out the definitions within that module. Without this, the generalized serializer will crawl over the whole of the AST structure serializing every thing that can be reached - including the whole of the core module.
The filter `ModuleSerialFilter` can be used when writing the AST module, it will replace any references to elements outside of the current module with a `ImportExternalDecl`. This contains a mangled name to the item being referenced in another module.
@@ -328,4 +328,4 @@ Issues
* All types (and typedefs) that are serialized must be defined in the same scope - child types don't work correctly
* When using value serialization serialization all the members that are serializable must be public
-* The types output in slang fields do not correctly take into account scope (this is a similar issue to the issue above) \ No newline at end of file
+* The types output in slang fields do not correctly take into account scope (this is a similar issue to the issue above)
diff --git a/docs/design/stdlib-intrinsics.md b/docs/design/stdlib-intrinsics.md
index 8d78de504..6e86f4c3f 100644
--- a/docs/design/stdlib-intrinsics.md
+++ b/docs/design/stdlib-intrinsics.md
@@ -1,17 +1,17 @@
-Stdlib Intrinsics
-=================
+Core Module Intrinsics
+======================
-The following document aims to cover a variety of systems used to add target specific features. They are most extensively used in the slang standard library (stdlib).
+The following document aims to cover a variety of systems used to add target specific features. They are most extensively used in the slang core module.
**NOTE!** These features should *not* be considered stable! They can be used in regular slang code to add features, but they risk breaking with any Slang version change. Additionally the features implementation can be very particular to what is required for a specific feature set, so might not work as expected in all scenarios.
As these features are in flux, it is quite possible this document is behind the current features available within the Slang code base.
-If you want to add support for a feature for a target to Slang, implementing it as part of the Slang standard library is typically a good way to progress. Depending on the extension/feature it may not be possible to add support exclusively via changes to the standard library alone. That said most support for target specific extensions and features involve at least some changes to the slang standard library, and typically using the mechanisms described here.
+If you want to add support for a feature for a target to Slang, implementing it as a part of the Slang standard modules is typically a good way to progress. Depending on the extension/feature it may not be possible to add support exclusively via changes to the standard module alone. That said most support for target specific extensions and features involve at least some changes to the slang standard modules including the core module, and typically using the mechanisms described here.
-## Standard Library
+## Core Module
-The main place these features are used are within the slang standard library (aka stdlib). This is implemented with a set of slang files within the slang project
+The main place these features are used are within the slang core module. This is implemented with a set of slang files within the slang project
* core.meta.slang
* hlsl.meta.slang
@@ -146,7 +146,7 @@ Used before a type declaration. The clsName is the name of the class that is use
Used to specify the IR opcode associated with a type. The IR opcode is listed as something like `$(kIROp_HLSLByteAddressBufferType)`, which will expand to the integer value of the opcode (because the opcode value is an enum value that is visible from C++). It is possible to just write the opcode number, but that is generally inadvisable as the ids for ops are not stable. If a code change in Slang C++ adds or removes an opcode the number is likely to be incorrect.
-As an example from stdlib
+As an example from the core module
```slang
__magic_type(HLSLByteAddressBufferType)