diff --git a/docs/overview/advanced-examples.rst b/docs/overview/advanced-examples.rst index 0ddf3e32a..e4cc83049 100644 --- a/docs/overview/advanced-examples.rst +++ b/docs/overview/advanced-examples.rst @@ -23,10 +23,10 @@ End-to-end examples * `Android NDK Mobile Kompute ML Application `_ * `Game Development Kompute ML in Godot Engine `_ -Add Vulkan Extensions +Add Extensions ^^^^^^^^^^^^^^^^^^^^ -Kompute provides a simple way to add Vulkan extensions through kp::Manager initialisation. When debug is enabled you will be able to see logs that show what are the desired extensions requested and the ones that are added based on the available extensions on the current driver. +Kompute provides a simple way to add extensions through kp::Manager initialisation. When debug is enabled you will be able to see logs that show what are the desired extensions requested and the ones that are added based on the available extensions on the current driver. The example below shows how you can enable the "VK_EXT_shader_atomic_float" extension so we can use the adomicAdd for floats in the shaders. @@ -165,7 +165,7 @@ First we are able to create the manager as we normally would. .. code-block:: cpp :linenos: - // You can allow Kompute to create the Vulkan components, or pass your existing ones + // You can allow Kompute to create the GPU resources, or pass your existing ones kp::Manager mgr; // Selects device 0 unless explicitly requested // Creates tensor an initializes GPU memory (below we show more granularity) @@ -262,7 +262,7 @@ In order to work with parallel execution of tasks, it is important that you unde Conceptual Overview ^^^^^^^^^^^^^^^^^^^^^ -If you are familiar with Vulkan, you will have experience that the first few things you do is fetching the physical Queues from the device. The queues themselves tend to have three main particular features - they can be GRAPHICS, TRANSFER and COMPUTE (between a few others we'll skip for simplicity). +If you are familiar with the Vulkan SDK, you will have experience that the first few things you do is fetching the physical Queues from the device. The queues themselves tend to have three main particular features - they can be GRAPHICS, TRANSFER and COMPUTE (between a few others we'll skip for simplicity). Queues can have multiple properties - namely a queue can be of type GRAPHICS+TRANSFER+COMPUTE, etc. Now here comes the key point: the underlying hardware may (or may not) support parallelized processing at multiple levels. @@ -272,7 +272,7 @@ With this in mind, the NVIDIA 1650 as of today does not support intra-family par However the NVIDIA 1650 does support inter-family parallelization, which means that if we were to submit commands across multiple queues from different families, these would execute in parallel. -This means that we would be able to execute parallel workloads as long as we're running them across multiple queue families. This is one of the reasons why Vulkan Kompute enables users to explicitly select the underlying queues and queue families to run particular workloads on. +This means that we would be able to execute parallel workloads as long as we're running them across multiple queue families. This is one of the reasons why Kompute enables users to explicitly select the underlying queues and queue families to run particular workloads on. It is important that you understand what are the capabilities and limitations of your hardware, as parallelization capabilities can vary, so you will want to make sure you account for potential discrepancies in processing structures, mainyl to avoid undesired/unexpected race conditions. diff --git a/docs/overview/async-parallel.rst b/docs/overview/async-parallel.rst index 6b1f68b62..114ac8f3b 100644 --- a/docs/overview/async-parallel.rst +++ b/docs/overview/async-parallel.rst @@ -23,7 +23,7 @@ Asynchronous operation submission As the name implies, this refers to the asynchronous submission of operations. This means that operations can be submitted to the GPU, and the C++ / host CPU can continue performing tasks, until when the user desires to run `await` to wait until the operation finishes. -This basically provides further granularity on Vulkan Fences, which is its means to enable the CPU host to know when GPU commands have finished executing. +This basically provides further granularity on vk::Fences, which is its means to enable the CPU host to know when GPU commands have finished executing. It is important that submitting tasks asynchronously, does not mean that these will be executed in parallel. Parallel execution of operations will be covered in the following section. diff --git a/docs/overview/build-system.rst b/docs/overview/build-system.rst index cb6933ba4..aa4f01f2d 100644 --- a/docs/overview/build-system.rst +++ b/docs/overview/build-system.rst @@ -50,11 +50,11 @@ Compile Flags * - KOMPUTE_CREATE_PIPELINE_RESULT_VALUE - Ensure the return value of createPipeline is processed as ResultValue instead of Result * - -DKOMPUTE_VK_API_VERSION="..." - - Sets the default api version to use for vulkan kompute api + - Sets the default api version to use for kompute api * - -DKOMPUTE_VK_API_MAJOR_VERSION=1 - - Major version to use for the Vulkan API + - Major version to use for the Vulkan SDK * - -DKOMPUTE_VK_API_MINOR_VERSION=1 - - Minor version to use for the Vulkan API + - Minor version to use for the Vulkan SDK * - -DKOMPUTE_ENABLE_SPDLOG=1 - Enables the build with SPDLOG and FMT dependencies (must be installed) * - -DKOMPUTE_LOG_VERRIDE=1 @@ -68,7 +68,7 @@ Compile Flags * - -DDEBUG=1 - Enable debug build including debug flags (enabled by cmake debug build) * - -DKOMPUTE_DISABLE_VK_DEBUG_LAYERS - - Disable the debug Vulkan layers, mainly used for android builds + - Disable the debug Vulkan SDK Layers, mainly used for android builds * - -DKOMPUTE_DISABLE_SHADER_UTILS - Disable the shader utils and skip adding glslang as dependency @@ -81,12 +81,12 @@ Given Kompute is expected to be used across a broad range of architectures and h Required dependencies ~~~~~~~~~~~~~~~~~~~~~ -The only required dependency in the build is Vulkan. More specifically, the header files vulkan.h and vulkan.hpp, which are both part of the Vulkan SDK. If you haven't installed the Vulkan SDK yet, you can `download it here `_. +The only required dependency in the build is the Vulkan SDK. More specifically, the header files vulkan.h and vulkan.hpp, which are both part of the Vulkan SDK. If you haven't installed the Vulkan SDK yet, you can `download it here `_. Optional dependencies ~~~~~~~~~~~~~~~~~~~~~ -SPDLOG is the preferred logging library, however by default Vulkan Kompute runs without SPDLOG by overriding the macros. It also provides an easy way to override the macros if you prefer to bring your own logging framework. The macro override is the following: +SPDLOG is the preferred logging library, however by default Kompute runs without SPDLOG by overriding the macros. It also provides an easy way to override the macros if you prefer to bring your own logging framework. The macro override is the following: .. code-block:: c++ diff --git a/docs/overview/ci-tests.rst b/docs/overview/ci-tests.rst index 4afc1f0ce..e65464f91 100644 --- a/docs/overview/ci-tests.rst +++ b/docs/overview/ci-tests.rst @@ -2,7 +2,7 @@ CI, Docker Images, Docs & Tests ====================== -This section contains an overview of the steps run on CI, as well as the tools used to simplify the testing (such as running Vulkan on CPU). +This section contains an overview of the steps run on CI, as well as the tools used to simplify the testing (such as running on CPU). We use Github Actions to run the tests, which simplifies the workflows significantly for contributors. @@ -33,12 +33,12 @@ When submitting a PR or merging a PR into master, both of these will run - you c -Running Vulkan on the CPU +Running on the CPU ~~~~~~~~~~~~~ -We use `Swiftshader `_ to enable us to run the Vulkan Kompute framework directly on the CPU for the CI tests. +We use `Swiftshader `_ to enable us to run the Kompute framework directly on the CPU for the CI tests. -Even though Swiftshader is optimized to function as a high-performance CPU backend for Vulkan, there are several limitations, the most notable in context of Kompute are: +Even though Swiftshader is optimized to function as a high-performance CPU backend for the Vulkan SDK, there are several limitations, the most notable in context of Kompute are: * Loading files (spirv or text) leads to segfault * Loading raw text string shaders leads to segfault diff --git a/docs/overview/custom-operations.rst b/docs/overview/custom-operations.rst index 21f1fb82c..027e7b489 100644 --- a/docs/overview/custom-operations.rst +++ b/docs/overview/custom-operations.rst @@ -13,7 +13,7 @@ Flow of Function Calls The top level operation which all operations inherit from is the :class:`kp::OpBase` class. Some of the "Core Native Operations" like :class:`kp::OpTensorCopy`, :class:`kp::OpTensorCreate`, etc all inherit from the base operation class. -The `kp::OpAlgoBase` is another base operation that is specifically built to enable users to create their own operations that contain custom shader logic (i.e. requiring Vulkan Compute Pipelines, DescriptorSets, etc). The next section contains an example which shows how to extend the OpAlgoBase class. +The `kp::OpAlgoBase` is another base operation that is specifically built to enable users to create their own operations that contain custom shader logic (i.e. requiring Compute Pipelines, DescriptorSets, etc). The next section contains an example which shows how to extend the OpAlgoBase class. Below you @@ -25,11 +25,11 @@ Below you * - OpBase(..., tensors, freeTensors) - Constructor for class where you can load/define resources such as shaders, etc. * - ~OpBase() - - Destructor that frees vulkan resources (if owned) which should be used to manage any memory allocations created through the operation. + - Destructor that frees GPU resources (if owned) which should be used to manage any memory allocations created through the operation. * - init() - Init function gets called in the Sequence / Manager inside the record step. This function allows for relevant objects to be initialised within the operation. * - record() - - Record function that gets called in the Sequence / Manager inside the record step after init(). In this function you can directly record to the Vulkan command buffer. + - Record function that gets called in the Sequence / Manager inside the record step after init(). In this function you can directly record to the vk::CommandBuffer. * - preEval() - When the Sequence is Evaluated this preEval is called across all operations before dispatching the batch of recorded commands to the GPU. This is useful for example if you need to copy data from local to host memory. * - postEval() diff --git a/docs/overview/memory-management.rst b/docs/overview/memory-management.rst index 5ecfd7c0f..28a3eaea5 100755 --- a/docs/overview/memory-management.rst +++ b/docs/overview/memory-management.rst @@ -2,7 +2,7 @@ Memory Management Principles ===================== -The principle in Vulkan Kompute on memory management is summarised as follows: +The principle in Kompute on memory management is summarised as follows: * Memory management by Kompute is optional and only in place if resource is created by Kompute * Memory management ownership architecture are acyclic and with a single top manager @@ -12,9 +12,9 @@ The principle in Vulkan Kompute on memory management is summarised as follows: * Once a resource is destroyed it cannot be recreated * Resources can only be rebuilt if they haven't been destroyed -Vulkan Kompute is responsible for managing both the CPU and GPU memory allocations and resources that it creates, and is important that they are able to explicitly define when these objects are released or destroyed. Similarly, it's important that the memory resources created by the application are released safely. +Kompute is responsible for managing both the CPU and GPU memory allocations and resources that it creates, and is important that they are able to explicitly define when these objects are released or destroyed. Similarly, it's important that the memory resources created by the application are released safely. -Vulkan Kompute is built with the BYOV principle in mind (Bring your own Vulkan). This means that even though the top level resources are managing the memory to its owned resources, they themselves may not have full ownership of the GPU / Vulkan components - this is in the case that you may want to use Kompute with an existing Vulkan enabled application, and may want to initialise Kompute components with existing Vulkan resources. +Kompute is built with the BYOV principle in mind (Bring your own VulkanSDK). This means that even though the top level resources are managing the memory to its owned resources, they themselves may not have full ownership of the GPU / Vulkan SDK components - this is in the case that you may want to use Kompute with an existing Vulkan SDK enabled application, and may want to initialise Kompute components with existing Vulkan SDK resources. The memory ownership is hierarchically outlined in the component architecture - in this diagram, the arrows provide an intuition on the memory management ownership relationships. It's worth mentioning that the memory relationship may be different to the way components interact with each other - for this, you can see the high level component overview. More specifically: * The purple arrows denote GPU memory management @@ -25,7 +25,7 @@ The memory ownership is hierarchically outlined in the component architecture - Optional Memory Management ------------- -As outlined above, resource memory is only managed by Kompute if the resources are created by Kompute. Each of the Kompute components can also be initialised with externally managed resources. The :class:`kp::Manager` for example can be initialized with an external Vulkan Device. The first principle ensures that all memory ownership is explicitly defined when managing and creating Kompute resources. +As outlined above, resource memory is only managed by Kompute if the resources are created by Kompute. Each of the Kompute components can also be initialised with externally managed resources. The :class:`kp::Manager` for example can be initialized with an external vk::Device. The first principle ensures that all memory ownership is explicitly defined when managing and creating Kompute resources. diff --git a/docs/overview/python-package.rst b/docs/overview/python-package.rst index db9593219..fae6a91be 100644 --- a/docs/overview/python-package.rst +++ b/docs/overview/python-package.rst @@ -4,7 +4,7 @@ Python Package Overview This section provides an overview of the Python Package from a functionality perspective. If you wish to see examples check the `Python Simple & Advanced Examples section `_ all the classes and their respective functions you can find that in the `Python Class Reference Section `_. -Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory. +Below is a diagram that provides insights on the relationship between Kompute objects and Vulkan SDK resources, which primarily encompass ownership of either CPU and/or GPU memory. .. image:: ../images/kompute-architecture.jpg :width: 70% @@ -36,7 +36,7 @@ Core Python Components The Python package exposes three main classes: -* :class:`kp.Manager` - Manages all high level Vulkan and Kompute resources created +* :class:`kp.Manager` - Manages all high level GPU and Kompute resources created * :class:`kp.Sequence` - Contains a set of recorded operations that can be reused * :class:`kp.Tensor` - Core data component to manage GPU and host data used in operations diff --git a/docs/overview/python-reference.rst b/docs/overview/python-reference.rst index 89b426ce0..097b8fe83 100644 --- a/docs/overview/python-reference.rst +++ b/docs/overview/python-reference.rst @@ -4,7 +4,7 @@ Python Class Documentation & Reference ======== This section provides a breakdown of the Python classes and what each of their functions provide. -Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory. +Below is a diagram that provides insights on the relationship between Kompute objects and Vulkan SDK resources, which primarily encompass ownership of either CPU and/or GPU memory. Manager ------- @@ -18,7 +18,7 @@ The Kompute Manager provides a high level interface to simplify interaction with Sequence ------- -The Kompute Sequence consists of batches of Kompute Operations, which are executed on a respective GPU queue. The execution of sequences can be synchronous or asynchronous, and it can be coordinated through its respective Vulkan Fence. +The Kompute Sequence consists of batches of Kompute Operations, which are executed on a respective GPU queue. The execution of sequences can be synchronous or asynchronous, and it can be coordinated through its respective vk::Fence. .. autoclass:: kp.Sequence :members: diff --git a/docs/overview/reference.rst b/docs/overview/reference.rst index 51704ac5c..76d165147 100644 --- a/docs/overview/reference.rst +++ b/docs/overview/reference.rst @@ -4,7 +4,7 @@ Class Documentation and C++ Reference This section provides a breakdown of the cpp classes and what each of their functions provide. It is partially generated and augomented from the Doxygen autodoc content. You can also go directly to the `raw doxygen docs <../doxygen/annotated.html>`_. -Below is a diagram that provides insights on the relationship between Vulkan Kompute objects and Vulkan resources, which primarily encompass ownership of either CPU and/or GPU memory. +Below is a diagram that provides insights on the relationship between Kompute objects and Vulkan SDK resources, which primarily encompass ownership of either CPU and/or GPU memory. .. image:: ../images/kompute-vulkan-architecture.jpg :width: 100% @@ -45,7 +45,7 @@ The :class:`kp::Tensor` is the atomic unit in Kompute, and it is used primarily Algorithm ------- -The :class:`kp::Algorithm` consists primarily of the components required for shader code execution, including the relevant vk::DescriptorSet relatedresources as well as vk::Pipeline and all the relevant Vulkan resources as outlined in the architectural diagram. +The :class:`kp::Algorithm` consists primarily of the components required for shader code execution, including the relevant vk::DescriptorSet relatedresources as well as vk::Pipeline and all the relevant Vulkan SDK resources as outlined in the architectural diagram. .. image:: ../images/kompute-vulkan-architecture-algorithm.jpg :width: 100%