Add SDP CSV to Perfetto JSON converter

Signed-off-by: A, Peixuan (Steven) <peixa@qti.qualcomm.com>

Author: peixuana

.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Input/output data files
+input/
+output/

CONTRIBUTING.md

@@ -1,7 +1,7 @@
-# Contributing to <REPLACE-ME>
+# Contributing to Snapdragon Profiler Ecosystem
 
 Hi there!
-We’re thrilled that you’d like to contribute to this project.
+We're thrilled that you'd like to contribute to this project.
 Your help is essential for keeping this project great and for making it better.
 
 ## Branching Strategy
@@ -11,10 +11,10 @@ In general, contributors should develop on branches based off of `main` and pull
 ## Submitting a pull request
 
 1. Please read our [code of conduct](CODE-OF-CONDUCT.md) and [license](LICENSE.txt).
-1. [Fork](https://github.com/qualcomm/<REPLACE-ME>/fork) and clone the repository.
+1. [Fork](https://github.com/SnapdragonGameStudios/Snapdragon_Profiler_Ecosystem/fork) and clone the repository.
 
     ```bash
-    git clone https://github.com/<username>/<REPLACE-ME>.git
+    git clone https://github.com/<username>/Snapdragon_Profiler_Ecosystem.git
     ```
 
 1. Create a new branch based on `main`:
@@ -26,7 +26,7 @@ In general, contributors should develop on branches based off of `main` and pull
 1. Create an upstream `remote` to make it easier to keep your branches up-to-date:
 
     ```bash
-    git remote add upstream https://github.com/qualcomm/<REPLACE-ME>.git
+    git remote add upstream https://github.com/SnapdragonGameStudios/Snapdragon_Profiler_Ecosystem.git
     ```
 
 1. Make your changes, add tests, and make sure the tests still pass.
@@ -50,7 +50,7 @@ In general, contributors should develop on branches based off of `main` and pull
 
     The `-u` is shorthand for `--set-upstream`. This will set up the tracking reference so subsequent runs of `git push` or `git pull` can omit the remote and branch.
 
-1. [Submit a pull request](https://github.com/qualcomm/<REPLACE-ME>/pulls) from your branch to `main`.
+1. [Submit a pull request](https://github.com/SnapdragonGameStudios/Snapdragon_Profiler_Ecosystem/pulls) from your branch to `main`.
 1. Pat yourself on the back and wait for your pull request to be reviewed.
 
 ## Security Analysis of Pull Requests
@@ -68,9 +68,9 @@ By submitting a PR, you agree to participate in this process and help us keep th
 
 Here are a few things you can do that will increase the likelihood of your pull request to be accepted:
 
-- Follow the existing style where possible. **INSERT LINK TO STYLE, e.g. PEP8 for python**
+- Follow the existing style where possible. See [PEP 8](https://peps.python.org/pep-0008/) for Python coding style guidelines.
 - Write tests.
 - Keep your change as focused as possible.
   If you want to make multiple independent changes, please consider submitting them as separate pull requests.
 - Write a [good commit message](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
-- It's a good idea to arrange a discussion with other developers to ensure there is consensus on large features, architecture changes, and other core code changes. PR reviews will go much faster when there are no surprises.
+- It's a good idea to arrange a discussion with other developers to ensure there is consensus on large features, architecture changes, and other core code changes. PR reviews will go much faster when there are no surprises.

LICENSE.txt

@@ -23,4 +23,6 @@ SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
-IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+SPDX-License-Identifier: BSD-3-Clause

README.md

@@ -1,47 +1,115 @@
-**After repository creation:**
-- [ ] Update this `README.md`. Update the Project Name, description, and all sections. Remove this checklist.
-- [ ] If required, update `LICENSE.txt` and the License section with your project's approved license
-- [ ] Search this repo for "REPLACE-ME" and update all instances accordingly
-- [ ] Update `CONTRIBUTING.md` as needed
-- [ ] Review the workflows in `.github/workflows`, updating as needed. See https://docs.github.com/en/actions for information on what these files do and how they work.
-- [ ] Review and update the suggested Issue and PR templates as needed in `.github/ISSUE_TEMPLATE` and `.github/PULL_REQUEST_TEMPLATE`
+# Snapdragon Profiler Ecosystem
 
-# Project Name
-
-*\<update with your project name and a short description\>*
-
-Project that does ... implemented in ... runs on Qualcomm® *\<processor\>*
+A collection of tools for working with [Snapdragon Profiler (SDP)](https://developer.qualcomm.com/software/snapdragon-profiler).
 
 ## Branches
 
 **main**: Primary development branch. Contributors should develop submissions based on this branch, and submit pull requests to this branch.
 
-## Requirements
+## Available Tools
+
+### Converter
+
+Convert SDP exported CSV trace files into [Perfetto](https://ui.perfetto.dev/) compatible JSON format for visualization and analysis.
+This converter supports CSV files exported from both SDP capture modes:
 
-List requirements to run the project, how to install them, instructions to use docker container, etc...
+- **Realtime Capture Mode** — Streaming/live capture sessions where metrics are recorded continuously in real time
+- **Trace Capture Mode** — Full trace sessions with detailed scheduling, slice, and counter data captured over a defined time window
+
+#### Supported Event Types
+
+| CSV Row Type | Perfetto Phase | Description |
+|---|---|---|
+| System counters | `"ph": "C"` | System-level metrics (CPU frequency, GPU metrics, DSP metrics) |
+| Process counters | `"ph": "C"` | Per-process counter values (e.g., `aaRdy`, GPU Rendering Pipe Metrics) |
+| Process slices | `"ph": "X"` | Duration events with start/end timestamps |
+| System scheduling slices | `"ph": "X"` | Kernel scheduling events (e.g., Sched CPU) |
+| Metadata | `"ph": "M"` | Auto-generated `process_name` and `thread_name` labels |
 
 ## Installation Instructions
 
-How to install the software itself.
+```bash
+# Install uv (if not already installed)
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Sync the project (creates virtual environment and installs dependencies)
+uv sync
+```
 
 ## Usage
 
-Describe how to use the project.
+All tools are accessible through the unified `main.py` entry point:
+
+```bash
+# Show available tools
+uv run main.py --help
+
+# Run a specific tool (e.g., converter)
+uv run main.py converter <tool-specific arguments ...>
+```
+
+### Converter Examples
+
+```bash
+# Single file (output: trace1.json)
+uv run main.py converter trace1.csv
+
+# Single file with custom output name
+uv run main.py converter trace1.csv -o custom_output.json
+
+# Multiple files (each gets its own .json: trace1.json, trace2.json, trace3.json)
+uv run main.py converter trace1.csv trace2.csv trace3.csv
+
+# All CSV files in the current directory
+uv run main.py converter *.csv
+
+# Output to a specific directory
+uv run main.py converter *.csv --output-dir ./output/
+```
+
+You can also invoke the converter directly (bypassing the dispatcher):
+
+```bash
+uv run python -m tools.converter.convert_sdp_csv_to_perfetto_json trace1.csv
+```
 
 ## Development
 
-How to develop new features/fixes for the software. Maybe different than "usage". Also provide details on how to contribute via a [CONTRIBUTING.md file](CONTRIBUTING.md).
+To contribute new features or fixes, please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on branching, submitting pull requests, and coding standards.
 
-## Getting in Contact
+```bash
+# Clone the repository
+git clone https://github.com/SnapdragonGameStudios/Snapdragon_Profiler_Ecosystem.git
+cd Snapdragon_Profiler_Ecosystem
+
+# Sync the project (creates virtual environment and installs dev dependencies)
+uv sync
+```
+
+## Testing
 
-How to contact maintainers. E.g. GitHub Issues, GitHub Discussions could be indicated for many cases. However a mail list or list of Maintainer e-mails could be shared for other types of discussions. E.g.
+The project includes a comprehensive test suite using pytest.
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run tests with verbose output
+uv run pytest -v
+
+# Run a specific test class
+uv run pytest tests/test_convert_sdp_csv_to_perfetto_json.py::TestExampleCSV -v
+```
+
+## Getting in Contact
 
 * [Report an Issue on GitHub](../../issues)
 * [Open a Discussion on GitHub](../../discussions)
-* [E-mail us](mailto:REPLACE-ME@qti.qualcomm.com) for general questions
 
 ## License
 
-*\<update with your project name and license\>*
-
-*\<REPLACE-ME\>* is licensed under the [BSD-3-clause License](https://spdx.org/licenses/BSD-3-Clause.html). See [LICENSE.txt](LICENSE.txt) for the full license text.
+*Snapdragon Profiler Ecosystem* is licensed under the [BSD-3-clause License](https://spdx.org/licenses/BSD-3-Clause.html). See [LICENSE.txt](LICENSE.txt) for the full license text.

SECURITY.md

@@ -3,7 +3,7 @@ How to Report a Potential Vulnerability?
 
 If you would like to report a public issue (for example, one with a released
 CVE number), please report it as a
-[GitHub issue](https://github.com/qualcomm/REPLACE-ME/issues/new).
+[GitHub issue](https://github.com/SnapdragonGameStudios/Snapdragon_Profiler_Ecosystem/issues/new).
 If you have a patch ready, submit it following the same procedure as any
 other patch as described in [CONTRIBUTING.md](CONTRIBUTING.md).
 

main.py

@@ -0,0 +1,67 @@
+# ============================================================================================================
+# 
+#                  Copyright (c) 2023, Qualcomm Innovation Center, Inc. All rights reserved.
+#                              SPDX-License-Identifier: BSD-3-Clause
+# 
+# ============================================================================================================ 
+
+
+"""Snapdragon Profiler Ecosystem – unified CLI entry point.
+
+Usage:
+    python main.py <tool> [tool-specific arguments ...]
+
+Available tools are registered in TOOLS_REGISTRY below.  To add a new tool,
+simply create a module under ``tools/`` with a ``main()`` function that uses
+``argparse``, then add one line to the registry mapping.
+
+Examples:
+    python main.py converter input.csv -o output.json
+    python main.py converter input1.csv input2.csv --output-dir output/
+"""
+
+import importlib
+import sys
+
+# ---------------------------------------------------------------------------
+# Tool registry – maps CLI name → dotted module path.
+# Each module MUST expose a ``main()`` function (using argparse internally).
+# ---------------------------------------------------------------------------
+TOOLS_REGISTRY: dict[str, str] = {
+    "converter": "tools.converter.convert_sdp_csv_to_perfetto_json",
+}
+
+
+def main():
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        _print_help()
+        sys.exit(0)
+
+    tool_name = sys.argv[1]
+
+    if tool_name not in TOOLS_REGISTRY:
+        print(f"Error: Unknown tool '{tool_name}'.")
+        print(f"Available tools: {', '.join(sorted(TOOLS_REGISTRY))}")
+        sys.exit(1)
+
+    module_path = TOOLS_REGISTRY[tool_name]
+    module = importlib.import_module(module_path)
+
+    # Remove the dispatcher's own argv[0] and the tool name so the tool's
+    # argparse sees only its own arguments.
+    sys.argv = [f"main.py {tool_name}"] + sys.argv[2:]
+    module.main()
+
+
+def _print_help():
+    print("Snapdragon Profiler Ecosystem – unified CLI entry point\n")
+    print("Usage: python main.py <tool> [tool-specific arguments ...]\n")
+    print("Available tools:")
+    for name, mod in sorted(TOOLS_REGISTRY.items()):
+        print(f"  {name:20s} → {mod}")
+    print("\nPass -h/--help after a tool name for tool-specific help.")
+    print("Example: python main.py converter --help")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "snapdragon_profiler_ecosystem"
+version = "2026.04"
+description = "Snapdragon Profiler Ecosystem – a collection of tools for working with Snapdragon Profiler (SDP) data"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[project.scripts]
+snapdragon-profiler-ecosystem = "main:main"
+sdp-csv-to-perfetto-json = "tools.converter.convert_sdp_csv_to_perfetto_json:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]

test_main.py

@@ -0,0 +1,14 @@
+# ============================================================================================================
+# 
+#                  Copyright (c) 2023, Qualcomm Innovation Center, Inc. All rights reserved.
+#                              SPDX-License-Identifier: BSD-3-Clause
+# 
+# ============================================================================================================ 
+
+"""Backward-compatible test entry point.
+
+The test suite has moved to tests/test_convert_sdp_csv_to_perfetto_json.py.
+This wrapper re-exports everything so that ``pytest test_main.py`` still works.
+"""
+
+from tests.test_convert_sdp_csv_to_perfetto_json import *  # noqa: F401,F403

tests/__init__.py

@@ -0,0 +1,8 @@
+# ============================================================================================================
+# 
+#                  Copyright (c) 2023, Qualcomm Innovation Center, Inc. All rights reserved.
+#                              SPDX-License-Identifier: BSD-3-Clause
+# 
+# ============================================================================================================ 
+
+# tests package