diff --git a/projects/rdc/.github/dependabot.yml b/projects/rdc/.github/dependabot.yml index 9cdf2d670c..d24c82f8f3 100644 --- a/projects/rdc/.github/dependabot.yml +++ b/projects/rdc/.github/dependabot.yml @@ -6,7 +6,12 @@ version: 2 updates: - package-ecosystem: "pip" # See documentation for possible values - directory: "/docs/.sphinx" # Location of package manifests + directory: "/docs/sphinx" # Location of package manifests open-pull-requests-limit: 10 schedule: interval: "daily" + labels: + - "documentation" + - "dependencies" + reviewers: + - "samjwu" diff --git a/projects/rdc/.readthedocs.yaml b/projects/rdc/.readthedocs.yaml index 43a0890c96..9e6678abe5 100644 --- a/projects/rdc/.readthedocs.yaml +++ b/projects/rdc/.readthedocs.yaml @@ -6,9 +6,13 @@ version: 2 sphinx: configuration: docs/conf.py -formats: [htmlzip] +formats: [htmlzip, pdf, epub] python: - version: "3.8" install: - - requirements: docs/.sphinx/requirements.txt + - requirements: docs/sphinx/requirements.txt + +build: + os: ubuntu-22.04 + tools: + python: "3.8" diff --git a/projects/rdc/README.md b/projects/rdc/README.md index 9e47777122..9882271a98 100644 --- a/projects/rdc/README.md +++ b/projects/rdc/README.md @@ -9,12 +9,13 @@ The ROCm™ Data Center Tool simplifies the administration and addresses key inf For up-to-date document and how to start using RDC from pre-built packages, please refer to the [**ROCm DataCenter Tool User Guide**](https://rocm.docs.amd.com/projects/rdc/en/latest/) -# Supported platforms +## Supported platforms + RDC can run on AMD ROCm supported platforms, please refer to the [List of Supported Operating Systems](https://rocm.docs.amd.com/en/latest/release/gpu_os_support.html) -# Building RDC from source +## Building RDC from source -## Dependencies +### Dependencies CMake 3.15 ## 3.15 or greater is required for gRPC g++ (5.4.0) @@ -43,136 +44,121 @@ The following tools are required for gRPC build & installation ### Download and build gRPC By default (without using CMAKE_INSTALL_PREFIX option), gRPC will install to /usr/local lib, include and bin directories. -It is highly recommended to install gRPC into a unique directory. +It is highly recommended to install gRPC into a unique directory. Below example installs gRPC into /opt/grpc -```bash -git clone -b v1.59.1 https://github.com/grpc/grpc --depth=1 --shallow-submodules --recurse-submodules -cd grpc -export GRPC_ROOT=/opt/grpc -cmake -B build \ - -DgRPC_INSTALL=ON \ - -DgRPC_BUILD_TESTS=OFF \ - -DBUILD_SHARED_LIBS=ON \ - -DCMAKE_INSTALL_PREFIX="$GRPC_ROOT" \ - -DCMAKE_INSTALL_LIBDIR=lib \ - -DCMAKE_BUILD_TYPE=Release -make -C build -j $(nproc) -sudo make -C build install -echo "$GRPC_ROOT" | sudo tee /etc/ld.so.conf.d/grpc.conf -``` + git clone -b v1.59.1 https://github.com/grpc/grpc --depth=1 --shallow-submodules --recurse-submodules + cd grpc + export GRPC_ROOT=/opt/grpc + cmake -B build \ + -DgRPC_INSTALL=ON \ + -DgRPC_BUILD_TESTS=OFF \ + -DBUILD_SHARED_LIBS=ON \ + -DCMAKE_INSTALL_PREFIX="$GRPC_ROOT" \ + -DCMAKE_INSTALL_LIBDIR=lib \ + -DCMAKE_BUILD_TYPE=Release + make -C build -j $(nproc) + sudo make -C build install + echo "$GRPC_ROOT" | sudo tee /etc/ld.so.conf.d/grpc.conf ## Building RDC Clone the RDC source code from GitHub and use CMake to build and install -```bash -git clone https://github.com/RadeonOpenCompute/rdc -cd rdc -mkdir -p build -# default installation location is /opt/rocm, specify with -DROCM_DIR or -DCMAKE_INSTALL_PREFIX -cmake -B build -DGRPC_ROOT="$GRPC_ROOT" -make -C build -j $(nproc) -make -C build install -``` + git clone https://github.com/RadeonOpenCompute/rdc + cd rdc + mkdir -p build + # default installation location is /opt/rocm, specify with -DROCM_DIR or -DCMAKE_INSTALL_PREFIX + cmake -B build -DGRPC_ROOT="$GRPC_ROOT" + make -C build -j $(nproc) + make -C build install ## Building RDC library only without gRPC (optional) If only the RDC libraries are needed (i.e. only "embedded mode" is required), the user can choose to not build rdci and rdcd. This will eliminate the need for gRPC and protoc. To build in this way, -DBUILD_STANDALONE=off should be passed on the the cmake command line: -```bash -cmake -B build -DBUILD_STANDALONE=off -``` + cmake -B build -DBUILD_STANDALONE=off ## Building RDC library without ROCM Run time (optional) The user can choose to not build RDC diagnostic ROCM Run time. This will eliminate the need for ROCM Run time. To build in this way, -DBUILD_ROCRTEST=off should be passed on the the cmake command line: -```bash -cmake -B build -DBUILD_ROCRTEST=off -``` + cmake -B build -DBUILD_ROCRTEST=off ## Update System Library Path -```bash -RDC_LIB_DIR=/opt/rocm/rdc/lib -GRPC_LIB_DIR=/opt/grpc/lib -echo -e "${GRPC_LIB_DIR}\n${GRPC_LIB_DIR}64" | sudo tee /etc/ld.so.conf.d/x86_64-librdc_client.conf -echo -e "${RDC_LIB_DIR}\n${RDC_LIB_DIR}64" | sudo tee -a /etc/ld.so.conf.d/x86_64-librdc_client.conf -ldconfig -``` + RDC_LIB_DIR=/opt/rocm/rdc/lib + GRPC_LIB_DIR=/opt/grpc/lib + echo -e "${GRPC_LIB_DIR}\n${GRPC_LIB_DIR}64" | sudo tee /etc/ld.so.conf.d/x86_64-librdc_client.conf + echo -e "${RDC_LIB_DIR}\n${RDC_LIB_DIR}64" | sudo tee -a /etc/ld.so.conf.d/x86_64-librdc_client.conf + ldconfig + +## Running RDC -# Running RDC RDC supports encrypted communications between clients and servers. The communication can be configured to be *authenticated* or *not authenticated*. The [**user guide**](https://rocm.docs.amd.com/projects/rdc/en/latest/) has information on how to generate and install SSL keys and certificates for authentication. By default, authentication is enabled. ## Starting ROCm™ Data Center Daemon (RDCD) + For an RDC client application to monitor and/or control a remote system, the RDC server daemon, *rdcd*, must be running on the remote system. *rdcd* can be configured to run with (a) full-capabilities which includes ability to set or change GPU configuration or (b) monitor-only capabilities which limits to monitoring GPU metrics. ### Start RDCD from command-line + When *rdcd* is started from a command-line the *capabilities* are determined by privilege of the *user* starting *rdcd* -```bash -## NOTE: Replace /opt/rocm with specific rocm version if needed + ## NOTE: Replace /opt/rocm with specific rocm version if needed -## To run with authentication. Ensure SSL keys are setup properly -## version will be the version number(ex:3.10.0) of ROCm where RDC was packaged with -/opt/rocm/rdc/bin/rdcd ## rdcd is started with monitor-only capabilities -sudo /opt/rocm/rdc/bin/rdcd ## rdcd is started will full-capabilities + ## To run with authentication. Ensure SSL keys are setup properly + ## version will be the version number(ex:3.10.0) of ROCm where RDC was packaged with + /opt/rocm/rdc/bin/rdcd ## rdcd is started with monitor-only capabilities + sudo /opt/rocm/rdc/bin/rdcd ## rdcd is started will full-capabilities -## To run without authentication. SSL key & certificates are not required. -## version will be the version number(ex:3.10.0) of ROCm where RDC was packaged with -/opt/rocm/rdc/bin/rdcd -u ## rdcd is started with monitor-only capabilities -sudo /opt/rocm/rdc/bin/rdcd -u ## rdcd is started will full-capabilities -``` + ## To run without authentication. SSL key & certificates are not required. + ## version will be the version number(ex:3.10.0) of ROCm where RDC was packaged with + /opt/rocm/rdc/bin/rdcd -u ## rdcd is started with monitor-only capabilities + sudo /opt/rocm/rdc/bin/rdcd -u ## rdcd is started will full-capabilities ### Start RDCD using systemd + *rdcd* can be started by using the systemctl command. You can copy /opt/rocm/rdc/lib/rdc.service, which is installed with RDC, to the systemd folder. This file has 2 lines that control what *capabilities* with which *rdcd* will run. If left uncommented, rdcd will run with full-capabilities. -```bash -## file: /opt/rocm/rdc/lib/rdc.service -## Comment the following two lines to run with monitor-only capabilities -CapabilityBoundingSet=CAP_DAC_OVERRIDE -AmbientCapabilities=CAP_DAC_OVERRIDE -``` + ## file: /opt/rocm/rdc/lib/rdc.service + ## Comment the following two lines to run with monitor-only capabilities + CapabilityBoundingSet=CAP_DAC_OVERRIDE + AmbientCapabilities=CAP_DAC_OVERRIDE -```bash -systemctl start rdc ## start rdc as systemd service -``` + systemctl start rdc ## start rdc as systemd service ## Invoke RDC using ROCm™ Data Center Interface (RDCI) + RDCI provides command-line interface to all RDC features. This CLI can be run locally or remotely. Refer to [**user guide**](https://rocm.docs.amd.com/projects/rdc/en/latest/user_guide/features.html) for the current list of features. -```bash -## sample rdci commands to test RDC functionality -## discover devices in a local or remote compute node -## NOTE: option -u (for unauthenticated) is required if rdcd was started in this mode -## Assuming that rdc is installed into /opt/rocm + ## sample rdci commands to test RDC functionality + ## discover devices in a local or remote compute node + ## NOTE: option -u (for unauthenticated) is required if rdcd was started in this mode + ## Assuming that rdc is installed into /opt/rocm -cd /opt/rocm/rdc/bin -./rdci discovery -l <-u> ## list available GPUs in localhost -./rdci discovery -l <-u> ## list available GPUs in host machine -./rdci dmon <-u> -l ## list most GPU counters -# assuming rdcd is running locally, using -u instead of -./rdci dmon -u --list-all ## list all GPU counters -./rdci dmon -u -i 0 -c 1 -e 100 ## monitor field 100 on gpu 0 for count of 1 -./rdci dmon -u -i 0 -c 1 -e 1,2 ## monitor fields 1,2 on gpu 0 for count of 1 -``` + cd /opt/rocm/rdc/bin + ./rdci discovery -l <-u> ## list available GPUs in localhost + ./rdci discovery -l <-u> ## list available GPUs in host machine + ./rdci dmon <-u> -l ## list most GPU counters + # assuming rdcd is running locally, using -u instead of + ./rdci dmon -u --list-all ## list all GPU counters + ./rdci dmon -u -i 0 -c 1 -e 100 ## monitor field 100 on gpu 0 for count of 1 + ./rdci dmon -u -i 0 -c 1 -e 1,2 ## monitor fields 1,2 on gpu 0 for count of 1 ## Troubleshooting rdcd - Log messages that can provide useful debug information. If rdcd was started as a systemd service, then use journalctl to view rdcd logs -```bash -sudo journalctl -u rdc -``` + + sudo journalctl -u rdc To run rdcd with debug log from command-line use version will be the version number(ex:3.10.0) of ROCm where RDC was packaged with -```bash -RDC_LOG=DEBUG /opt/rocm/rdc/bin/rdcd -``` + + RDC_LOG=DEBUG /opt/rocm/rdc/bin/rdcd RDC_LOG=DEBUG also works on rdci diff --git a/projects/rdc/docs/.sphinx/requirements.in b/projects/rdc/docs/.sphinx/requirements.in deleted file mode 100644 index b8366edf9e..0000000000 --- a/projects/rdc/docs/.sphinx/requirements.in +++ /dev/null @@ -1 +0,0 @@ -rocm-docs-core==0.11.0 diff --git a/projects/rdc/docs/conf.py b/projects/rdc/docs/conf.py index a2b1c5ae59..7422002472 100644 --- a/projects/rdc/docs/conf.py +++ b/projects/rdc/docs/conf.py @@ -6,9 +6,19 @@ from rocm_docs import ROCmDocs + +# for PDF output on Read the Docs +project = "ROCm Data Center Documentation" +author = "Advanced Micro Devices, Inc." +copyright = "Copyright (c) 2023 Advanced Micro Devices, Inc. All rights reserved." + +external_toc_path = "./sphinx/_toc.yml" + docs_core = ROCmDocs("ROCm Data Center Documentation") -docs_core.run_doxygen() +docs_core.run_doxygen(doxygen_root="doxygen", doxygen_path="doxygen/xml") docs_core.setup() +external_projects_current_project = "rdc" + for sphinx_var in ROCmDocs.SPHINX_VARS: globals()[sphinx_var] = getattr(docs_core, sphinx_var) diff --git a/projects/rdc/docs/doxygen/.gitignore b/projects/rdc/docs/doxygen/.gitignore new file mode 100644 index 0000000000..431b205665 --- /dev/null +++ b/projects/rdc/docs/doxygen/.gitignore @@ -0,0 +1,2 @@ +html/ +xml/ diff --git a/projects/rdc/docs/.doxygen/Doxyfile b/projects/rdc/docs/doxygen/Doxyfile similarity index 99% rename from projects/rdc/docs/.doxygen/Doxyfile rename to projects/rdc/docs/doxygen/Doxyfile index 7f6c076a9d..5f71b8e365 100644 --- a/projects/rdc/docs/.doxygen/Doxyfile +++ b/projects/rdc/docs/doxygen/Doxyfile @@ -61,7 +61,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = docBin +OUTPUT_DIRECTORY = . # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and diff --git a/projects/rdc/docs/license.md b/projects/rdc/docs/license.md new file mode 100644 index 0000000000..89819476ee --- /dev/null +++ b/projects/rdc/docs/license.md @@ -0,0 +1,4 @@ +# License + +```{include} ../LICENSE +``` diff --git a/projects/rdc/docs/.sphinx/_toc.yml.in b/projects/rdc/docs/sphinx/_toc.yml.in similarity index 91% rename from projects/rdc/docs/.sphinx/_toc.yml.in rename to projects/rdc/docs/sphinx/_toc.yml.in index eabf354c83..9b8c2922af 100644 --- a/projects/rdc/docs/.sphinx/_toc.yml.in +++ b/projects/rdc/docs/sphinx/_toc.yml.in @@ -17,3 +17,6 @@ subtrees: - caption: API Reference entries: - file: api_ref +- caption: About + entries: + - file: license diff --git a/projects/rdc/docs/sphinx/requirements.in b/projects/rdc/docs/sphinx/requirements.in new file mode 100644 index 0000000000..84662ab7e8 --- /dev/null +++ b/projects/rdc/docs/sphinx/requirements.in @@ -0,0 +1 @@ +rocm-docs-core==0.28.0 diff --git a/projects/rdc/docs/.sphinx/requirements.txt b/projects/rdc/docs/sphinx/requirements.txt similarity index 95% rename from projects/rdc/docs/.sphinx/requirements.txt rename to projects/rdc/docs/sphinx/requirements.txt index c2302d0aa8..fd9e341fb7 100644 --- a/projects/rdc/docs/.sphinx/requirements.txt +++ b/projects/rdc/docs/sphinx/requirements.txt @@ -54,8 +54,6 @@ jinja2==3.1.2 # via # myst-parser # sphinx -linkify-it-py==1.0.3 - # via myst-parser markdown-it-py==2.2.0 # via # mdit-py-plugins @@ -66,7 +64,7 @@ mdit-py-plugins==0.3.5 # via myst-parser mdurl==0.1.2 # via markdown-it-py -myst-parser[linkify]==1.0.0 +myst-parser==1.0.0 # via rocm-docs-core packaging==23.0 # via @@ -100,7 +98,7 @@ requests==2.28.2 # via # pygithub # sphinx -rocm-docs-core==0.11.0 +rocm-docs-core==0.28.0 # via -r requirements.in smmap==5.0.0 # via gitdb @@ -143,8 +141,6 @@ sphinxcontrib-serializinghtml==1.1.5 # via sphinx typing-extensions==4.5.0 # via pydata-sphinx-theme -uc-micro-py==1.0.1 - # via linkify-it-py urllib3==1.26.15 # via requests wrapt==1.15.0