From 831575b1f52f911ea2e76bc838b08135824d1b04 Mon Sep 17 00:00:00 2001 From: Lisa Delaney Date: Mon, 28 Aug 2023 16:43:13 -0600 Subject: [PATCH 1/2] restructure layout --- docs/.gitignore | 3 +- docs/.sphinx/_toc.yml.in | 42 +++++++----------- docs/index.md | 94 ++++++++-------------------------------- 3 files changed, 36 insertions(+), 103 deletions(-) diff --git a/docs/.gitignore b/docs/.gitignore index 8f68c925a3..48657d2c08 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -2,4 +2,5 @@ /_doxygen /_images /_static -/_templates \ No newline at end of file +/_templates +_build \ No newline at end of file diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in index 73b689b652..2d2676d375 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/.sphinx/_toc.yml.in @@ -1,36 +1,26 @@ root: index subtrees: -- caption: User Reference +- caption: Conceptual entries: - - file: .doxygen/docBin/html/index - - file: reference/programming_model - - file: reference/kernel_language - - file: reference/math_api - - file: reference/glossary - - file: reference/deprecated_api_list -- caption: User How to Guides + - file: user_guide/hip_rtc + - file: user_guide/programming_manual +- caption: How-to entries: - file: how_to_guides/install.md -- caption: User Tutorials - entries: - - file: tutorials/saxpy.md -- caption: Developer How to Guides - entries: - file: developer_guide/build -- caption: Legacy Reference + - file: how_to_guides/debugging + - file: user_guide/hip_porting_guide +- caption: Reference entries: + - file: .doxygen/docBin/html/index + - file: reference/kernel_language + - file: reference/math_api + - file: reference/deprecated_api_list - file: reference/terms -- caption: Legacy User Guide - entries: - - file: user_guide/programming_manual - - file: user_guide/hip_rtc - - file: user_guide/faq -- caption: Legacy How to Guides + - file: developer_guide/logging +- caption: Tutorials entries: - - file: how_to_guides/debugging.md - - file: user_guide/hip_porting_guide - - file: user_guide/hip_porting_driver_api -- caption: Legacy Developer Guide + - file: tutorials/saxpy +- caption: Additional resources entries: - - file: developer_guide/logging - - file: developer_guide/contributing.md \ No newline at end of file + - file: developer_guide/contributing diff --git a/docs/index.md b/docs/index.md index 1de30277b5..918ab26a2d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,100 +1,42 @@ -# HIP Documentation +# HIP Runtime documentation -HIP is a C++ runtime API and kernel language that allows developers to create -portable applications for AMD and NVIDIA GPUs from single source code. +HIP Runtime is a C++ API and kernel language that you can use to create portable applications for +AMD and NVIDIA GPUs from single source code. -## Programmer Manual - -These documents are targeted at authors of HIP libraries and applications. +If you want to contribute to the HIP Runtime documentation, first review our +{doc}`/developer_guide/contributing`. ::::{grid} 1 1 2 2 :gutter: 1 -:::{grid-item-card} Reference - -- {doc}`/.doxygen/docBin/html/index` - - {doc}`/.doxygen/docBin/html/modules` -- {doc}`/reference/kernel_language` -- {doc}`/reference/math_api` -- {doc}`/reference/deprecated_api_list` - -::: +:::{grid-item-card} Conceptual -:::{grid-item-card} Understand HIP +- {doc}`/user_guide/hip_rtc` +- {doc}`/user_guide/programming_manual` ::: -:::{grid-item-card} How-to Guides +:::{grid-item-card} How-to - {doc}`/how_to_guides/install` - -::: - -:::{grid-item-card} Tutorials - -- {doc}`/tutorials/saxpy` - -::: - -:::: - -## Contributor Manual - -These documents are targeted at authors contributing to the HIP runtime and -the accompanying host/device compiler. - -::::{grid} 1 1 2 2 -:gutter: 1 - -:::{grid-item-card} Reference -::: - -:::{grid-item-card} Background -::: - -:::{grid-item-card} How-to Guides - - {doc}`/developer_guide/build` - -::: - -:::{grid-item-card} Tutorials -::: - -:::: - -## Legacy Content - -Materials listed here don't fit well the new documentation system and will be -removed once their contents are appropriately covered. - -::::{grid} 1 1 2 2 -:gutter: 1 - -:::{grid-item-card} User Guide - -- {doc}`/user_guide/programming_manual` -- {doc}`/user_guide/hip_rtc` -- {doc}`/user_guide/faq` - -::: - -:::{grid-item-card} How to Guides - - {doc}`/how_to_guides/debugging` - +- {doc}`/user_guide/hip_porting_guide` ::: :::{grid-item-card} Reference +- {doc}`/.doxygen/docBin/html/index` +- {doc}`/.doxygen/docBin/html/modules` +- {doc}`/reference/kernel_language` +- {doc}`/reference/math_api` +- {doc}`/reference/deprecated_api_list` - {doc}`/reference/terms` - +- {doc}`/developer_guide/logging` ::: -:::{grid-item-card} Developer Guide - -- {doc}`/developer_guide/logging` -- {doc}`/developer_guide/contributing` +:::{grid-item-card} Tutorials +- {doc}`/tutorials/saxpy` ::: :::: From 7693cd16f5ece9875b2f2788902682bb444987a2 Mon Sep 17 00:00:00 2001 From: Lisa Delaney Date: Wed, 30 Aug 2023 15:53:45 -0600 Subject: [PATCH 2/2] reorganize files for new structure --- README.md | 23 +++++++++---------- docs/.gitignore | 5 ++-- docs/.sphinx/_toc.yml.in | 17 +++++++------- .../contributing.md | 0 .../faq.md | 2 +- docs/{user_guide => conceptual}/hip_rtc.md | 0 .../porting_driver.md} | 0 .../programming_manual.md | 2 +- docs/conf.py | 2 +- docs/{developer_guide => how_to}/build.md | 0 docs/{how_to_guides => how_to}/debugging.md | 0 docs/{how_to_guides => how_to}/install.md | 2 +- .../porting.md} | 0 docs/index.md | 18 +++++++-------- .../{developer_guide => reference}/logging.md | 0 docs/tutorials/saxpy.md | 2 +- include/hip/hip_ext.h | 2 +- include/hip/hip_runtime_api.h | 2 +- 18 files changed, 38 insertions(+), 39 deletions(-) rename docs/{developer_guide => additional_resources}/contributing.md (100%) rename docs/{user_guide => additional_resources}/faq.md (99%) rename docs/{user_guide => conceptual}/hip_rtc.md (100%) rename docs/{user_guide/hip_porting_driver_api.md => conceptual/porting_driver.md} (100%) rename docs/{user_guide => conceptual}/programming_manual.md (99%) rename docs/{developer_guide => how_to}/build.md (100%) rename docs/{how_to_guides => how_to}/debugging.md (100%) rename docs/{how_to_guides => how_to}/install.md (96%) rename docs/{user_guide/hip_porting_guide.md => how_to/porting.md} (100%) rename docs/{developer_guide => reference}/logging.md (100%) diff --git a/README.md b/README.md index d5fb37e805..06bdfae064 100644 --- a/README.md +++ b/README.md @@ -34,16 +34,15 @@ HIP releases are typically naming convention for each ROCM release to help diffe This type of release is typically made once a month.* ## More Info: -- [Installation](docs/how_to_guides/install.md) -- [HIP FAQ](docs/user_guide/faq.md) +- [Installation](docs/how_to/install.md) - [HIP Kernel Language](docs/reference/kernel_language.md) -- [HIP Porting Guide](docs/user_guide/hip_porting_guide.md) -- [HIP Porting Driver Guide](docs/user_guide/hip_porting_driver_api.md) -- [HIP Programming Guide](docs/user_guide/programming_manual.md) -- [HIP Logging ](docs/developer_guide/logging.md) -- [Building HIP From Source](docs/developer_guide/build.md) -- [HIP Debugging ](docs/how_to_guides/debugging.md) -- [HIP RTC](docs/user_guide/hip_rtc.md) +- [HIP Porting Guide](docs/how_to/hip_porting_guide.md) +- [HIP Porting Driver Guide](docs/conceptual/porting_driver.md) +- [HIP Programming Guide](docs/conceptual/programming_manual.md) +- [HIP Logging ](docs/reference/logging.md) +- [Building HIP From Source](docs/how_to/build.md) +- [HIP Debugging ](docs/how_to/debugging.md) +- [HIP RTC](docs/conceptual/hip_rtc.md) - [HIP Terminology](docs/reference/terms.md) (including Rosetta Stone of GPU computing terms across CUDA/HIP/OpenCL) - [HIPIFY](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/amd-staging/README.md) - Supported CUDA APIs: @@ -56,12 +55,12 @@ HIP releases are typically naming convention for each ROCM release to help diffe * [cuDNN](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/master/doc/markdown/CUDNN_API_supported_by_HIP.md) * [cuFFT](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/master/doc/markdown/CUFFT_API_supported_by_HIP.md) * [cuSPARSE](https://github.com/ROCm-Developer-Tools/HIPIFY/blob/master/doc/markdown/CUSPARSE_API_supported_by_HIP.md) -- [Developer/CONTRIBUTING Info](docs/developer_guide/contributing.md) +- [Developer/CONTRIBUTING Info](docs/additional_resources/contributing.md) - [Release Notes](RELEASE.md) ## How do I get set up? -See the [Installation](docs/how_to_guides/install.md) notes. +See the [Installation](docs/how_to/install.md) notes. ## Simple Example The HIP API includes functions such as hipMalloc, hipMemcpy, and hipFree. @@ -131,7 +130,7 @@ cd samples/01_Intro/square # follow README / blog steps to hipify the application. ``` -* Guide to [Porting a New Cuda Project](docs/user_guide/hip_porting_guide.md/"Porting a New CUDA Project") +* Guide to [Porting a New Cuda Project](docs/how_to/porting.md/"Porting a New CUDA Project") ## More Examples diff --git a/docs/.gitignore b/docs/.gitignore index 48657d2c08..de28ffb8a5 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,6 +1,5 @@ -/_build +_build /_doxygen /_images /_static -/_templates -_build \ No newline at end of file +/_templates \ No newline at end of file diff --git a/docs/.sphinx/_toc.yml.in b/docs/.sphinx/_toc.yml.in index 2d2676d375..3f4b2b8b56 100644 --- a/docs/.sphinx/_toc.yml.in +++ b/docs/.sphinx/_toc.yml.in @@ -2,25 +2,26 @@ root: index subtrees: - caption: Conceptual entries: - - file: user_guide/hip_rtc - - file: user_guide/programming_manual + - file: conceptual/hip_rtc + - file: conceptual/programming_manual - caption: How-to entries: - - file: how_to_guides/install.md - - file: developer_guide/build - - file: how_to_guides/debugging - - file: user_guide/hip_porting_guide + - file: how_to/install + - file: how_to/build + - file: how_to/debugging + - file: how_to/porting - caption: Reference entries: - file: .doxygen/docBin/html/index + - file: reference/programming_model - file: reference/kernel_language - file: reference/math_api - file: reference/deprecated_api_list - file: reference/terms - - file: developer_guide/logging + - file: reference/logging - caption: Tutorials entries: - file: tutorials/saxpy - caption: Additional resources entries: - - file: developer_guide/contributing + - file: additional_resources/contributing diff --git a/docs/developer_guide/contributing.md b/docs/additional_resources/contributing.md similarity index 100% rename from docs/developer_guide/contributing.md rename to docs/additional_resources/contributing.md diff --git a/docs/user_guide/faq.md b/docs/additional_resources/faq.md similarity index 99% rename from docs/user_guide/faq.md rename to docs/additional_resources/faq.md index 6f9a8af744..87f1dce50a 100644 --- a/docs/user_guide/faq.md +++ b/docs/additional_resources/faq.md @@ -195,7 +195,7 @@ hipCUResultTohipError If platform portability is important, use #ifdef __HIP_PLATFORM_NVIDIA__ to guard the CUDA-specific code. ## How do I trace HIP application flow? -See {doc}`/developer_guide/logging` for more information. +See {doc}`/reference/logging` for more information. ## What is maximum limit of kernel launching parameter? Product of block.x, block.y, and block.z should be less than 1024. diff --git a/docs/user_guide/hip_rtc.md b/docs/conceptual/hip_rtc.md similarity index 100% rename from docs/user_guide/hip_rtc.md rename to docs/conceptual/hip_rtc.md diff --git a/docs/user_guide/hip_porting_driver_api.md b/docs/conceptual/porting_driver.md similarity index 100% rename from docs/user_guide/hip_porting_driver_api.md rename to docs/conceptual/porting_driver.md diff --git a/docs/user_guide/programming_manual.md b/docs/conceptual/programming_manual.md similarity index 99% rename from docs/user_guide/programming_manual.md rename to docs/conceptual/programming_manual.md index 827a62af67..7e584d7b51 100644 --- a/docs/user_guide/programming_manual.md +++ b/docs/conceptual/programming_manual.md @@ -129,7 +129,7 @@ HIP now supports runtime compilation (hipRTC), the usage of which will provide t hipRTC APIs accept HIP source files in character string format as input parameters and create handles of programs by compiling the HIP source files without spawning separate processes. For more details on hipRTC APIs, refer to HIP-API.pdf in GitHub (https://docs.amd.com/category/api_documentation). -For Linux developers, the link here(https://github.com/ROCm-Developer-Tools/hip-tests/blob/develop/samples/2_Cookbook/23_cmake_hiprtc/saxpy.cpp) shows an example how to program HIP application using runtime compilation mechanism, and detail hipRTC programming guide is also available in Github (https://github.com/ROCm-Developer-Tools/HIP/blob/develop/docs/user_guide/hip_rtc.md). +For Linux developers, the link here(https://github.com/ROCm-Developer-Tools/hip-tests/blob/develop/samples/2_Cookbook/23_cmake_hiprtc/saxpy.cpp) shows an example how to program HIP application using runtime compilation mechanism, and detail hipRTC programming guide is also available in Github (https://github.com/ROCm-Developer-Tools/HIP/blob/develop/docs/conceptual/hip_rtc.md). ## HIP Graph HIP graph is supported. For more details, refer to the HIP API Guide. diff --git a/docs/conf.py b/docs/conf.py index 62b6736eba..8e9b9a35eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,7 +7,7 @@ from rocm_docs import ROCmDocs from typing import Any, Dict, List -docs_core = ROCmDocs("HIP Documentation") +docs_core = ROCmDocs("HIP Runtime documentation") docs_core.run_doxygen() docs_core.enable_api_reference() docs_core.setup() diff --git a/docs/developer_guide/build.md b/docs/how_to/build.md similarity index 100% rename from docs/developer_guide/build.md rename to docs/how_to/build.md diff --git a/docs/how_to_guides/debugging.md b/docs/how_to/debugging.md similarity index 100% rename from docs/how_to_guides/debugging.md rename to docs/how_to/debugging.md diff --git a/docs/how_to_guides/install.md b/docs/how_to/install.md similarity index 96% rename from docs/how_to_guides/install.md rename to docs/how_to/install.md index dc496c02a8..54eaf63c88 100644 --- a/docs/how_to_guides/install.md +++ b/docs/how_to/install.md @@ -48,6 +48,6 @@ Run hipconfig (instructions below assume default installation path): # How to build HIP from source Developers can build HIP from source on either AMD or NVIDIA platforms, see -detailed instructions at [building HIP from source](../developer_guide/build.md). +detailed instructions at [building HIP from source](../how_to/build.md). diff --git a/docs/user_guide/hip_porting_guide.md b/docs/how_to/porting.md similarity index 100% rename from docs/user_guide/hip_porting_guide.md rename to docs/how_to/porting.md diff --git a/docs/index.md b/docs/index.md index 918ab26a2d..3c455f13f9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,34 +4,34 @@ HIP Runtime is a C++ API and kernel language that you can use to create portable AMD and NVIDIA GPUs from single source code. If you want to contribute to the HIP Runtime documentation, first review our -{doc}`/developer_guide/contributing`. +{doc}`/additional_resources/contributing`. ::::{grid} 1 1 2 2 :gutter: 1 :::{grid-item-card} Conceptual -- {doc}`/user_guide/hip_rtc` -- {doc}`/user_guide/programming_manual` +- {doc}`/conceptual/hip_rtc` +- {doc}`/conceptual/programming_manual` ::: :::{grid-item-card} How-to -- {doc}`/how_to_guides/install` -- {doc}`/developer_guide/build` -- {doc}`/how_to_guides/debugging` -- {doc}`/user_guide/hip_porting_guide` +- {doc}`/how_to/install` +- {doc}`/how_to/build` +- {doc}`/how_to/debugging` +- {doc}`/how_to/porting` ::: :::{grid-item-card} Reference - {doc}`/.doxygen/docBin/html/index` -- {doc}`/.doxygen/docBin/html/modules` +- {doc}`/reference/programming_model` - {doc}`/reference/kernel_language` - {doc}`/reference/math_api` - {doc}`/reference/deprecated_api_list` - {doc}`/reference/terms` -- {doc}`/developer_guide/logging` +- {doc}`/reference/logging` ::: :::{grid-item-card} Tutorials diff --git a/docs/developer_guide/logging.md b/docs/reference/logging.md similarity index 100% rename from docs/developer_guide/logging.md rename to docs/reference/logging.md diff --git a/docs/tutorials/saxpy.md b/docs/tutorials/saxpy.md index 1fed2ce118..20d6aff287 100644 --- a/docs/tutorials/saxpy.md +++ b/docs/tutorials/saxpy.md @@ -11,7 +11,7 @@ In order to follow this tutorial you will need properly installed drivers and a HIP compiler toolchain to compile your code. Because HIP provided by ROCm supports compiling and running on Linux and Windows with AMD and NVIDIA GPUs alike, the combination of install instructions are more then worth covering as -part of this tutorial. Please refer to {doc}`/how_to_guides/install` on how to +part of this tutorial. Please refer to {doc}`/how_to/install` on how to install HIP development packages. ## Heterogenous Programming diff --git a/include/hip/hip_ext.h b/include/hip/hip_ext.h index 09e9cf8b95..8346af9f6f 100644 --- a/include/hip/hip_ext.h +++ b/include/hip/hip_ext.h @@ -50,7 +50,7 @@ THE SOFTWARE. * @param [in] extra Pointer to kernel arguments. These are passed directly to the kernel and * must be in the memory layout and alignment expected by the kernel. * All passed arguments must be naturally aligned according to their type. The memory address of each - * argument should be a multiple of its size in bytes. Please refer to hip_porting_driver_api.md + * argument should be a multiple of its size in bytes. Please refer to porting_driver.md * for sample usage. * @param [in] startEvent If non-null, specified event will be updated to track the start time of * the kernel launch. The event must be created before calling this API. diff --git a/include/hip/hip_runtime_api.h b/include/hip/hip_runtime_api.h index dc2edb0273..ded7a0de43 100644 --- a/include/hip/hip_runtime_api.h +++ b/include/hip/hip_runtime_api.h @@ -4984,7 +4984,7 @@ hipError_t hipModuleLoadDataEx(hipModule_t* module, const void* image, unsigned * @param [in] extra Pointer to kernel arguments. These are passed directly to the kernel and * must be in the memory layout and alignment expected by the kernel. * All passed arguments must be naturally aligned according to their type. The memory address of each - * argument should be a multiple of its size in bytes. Please refer to hip_porting_driver_api.md + * argument should be a multiple of its size in bytes. Please refer to porting_driver.md * for sample usage. * * Please note, HIP does not support kernel launch with total work items defined in dimension with