diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cpu-target.md | 81 |
1 files changed, 54 insertions, 27 deletions
diff --git a/docs/cpu-target.md b/docs/cpu-target.md index a0b4f0180..bbaf0084d 100644 --- a/docs/cpu-target.md +++ b/docs/cpu-target.md @@ -7,13 +7,13 @@ Slang has preliminary support for producing CPU source and binaries. * Can compile C/C++/Slang to binaries (executables and or shared libraries) * Can compile Slang source into C++ source code -* Supports compute style shaders +* Supports compute style shaders * C/C++ backend abstracts the command line options, and parses the compiler errors/out such that all supported compilers output available in same format * Once compilation is complete can optionally access and run CPU code directly # Limitations -These limitations apply to Slang source, with C/C++ the limitations are whatever the compiler requires +These limitations apply to Slang transpiling to C++. * Barriers are not supported (making these work would require an ABI change) * Atomics are not supported @@ -34,9 +34,9 @@ SLANG_PASS_THROUGH_GCC, ///< GCC C/C++ compiler SLANG_PASS_THROUGH_GENERIC_C_CPP, ///< Generic C or C++ compiler, which is decided by the source type ``` -Sometimes it is not important which C/C++ compiler is used, and this can be specified via the 'Generic C/C++' option. This will aim to use the compiler that is most likely binary compatible with the compiler that was used to build the slang binary being used. +Sometimes it is not important which C/C++ compiler is used, and this can be specified via the 'Generic C/C++' option. This will aim to use the compiler that is most likely binary compatible with the compiler that was used to build the Slang binary being used. -To make it possible for slang to produce CPU code, we now need a mechanism to convert slang code into C/C++. The first iteration only supports C++ generation. If source is desired instead of a binary this can be specified via the SlangCompileTarget. These can be specified on the slangc command line as `-target c` or `-target cpp`. +To make it possible for Slang to produce CPU code, we now need a mechanism to convert Slang code into C/C++. The first iteration only supports C++ generation. If source is desired instead of a binary this can be specified via the SlangCompileTarget. These can be specified on the `slangc` command line as `-target c` or `-target cpp`. Note that when using the 'pass through' mode for a CPU based target it is currently necessary to set an entry point, even though it's basically ignored. @@ -55,20 +55,20 @@ SLANG_SHARED_LIBRARY ///< A shared library/Dll (for hosting CPU/OS) SLANG_HOST_CALLABLE ///< A CPU target that makes the compiled code available to be run immediately ``` -These can also be specified on the slang command line as `-target exe` and `-target dll` or `-target sharedlib`. `-target callable` or `-target host-callable` is also possible, but is typically not very useful from the command line, other than to test such code is avaiable for host execution. +These can also be specified on the Slang command line as `-target exe` and `-target dll` or `-target sharedlib`. `-target callable` or `-target host-callable` is also possible, but is typically not very useful from the command line, other than to test such code can be loaded for host execution. -In order to be able to use the slang code on CPU, there needs to be binding via values passed to a function that the C/C++ code will produce and export. How this works is described in the ABI section. +In order to be able to use the Slang code on CPU, there needs to be binding via values passed to a function that the C/C++ code will produce and export. How this works is described in the ABI section. If a binary target is requested, the binary contents will be returned in a ISlangBlob just like for other targets. To use the CPU binary typically it must be saved as file and then potentially marked for execution by the OS before executing. It may be possible to load shared libraries or dlls from memory - but is a non standard feature, that requires unusual work arounds. -Under the covers when slang is used to generate a binary via a C/C++ compiler, it must do so through the file system. Currently this means that the source (say generated by slang) and the binary (produced by the C/C++ compiler) must all be files. To make this work slang uses temporary files. That the reasoning for hiding this mechanism - and not return say filenames, is so that in the future when binaries are produced directly (for example with LLVM), nothing will need to change. +Under the covers when Slang is used to generate a binary via a C/C++ compiler, it must do so through the file system. Currently this means that the source (say generated by Slang) and the binary (produced by the C/C++ compiler) must all be files. To make this work Slang uses temporary files. The reasoning for hiding this mechanism - and not return filenames, is so that in the future when binaries are produced directly (for example with LLVM), nothing will need to change. Executing CPU Code ================== -In typical slang operation when code is compiled it produces either source or a binary that can then be loaded by another API such as a rendering API. With CPU code the binary produced could be saved to a file and then executed as an exe or a shared library/dll. In practice though it is not uncommon to want to be able to execute compiled code immediately. Having to save off to a file and then load again can be awkward. It is also not necessarily the case that code needs to be saved to a file to be executed. +In typical Slang operation when code is compiled it produces either source or a binary that can then be loaded by another API such as a rendering API. With CPU code the binary produced could be saved to a file and then executed as an exe or a shared library/dll. In practice though it is common to want to be able to execute compiled code immediately. Having to save off to a file and then load again can be awkward. It is also not necessarily the case that code needs to be saved to a file to be executed. -To handle being able call code directly, code can be compiled using the SLANG_HOST_CALLABLE code target type. To access the code that has been produced use the function +To handle being able call code directly, code can be compiled using the `SLANG_HOST_CALLABLE` code target type. To access the code that has been produced use the function ``` SLANG_API SlangResult spGetEntryPointHostCallable( @@ -78,7 +78,7 @@ To handle being able call code directly, code can be compiled using the SLANG_HO ISlangSharedLibrary** outSharedLibrary); ``` -This outputs a `ISlangSharedLibrary` which whilst in scope, any contained functions remain available (even if the request or session go out of scope). The contained functions can then be accessed via the `findFuncByName` method on the `ISlangSharedLibrary` interface. +This outputs a `ISlangSharedLibrary` which whilst in scope, any contained functions remain available (even if the request or session go out of scope). The contained functions can then be accessed via the `findFuncByName` method on the `ISlangSharedLibrary` interface. Finding the entry point names, can be achieved using reflection, if not directly known to the client. The returned function pointer should be cast to the appropriate function signature before calling. For entry points - the function will appear under the same name as the entry point name. See the ABI section for what is the appropriate signature for entry points. @@ -87,7 +87,7 @@ For pass through compilation of C/C++ this mechanism allows any functions marked ABI === -Say we have some slang source like the following. +Say we have some Slang source like the following. ``` struct Thing { int a; int b; } @@ -105,19 +105,19 @@ void computeMain( } ``` -When it is compiled into a shared library/dll - how is it invoked? The entry point is exported with a signiture +When compiled into a shared library/dll - how is it invoked? The entry point is exported with a signiture ``` void computeMain(ComputeVaryingInput* varyingInput, UniformState* uniformState); ``` -The UniformState struct typically varies by shader, and it holds all of the bindings. Where these are located can be determined by reflection. For example +The UniformState struct typically varies by shader, and holds all of the bindings. Where these are located can be determined by reflection. For example ``` struct _S1 { - Thing_0 thing_0; - Thing_0 thing2_0; + Thing thing; + Thing thing2; }; struct UniformState @@ -130,9 +130,9 @@ struct UniformState }; ``` -For C++ targets, the templated types are defined in the slang-cpp-prelude.h that is included. Note that `slang-cpp-prelude.h` *MUST* currently be within the search path passed to the compiler. By default with CPU code-generation, the file path to the slang file is included as a 'system' include path, such that placing the `slang-cpp-prelude.h` file in the same directory as the slang source file should mean that it is found. +The code that sets up the prelude for the test infrastucture and command line usage can be found in ```TestToolUtil::setSessionDefaultPrelude```. -ConstantBuffers will become pointers to the type they hold (as thing3_0 is in the above structure). +ConstantBuffers will become pointers to the type they hold (as `thing3` is in the above structure). StructuredBuffer/RWStructuredBuffer/ByteAddressBuffer/RWByteAddressBuffer become in effect (where in ByteAddressBuffers T is uint32_t). @@ -147,15 +147,45 @@ The `_S1` struct in the example above (which may have different names) is actual Note that the this pointer is not directly reflected (although layout of uniform paramters in the struct are). Currently this pointer is just placed after all the other reflected bindings. +## Prelude -It may be useful to be able to include `slang-cpp-prelude.h` in C++ code to access the types that are used in the generated code. This introduces a problem in that the types used in the generated code might clash with types in client code. To work around this problem, you can wrap all of the types defined in the prelude with a namespace of your choosing. For example +For C++ targets, the code to support the code generated by Slang must be defined within the 'prelude'. The prelude is inserted text placed before the generated C++ source code. For the Slang command line tools as well as the test infrastructure, the prelude functionality is achieved through a `#include` in the prelude text of the `prelude/slang-cpp-prelude.h` specified with an absolute path. Doing so means other files the `slang-cpp-prelude.h` might need can be specified relatively, and include paths for the backend C/C++ compiler do not need to be modified. + +The prelude needs to define + +* 'Built in' types (vector, matrix, 'object'-like Texture, SamplerState etc) +* Scalar intrinsic function implementations +* Compiler based definations/tweaks + +For the Slang prelude this is split into the following files... + +* 'prelude/slang-cpp-prelude.h' - Header that includes all the other requirements & some compiler tweaks +* 'prelude/slang-cpp-scalar-intrinsics.h' - Scalar intrinsic implementations +* 'prelude/slang-cpp-types.h' - The 'built in types' +* 'slang.h' - Slang header is used for majority of compiler based definitions + +For a client application - as long as the requirements of the generated code are met, the prelude can be implemented by whatever mechanism is appropriate for the client . For example the implementation could be replaced with another implementation, or the prelude could contain all of the required text for compilation. Setting the prelude text can be achieved with the method on the global session... + +``` +/** Set the 'prelude' for generated code for a 'downstream compiler'. +@param passThrough The downstream compiler for generated code that will have the prelude applied to it. +@param preludeText The text added pre-pended verbatim before the generated source + +That for pass-through usage, prelude is not pre-pended, preludes are for code generation only. +*/ +virtual SLANG_NO_THROW void SLANG_MCALL setDownstreamCompilerPrelude( +SlangPassThrough passThrough, +const char* preludeText) = 0; +``` + +It may be useful to be able to include `slang-cpp-types.h` in C++ code to access the types that are used in the generated code. This introduces a problem in that the types used in the generated code might clash with types in client code. To work around this problem, you can wrap all of the types defined in the prelude with a namespace of your choosing. For example ``` #define SLANG_PRELUDE_NAMESPACE CPPPrelude -#include "../../tests/cross-compile/slang-cpp-prelude.h" +#include "../../prelude/slang-cpp-types.h" ``` -Would wrap all the slang prelude types in the namespace `CPPPrelude`. +Would wrap all the Slang prelude types in the namespace `CPPPrelude`, such that say a `StructuredBuffer<int32_t>` could be specified in C++ source code as `CPPPrelude::StructuredBuffer<int32_t>`. Language aspects ================ @@ -173,15 +203,14 @@ Limitations In HLSL code if an access is made out of bounds of a StructuredBuffer, execution proceceeds. If an out of bounds read is performed, a zeroed value is returned. If an out of bounds write is performed it's effectively a noop, as the value is discarded. -On the CPU target this behaviour is *NOT* supported. For a debug CPU build an out of bounds access will assert, for a release build the behaviour is undefined. +On the CPU target this behavior is *NOT* supported. For a debug CPU build an out of bounds access will assert, for a release build the behaviour is undefined. -The reason for this is that such an access is quite difficult and/or slow to implement on the CPU. The underlying reason is that operator[] typically returns a reference to the contained value. If this is out of bounds - it's not clear what to return, in particular because the value may be read or written and moreover elements of the type might bet written. In practice this means a global zeroed value cannot be returned. +The reason for this is that such an access is difficult and/or slow to implement on the CPU. The underlying reason is that `operator[]` typically returns a reference to the contained value. If this is out of bounds - it's not clear what to return, in particular because the value may be read or written and moreover elements of the type might be written. In practice this means a global zeroed value cannot be returned. -This could be supported if code gen worked as followed for say +This could be somewhat supported if code gen worked as followed for say ``` RWStructuredBuffer<float4> values; - values[3].x = 10; ``` @@ -214,7 +243,6 @@ TODO * Complete support (in terms of interfaces) for 'complex' resource types - such as Texture * Parameter block support (the difficulty is around layout) * Split out entry point uniforms into a separate pointer passed to the entry point -* Test system executes and tests for CPU targets - for example compute tests run on CPU * Improve documentation * Output of header files @@ -222,9 +250,8 @@ TODO These issues are more internal Slang features/improvements -* Slang compute tests work (where appropriate) * Currently only generates C++ code, it would be fairly straight forward to support C (especially if we have 'intrinsic definitions') * Have 'intrinsic definitions' in standard library - such that they can be generated where appropriate - + This will simplify the C/C++ code generation as means slang language will generate must of the appropriate code + + This will simplify the C/C++ code generation as means Slang language will generate must of the appropriate code * Currently 'construct' IR inst is supported as is, we may want to split out to separate instructions for specific scenarios * Refactoring around swizzle. Currently in emit it has to check for a variety of scenarios - could be simplified with an IR pass and perhaps more specific instructions. |