From cb0d7f7cf38974410abb3ff76563c5772f0f24f0 Mon Sep 17 00:00:00 2001 From: Alejandro Saucedo Date: Fri, 28 Aug 2020 16:13:48 +0100 Subject: [PATCH] Updated docstrings --- docs/CMakeLists.txt | 10 ++++++ src/Manager.cpp | 9 +++-- src/include/kompute/Manager.hpp | 14 ++++---- src/include/kompute/OpBase.hpp | 42 ++++++++++++++++++----- src/include/kompute/OpCreateTensor.hpp | 32 ++++++++++++++++++ src/include/kompute/OpMult.hpp | 46 +++++++++++++++++++++++--- src/include/kompute/Tensor.hpp | 8 +++++ 7 files changed, 135 insertions(+), 26 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index a045f2fa4..163befb87 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -55,3 +55,13 @@ add_custom_target(gensphinx ALL DEPENDS ${DOXYGEN_INDEX_FILE} COMMENT "Generating documentation with Sphinx") +# For completeness we also copy the output doxygen html files +file(COPY ${DOXYGEN_OUTPUT_DIR}/html/ + DESTINATION ${SPHINX_BUILD}/doxygen/) +#add_custom_target(includedoxygen ALL +# COMMAND ${CMAKE_COMMAND} +# -E copy_directory +# ${DOXYGEN_OUTPUT_DIR}/html/ +# ${SPHINX_BUILD}/doxygen/ +# DEPENDS gensphinx) + diff --git a/src/Manager.cpp b/src/Manager.cpp index 5dbc205d2..c7de4d9a5 100644 --- a/src/Manager.cpp +++ b/src/Manager.cpp @@ -74,8 +74,8 @@ std::weak_ptr Manager::getOrCreateManagedSequence(std::string sessionName) { SPDLOG_DEBUG("Kompute Manager creating Sequence object"); - std::unordered_map>::iterator - found = this->mManagedSequences.find(sessionName); + std::unordered_map>::iterator found = + this->mManagedSequences.find(sessionName); if (found == this->mManagedSequences.end()) { std::shared_ptr sq = @@ -84,10 +84,9 @@ Manager::getOrCreateManagedSequence(std::string sessionName) this->mComputeQueue, this->mComputeQueueFamilyIndex); sq->init(); - this->mManagedSequences.insert({sessionName, sq}); + this->mManagedSequences.insert({ sessionName, sq }); return sq; - } - else { + } else { return found->second; } } diff --git a/src/include/kompute/Manager.hpp b/src/include/kompute/Manager.hpp index 7ed0924d5..da49f133b 100644 --- a/src/include/kompute/Manager.hpp +++ b/src/include/kompute/Manager.hpp @@ -31,14 +31,14 @@ class Manager std::weak_ptr getOrCreateManagedSequence(std::string sessionName); template - void evalOp(std::vector> tensors, std::string sessionName = KP_DEFAULT_SESSION) + void evalOp(std::vector> tensors, + std::string sessionName = KP_DEFAULT_SESSION) { SPDLOG_DEBUG("Kompute Manager evalOp triggered"); - std::weak_ptr sqWeakPtr = - this->getOrCreateManagedSequence(sessionName); + std::weak_ptr sqWeakPtr = + this->getOrCreateManagedSequence(sessionName); - if (std::shared_ptr sq = sqWeakPtr.lock()) - { + if (std::shared_ptr sq = sqWeakPtr.lock()) { SPDLOG_DEBUG("Kompute Manager evalOp running sequence BEGIN"); sq->begin(); @@ -55,7 +55,6 @@ class Manager } private: - std::shared_ptr mInstance = nullptr; bool mFreeInstance = false; std::shared_ptr mPhysicalDevice = nullptr; @@ -66,7 +65,8 @@ class Manager std::shared_ptr mComputeQueue = nullptr; // Always owned resources - std::unordered_map> mManagedSequences; + std::unordered_map> + mManagedSequences; #if DEBUG vk::DebugReportCallbackEXT mDebugReportCallback; diff --git a/src/include/kompute/OpBase.hpp b/src/include/kompute/OpBase.hpp index 1511c821c..34443be4e 100644 --- a/src/include/kompute/OpBase.hpp +++ b/src/include/kompute/OpBase.hpp @@ -23,9 +23,15 @@ class OpBase OpBase() { SPDLOG_DEBUG("Compute OpBase base constructor"); } /** - * Default constructor with parameters that provides the bare minimum + * Default constructor with parameters that provides the bare minimum * requirements for the operations to be able to create and manage their * sub-components. + * + * @param physicalDevice Vulkan physical device used to find device queues + * @param device Vulkan logical device for passing to Algorithm + * @param commandBuffer Vulkan Command Buffer to record commands into + * @param tensors Tensors that are to be used in this operation + * @param freeTensors Whether operation manages the memory of the Tensors */ OpBase(std::shared_ptr physicalDevice, std::shared_ptr device, @@ -69,22 +75,40 @@ class OpBase } } + /** + * The init function is responsible for setting up all the resources and + * should be called after the Operation has been created. + */ virtual void init() = 0; + /** + * The record function is intended to only send a record command or run + * commands that are expected to record operations that are to be submitted + * as a batch into the GPU. + */ virtual void record() = 0; + /** + * Post submit is called after the Sequence has submitted the commands to + * the GPU for processing, and can be used to perform any tear-down steps + * required as the computation iteration finishes. + */ virtual void postSubmit() = 0; protected: - // Sometimes owned resources - std::vector> mTensors; - bool mFreeTensors = - false; // TODO: Provide granularity to specify which to free + // OPTIONALLY OWNED RESOURCES + std::vector> + mTensors; ///< Tensors referenced by operation that can be managed + ///< optionally by operation + bool mFreeTensors = false; ///< Explicit boolean that specifies whether the + ///< tensors are freed (if they are managed) - // Always external resources - std::shared_ptr mPhysicalDevice; - std::shared_ptr mDevice; - std::shared_ptr mCommandBuffer; + // NEVER OWNED RESOURCES + std::shared_ptr + mPhysicalDevice; ///< Vulkan Physical Device + std::shared_ptr mDevice; ///< Vulkan Logical Device + std::shared_ptr + mCommandBuffer; ///< Vulkan Command Buffer }; } // End namespace kp diff --git a/src/include/kompute/OpCreateTensor.hpp b/src/include/kompute/OpCreateTensor.hpp index 81171ef56..386bb0223 100644 --- a/src/include/kompute/OpCreateTensor.hpp +++ b/src/include/kompute/OpCreateTensor.hpp @@ -8,23 +8,55 @@ namespace kp { +/** + Operation that creates tensor and manages the memory of the components + created +*/ class OpCreateTensor : public OpBase { public: OpCreateTensor(); + /** + * Default constructor with parameters that provides the bare minimum + * requirements for the operations to be able to create and manage their + * sub-components. + * + * @param physicalDevice Vulkan physical device used to find device queues + * @param device Vulkan logical device for passing to Algorithm + * @param commandBuffer Vulkan Command Buffer to record commands into + * @param tensors Tensors that are to be used in this operation + * @param freeTensors Whether operation manages the memory of the Tensors + */ OpCreateTensor(std::shared_ptr physicalDevice, std::shared_ptr device, std::shared_ptr commandBuffer, std::vector>& tensors, bool freeTensors = true); + /** + * Default destructor which in this case expects the parent class to free + * the tensors + */ ~OpCreateTensor(); + /** + * In charge of initialising the primary Tensor as well as the staging + * tensor as required. It will only initialise a staging tensor if the + * Primary tensor is of type Device. + */ void init() override; + /** + * Records the copy command into the GPU memory from the staging or host + * memory depending on the type of tensor. + */ void record() override; + /** + * Performs a copy back into the main tensor to ensure that the data + * contained is the one that is now being stored in the GPU. + */ void postSubmit() override; private: diff --git a/src/include/kompute/OpMult.hpp b/src/include/kompute/OpMult.hpp index 2ceb303d2..b4e40d972 100644 --- a/src/include/kompute/OpMult.hpp +++ b/src/include/kompute/OpMult.hpp @@ -14,29 +14,66 @@ namespace kp { /** - Base algorithm based operation -*/ + * Operation that performs multiplication on two tensors and outpus on third + * tensor. The template parameters specify the processing GPU layout number of + * iterations for each x, y, z parameter. More specifically, this will be the + * input to ".dispatch(uint32_t tX, uint32_t tY, uint32_t, tZ)" + */ template class OpMult : public OpBase { public: /** - Constructor - */ + * Base constructor, should not be used unless explicitly intended. + */ OpMult(); + /** + * Default constructor with parameters that provides the bare minimum + * requirements for the operations to be able to create and manage their + * sub-components. + * + * @param physicalDevice Vulkan physical device used to find device queues + * @param device Vulkan logical device for passing to Algorithm + * @param commandBuffer Vulkan Command Buffer to record commands into + * @param tensors Tensors that are to be used in this operation + * @param freeTensors Whether operation manages the memory of the Tensors + */ OpMult(std::shared_ptr physicalDevice, std::shared_ptr device, std::shared_ptr commandBuffer, std::vector>& tensors, bool freeTensors = false); + /** + * Default destructor, which is in charge of destroying the algorithm + * components but does not destroy the underlying tensors + */ ~OpMult(); + /** + * The init function is responsible for ensuring that all of the tensors + * provided are aligned with requirements such as LHS, RHS and Output + * tensors, and creates the algorithm component which processes the + * computation. + */ void init() override; + /** + * This records the commands that are to be sent to the GPU. This includes + * the barriers that ensure the memory has been copied before going in and + * out of the shader, as well as the dispatch operation that sends the + * shader processing to the gpu. This function also records the GPU memory + * copy of the output data for the staging bufffer so it can be read by the + * host. + */ void record() override; + /** + * Executes after the recorded commands are submitted, and performs a copy + * of the GPU Device memory into the staging buffer so the output data can + * be retrieved. + */ void postSubmit() override; private: @@ -71,7 +108,6 @@ OpMult::OpMult() SPDLOG_DEBUG("Kompute OpMult constructor base"); } -// TODO: Remove physicalDevice from main initialiser template OpMult::OpMult(std::shared_ptr physicalDevice, std::shared_ptr device, diff --git a/src/include/kompute/Tensor.hpp b/src/include/kompute/Tensor.hpp index d6a5659b1..e9f5e261d 100644 --- a/src/include/kompute/Tensor.hpp +++ b/src/include/kompute/Tensor.hpp @@ -6,6 +6,14 @@ namespace kp { +/** + * Structured data used in GPU operations. + * + * Tensors are the base building block in Kompute to perform operations across + * GPUs. Each tensor would have a respective Vulkan memory and buffer, which + * woudl be used to store their respective data. The tensors can be used for GPU + * data storage or transfer. + */ class Tensor { public: