Jonathan R. Madsen
40f37f9597
* Update README - Overview - Contributing - Build and install * Update workflows - branches reflect new amd-mainline and amd-staging names instead of main and develop
62 lines
2.9 KiB
Markdown
62 lines
2.9 KiB
Markdown
# 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 <feature-branch>
|
|
```
|
|
|
|
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
|
|
```
|