From 26b7abc63893a0e37bec6bb91878afd18c7a1ac9 Mon Sep 17 00:00:00 2001 From: "Jonathan R. Madsen" Date: Thu, 19 Oct 2023 03:47:27 -0500 Subject: [PATCH] Update README and workflows (#27) * Update README - Overview - Contributing - Build and install * Update workflows - branches reflect new amd-mainline and amd-staging names instead of main and develop [ROCm/rocprofiler-register commit: 40f37f9597d928213a81a4adfbd2414a8d464cb1] --- .../workflows/continuous-integration.yml | 4 +- .../.github/workflows/formatting.yml | 2 +- projects/rocprofiler-register/README.md | 62 ++++++++++++++++++- 3 files changed, 64 insertions(+), 4 deletions(-) diff --git a/projects/rocprofiler-register/.github/workflows/continuous-integration.yml b/projects/rocprofiler-register/.github/workflows/continuous-integration.yml index 4959f58ee0..2235140a6e 100644 --- a/projects/rocprofiler-register/.github/workflows/continuous-integration.yml +++ b/projects/rocprofiler-register/.github/workflows/continuous-integration.yml @@ -2,11 +2,11 @@ name: Continuous Integration on: push: - branches: [ main, develop ] + branches: [ amd-mainline, amd-staging ] paths-ignore: - '*.md' pull_request: - branches: [ main, develop ] + branches: [ amd-mainline, amd-staging ] paths-ignore: - '*.md' diff --git a/projects/rocprofiler-register/.github/workflows/formatting.yml b/projects/rocprofiler-register/.github/workflows/formatting.yml index 7cbbb93f75..7fca0a0777 100644 --- a/projects/rocprofiler-register/.github/workflows/formatting.yml +++ b/projects/rocprofiler-register/.github/workflows/formatting.yml @@ -4,7 +4,7 @@ name: Formatting on: workflow_dispatch: pull_request: - branches: [ main ] + branches: [ amd-mainline, amd-staging ] paths-ignore: - '.github/workflows/pull_*.yml' - '.github/workflows/linting.yml' diff --git a/projects/rocprofiler-register/README.md b/projects/rocprofiler-register/README.md index 8f8bcf1a62..5ce882f48e 100644 --- a/projects/rocprofiler-register/README.md +++ b/projects/rocprofiler-register/README.md @@ -1 +1,61 @@ -# rocprofiler-register \ No newline at end of file +# rocprofiler-register + +## Overview + +The rocprofiler-register library is a helper library that coordinates the modification of the intercept API table(s) of the HSA/HIP/ROCTx +runtime libraries by the ROCprofiler (v2) library. The purpose of this library is to provide a consistent and automated mechanism +of enabling performance analysis in the ROCm runtimes which does not rely on environment variables or unique methods for each runtime +library. + +When a runtime is initialized (either explicitly and lazily) and the intercept API table is constructed, it passes this API table to +rocprofiler-register. Rocprofiler-register scans the symbols in the address space and if it detects there is at least one visible symbol named +`rocprofiler_configure` (which is a function provided by tools), it passes the intercept API table to the rocprofiler library (dlopening +the rocprofiler library if it is not already loaded). The rocprofiler library then does an extensive scan for _all_ the instances of +the `rocprofiler_configure` symbols and invokes each of them. The `rocprofiler_configure` function (again, provided by a tool) returns +effectively tells rocprofiler which behaviors it wants to be notified about, features it wants to use (e.g. API tracing, kernel dispatch timing), +etc. + +## Contributing + +The default branch is `amd-mainline` but the only branch that should target that branch in a pull requests is the `amd-staging` branch. + +> _**All pull-requests should target the `amd-staging` branch**_ + +### Creating a feature branch + +```console +# fetch any updates +git fetch origin + +# switch to staging branch +git checkout amd-staging + +# update your copy of the staging branch +git pull --rebase + +# create your feature branch off of amd-staging +git checkout -b +``` + +In the event, your local clone of the repo has a `amd-staging` branch that diverges from the upstream branch, +do a hard reset of your local branch to match the upstream branch: `git reset --hard origin/amd-staging`. +Theoretically, you should never need to do this for `amd-mainline` but this can be applied to that +branch as well. + +### Pulling in updates to `amd-staging` to your feature branch + +Linear histories are preferred so if another PR is merged into `amd-staging` while your PR is still open, please +select the "Update with rebase" option (i.e. try to avoid a merge commit). From the command line, the git command +would be `git pull --rebase origin amd-staging`. + +## Build and Installation + +rocprofiler-register has a standard CMake build and install process. E.g. the following configure +rocprofiler-register to build with optimizations and without debug info in a `build-rocp-reg` subdirectory, +build using 4 jobs, and install to `/opt/rocprofiler-register`: + +```console +cmake -B build-rocp-reg . -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/rocprofiler-register +cmake --build build-rocp-reg --target all --parallel 4 +cmake --build build-rocp-reg --target install +```