[rocprofv3] Use -P for collection period shorthand option (#356)

* [rocprofv3] Use -P for collection period option

- Reserve -p for profiler attachment

* Update changelog

---------

Co-authored-by: Jonathan R. Madsen <jonathanrmadsen@gmail.com>

CHANGELOG.md

@@ -177,11 +177,11 @@ Full documentation for ROCprofiler-SDK is available at [rocm.docs.amd.com/projec
     - type-relative == logical_node_type_id
 - Added MI300 stochastic (hardware-based) PC sampling support in ROCProfiler-SDK and ROCProfV3
 
-
 ### Changed
 
 - SDK no longer creates a background thread when every tool returns a nullptr from `rocprofiler_configure`.
 - Updated disassembly.hpp's vaddr-to-file-offset mapping to use the dedicated comgr API.
+- rocprofv3 shorthand argument for `--collection-period` is now `-P` (upper-case) as `-p` (lower-case) is reserved for later use
 
 ### Resolved issues
 

source/bin/rocprofv3.py

@@ -200,6 +200,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins
         description="ROCProfilerV3 Run Script",
         usage="%(prog)s [options] -- <application> [application options]",
         epilog=usage_examples,
+        allow_abbrev=False,
         formatter_class=format_help(argparse.RawTextHelpFormatter),
     )
 
@@ -501,7 +502,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins
         type=str,
     )
     filter_options.add_argument(
-        "-p",
+        "-P",
         "--collection-period",
         help="The times are specified in seconds by default, but the unit can be changed using the `--collection-period-unit` option. Start Delay Time is the time in seconds before the collection begins, Collection Time is the duration in seconds for which data is collected, and Rate is the number of times the cycle is repeated. A repeat of 0 indicates that the cycle will repeat indefinitely. Users can specify multiple configurations, each defined by a triplet in the format `start_delay:collection_time:repeat`",
         nargs="+",
@@ -511,7 +512,7 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins
     )
     filter_options.add_argument(
         "--collection-period-unit",
-        help="To change the unit used in `--collection-period` or `-p`, you can specify the desired unit using the `--collection-period-unit` option. The available units are `hour` for hours, `min` for minutes, `sec` for seconds, `msec` for milliseconds, `usec` for microseconds, and `nsec` for nanoseconds",
+        help="To change the unit used in `--collection-period` or `-P`, you can specify the desired unit using the `--collection-period-unit` option. The available units are `hour` for hours, `min` for minutes, `sec` for seconds, `msec` for milliseconds, `usec` for microseconds, and `nsec` for nanoseconds",
         nargs=1,
         default=["sec"],
         type=str,
@@ -640,6 +641,16 @@ For MPI applications (or other job launchers such as SLURM), place rocprofv3 ins
         metavar="KB",
     )
 
+    reserved_options = parser.add_argument_group("Reserved options")
+    reserved_options.add_argument(
+        "-p",
+        "--pid",
+        help=argparse.SUPPRESS,
+        type=str,
+        nargs="+",
+        default=None,
+    )
+
     if args is None:
         args = sys.argv[1:]
 
@@ -886,6 +897,13 @@ def run(app_args, args, **kwargs):
     use_execv = kwargs.get("use_execv", True)
     app_pass = kwargs.get("pass_id", None)
 
+    if args.pid is not None:
+        fatal_error(
+            """The -p shorthand option for --collection-period is now an upper-case -P
+                    In the future, rocprofv3 plans to support debugger-like process attachment and -p
+                    is de-facto standard shorthand option for this feature"""
+        )
+
     def setattrifnone(obj, attr, value):
         if getattr(obj, f"{attr}") is None:
             setattr(obj, f"{attr}", value)

source/docs/conceptual/comparing-with-legacy-tools.rst

@@ -367,7 +367,7 @@ ROCprofiler-SDK introduces a new command-line tool, `rocprofv3`, which is a more
      - Trace Period
      - `--trace-period`
      - `-tp | --trace-period`
-     - `-p  |--collection-period`,`--collection-period-unit`
+     - `-P  |--collection-period`,`--collection-period-unit`
      - Users can specify multiple configurations, each defined by a triplet in the format `start_delay:collection_time:repeat`, with the ability to change the unit of time in the given configurations.
      -
    * - Trace Control options

source/docs/how-to/using-rocprofv3.rst

@@ -143,13 +143,13 @@ The following table lists the commonly used ``rocprofv3`` command-line options c
      - | ``--kernel-include-regex`` REGULAR_EXPRESSION |br| |br| |br| |br|
        | ``--kernel-exclude-regex`` REGULAR_EXPRESSION |br| |br| |br| |br|
        | ``--kernel-iteration-range`` KERNEL_ITERATION_RANGE [KERNEL_ITERATION_RANGE ...] |br| |br|
-       | ``-p`` (START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) [(START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) ...] \| ``--collection-period`` (START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) [(START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) ...] |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br|
+       | ``-P`` (START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) [(START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) ...] \| ``--collection-period`` (START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) [(START_DELAY_TIME):(COLLECTION_TIME):(REPEAT) ...] |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br| |br|
        | ``--collection-period-unit`` {hour,min,sec,msec,usec,nsec}
      - | Filters counter-collection and thread-trace data to include the kernels matching the specified regular expression. Non-matching kernels are excluded. |br| |br|
        | Filters counter-collection and thread-trace data to exclude the kernels matching the specified regular expression. It is applied after ``--kernel-include-regex`` option. |br| |br|
        | Specifies iteration range for each kernel matching the filter [start-stop]. |br| |br| |br|
-       | START_DELAY_TIME\: Time in seconds before the data collection begins. |br| COLLECTION_TIME\: Duration of data collection in seconds. |br| REPEAT\: Number of times the data collection cycle is repeated. |br| The default unit for time is seconds, which can be changed using the ``--collection-period-unit`` or ``-pu`` option. To repeat the cycle indefinitely, specify ``repeat`` as 0. You can specify multiple configurations, each defined by a triplet in the format ``start_delay_time:collection_time:repeat``. For example, the command ``-p 10:10:1 5:3:0`` specifies two configurations, the first one with a start delay time of 10 seconds, a collection time of 10 seconds, and a repeat of 1 (the cycle repeats once), and the second with a start delay time of 5 seconds, a collection time of 3 seconds, and a repeat of 0 (the cycle repeats indefinitely). |br| |br| |br|
+       | START_DELAY_TIME\: Time in seconds before the data collection begins. |br| COLLECTION_TIME\: Duration of data collection in seconds. |br| REPEAT\: Number of times the data collection cycle is repeated. |br| The default unit for time is seconds, which can be changed using the ``--collection-period-unit`` option. To repeat the cycle indefinitely, specify ``repeat`` as 0. You can specify multiple configurations, each defined by a triplet in the format ``start_delay_time:collection_time:repeat``. For example, the command ``-P 10:10:1 5:3:0`` specifies two configurations, the first one with a start delay time of 10 seconds, a collection time of 10 seconds, and a repeat of 1 (the cycle repeats once), and the second with a start delay time of 5 seconds, a collection time of 3 seconds, and a repeat of 0 (the cycle repeats indefinitely). |br| |br| |br|
-       | To change the unit of time used in ``--collection-period`` or ``-p``, specify the desired unit using the ``--collection-period-unit`` or ``-pu`` option. The available units are ``hour`` for hours, ``min`` for minutes, ``sec`` for seconds, ``msec`` for milliseconds, ``usec`` for microseconds, and ``nsec`` for nanoseconds.
+       | To change the unit of time used in ``--collection-period`` or ``-P``, specify the desired unit using the ``--collection-period-unit`` option. The available units are ``hour`` for hours, ``min`` for minutes, ``sec`` for seconds, ``msec`` for milliseconds, ``usec`` for microseconds, and ``nsec`` for nanoseconds.
 
    * - Perfetto-specific
      - | ``--perfetto-backend`` {inprocess,system} |br| |br| |br| |br| |br|
@@ -1361,7 +1361,7 @@ The above command generates an ``%hostname%/%pid%_hip_api_trace.csv`` file.
 Collection period
 +++++++++++++++++++
 
-The collection period is the time interval during which the profiling data is collected. You can specify the collection period using the ``--collection-period`` or ``-p`` option.
+The collection period is the time interval during which the profiling data is collected. You can specify the collection period using the ``--collection-period`` or ``-P`` option.
 Users can specify multiple configurations, each defined by a triplet in the format `start_delay:collection_time:repeat`.
 
 The triplet is defined as follows: