diff --git a/content/install-guides/antigravity.md b/content/install-guides/antigravity.md index c5c5c250e8..844fb21d72 100644 --- a/content/install-guides/antigravity.md +++ b/content/install-guides/antigravity.md @@ -209,10 +209,6 @@ Add the following JSON configuration to `~/.gemini/antigravity-cli/mcp_config.js "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {} @@ -221,7 +217,7 @@ Add the following JSON configuration to `~/.gemini/antigravity-cli/mcp_config.js } ``` -Replace `/path/to/your/workspace`, `/path/to/your/ssh/private_key`, and `/path/to/your/ssh/known_hosts` with your workspace directory, SSH private key, and `known_hosts` file to enable remote testing features on your target device. +Replace `/path/to/your/workspace` with your workspace directory. ### (Optional) Use alternative container tools @@ -251,10 +247,6 @@ Add the following configuration to `~/.gemini/antigravity-cli/mcp_config.json`: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {} @@ -284,10 +276,6 @@ Add the following configuration to `~/.gemini/antigravity-cli/mcp_config.json`: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {} @@ -319,10 +307,6 @@ Add the following configuration to `~/.gemini/antigravity-cli/mcp_config.json`: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {} @@ -354,10 +338,6 @@ Add the following configuration to `~/.gemini/antigravity-cli/mcp_config.json`: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {} @@ -388,8 +368,8 @@ The output lists the Arm MCP Server tools and is similar to: MCP Servers Plugins (~/.gemini/antigravity-cli/plugins) -> ✓ arm_mcp_server Tools: knowledge_base_search, check_image, sysreport_instructions, - migrate_ease_scan, apx_recipe_run, +2 more +> ✓ arm_mcp_server Tools: knowledge_base_search, migrate_ease_scan, check_image, + skopeo, mca ``` @@ -406,4 +386,3 @@ If you are facing issues or have questions, reach out to mcpserver@arm.com. You're now ready to use Antigravity CLI for Arm architecture development, migration, and optimization. To test a workflow for migrating an application from x86 to Arm, see the Learning Path [Automate x86-to-Arm application migration using the Arm MCP server](/learning-paths/servers-and-cloud-computing/arm-mcp-server/). - diff --git a/content/install-guides/claude-code.md b/content/install-guides/claude-code.md index 72e9a6d5c9..fcdf71f823 100644 --- a/content/install-guides/claude-code.md +++ b/content/install-guides/claude-code.md @@ -184,7 +184,7 @@ Navigate to your project directory and add the Arm MCP Server: ```console cd your-project -claude mcp add --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` under your project's path and is only accessible when working in this directory. @@ -194,7 +194,7 @@ This configuration is stored in `~/.claude.json` under your project's path and i To make the Arm MCP Server available across all your projects: ```console -claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` and is accessible from any project directory. @@ -205,7 +205,7 @@ To share the MCP server configuration with your team via version control: ```console cd your-project -claude mcp add --scope project --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope project --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This creates a `.mcp.json` file in your project root that can be committed to version control. @@ -217,11 +217,9 @@ The Arm MCP Server automatically mounts your current working directory to the `/ To analyze a different directory, modify the volume mount in the `docker run` command. For example, to analyze `/Users/username/myproject`: ```console -claude mcp add --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "/Users/username/myproject:/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "/Users/username/myproject:/workspace" armlimited/arm-mcp:latest ``` -To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device. - ### Optional: Use a Docker replacement containerization tool You can use other containerization tools besides Docker that are free and do not require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the options below and use its CLI in place of `docker`. @@ -238,7 +236,7 @@ podman pull armlimited/arm-mcp:latest To make the Arm MCP Server available across all your projects (user scope): ```console -claude mcp add --scope user --transport stdio arm-mcp -- podman run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope user --transport stdio arm-mcp -- podman run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` and is accessible from any project directory. You can choose other scopes (local or project) as described in the Docker section above. @@ -254,7 +252,7 @@ finch pull armlimited/arm-mcp:latest To make the Arm MCP Server available across all your projects (user scope): ```console -claude mcp add --scope user --transport stdio arm-mcp -- finch run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope user --transport stdio arm-mcp -- finch run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` and is accessible from any project directory. You can choose other scopes (local or project) as described in the Docker section above. @@ -272,7 +270,7 @@ docker pull armlimited/arm-mcp:latest To make the Arm MCP Server available across all your projects (user scope): ```console -claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` and is accessible from any project directory. You can choose other scopes (local or project) as described in the Docker section above. @@ -290,7 +288,7 @@ docker pull armlimited/arm-mcp:latest To make the Arm MCP Server available across all your projects (user scope): ```console -claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest +claude mcp add --scope user --transport stdio arm-mcp -- docker run --rm -i --pull=always -v "$(pwd):/workspace" armlimited/arm-mcp:latest ``` This configuration is stored in `~/.claude.json` and is accessible from any project directory. You can choose other scopes (local or project) as described in the Docker section above. diff --git a/content/install-guides/codex-cli.md b/content/install-guides/codex-cli.md index 3017492442..11e473f833 100644 --- a/content/install-guides/codex-cli.md +++ b/content/install-guides/codex-cli.md @@ -210,10 +210,6 @@ args = [ "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] startup_timeout_sec = 60 @@ -228,11 +224,9 @@ The section must be named `mcp_servers` with an underscore. Using `mcp-servers` You can also add the Arm MCP server from the Codex CLI, after starting `codex` run: ```bash -codex mcp add arm-mcp -- sh -lc 'docker run --rm -i --pull=always -v "$PWD:/workspace" -v "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro" -v "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro" armlimited/arm-mcp:latest' +codex mcp add arm-mcp -- sh -lc 'docker run --rm -i --pull=always -v "$PWD:/workspace" armlimited/arm-mcp:latest' ``` -To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device. - ### Optional: Use a Docker replacement containerization tool You can use other containerization tools besides Docker that are free and don't require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the following options and use its CLI in place of `docker`. @@ -256,8 +250,6 @@ args = [ "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] startup_timeout_sec = 60 @@ -281,8 +273,6 @@ args = [ "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] startup_timeout_sec = 60 @@ -308,8 +298,6 @@ args = [ "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] startup_timeout_sec = 60 @@ -335,8 +323,6 @@ args = [ "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] startup_timeout_sec = 60 diff --git a/content/install-guides/gemini.md b/content/install-guides/gemini.md index b1027f6ea9..84590f84ee 100644 --- a/content/install-guides/gemini.md +++ b/content/install-guides/gemini.md @@ -370,10 +370,6 @@ Make sure to use a `,` at the end of each object that is not the last one. For e "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -385,8 +381,6 @@ Make sure to use a `,` at the end of each object that is not the last one. For e This configuration tells Gemini CLI to connect to the Arm MCP server running in the Docker container. -To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device. - ### Optional: Use a Docker replacement containerization tool You can use other containerization tools besides Docker that are free and do not require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the options below and use its CLI in place of `docker`. @@ -417,8 +411,6 @@ Add the following configuration to the user-level `~/.gemini/settings.json` file "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -453,8 +445,6 @@ Add the following configuration to the user-level `~/.gemini/settings.json` file "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -491,8 +481,6 @@ Add the following configuration to the user-level `~/.gemini/settings.json` file "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -529,8 +517,6 @@ Add the following configuration to the user-level `~/.gemini/settings.json` file "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -567,14 +553,13 @@ The Arm MCP server tools are listed in the output: ```output Configured MCP servers: -🟢 arm_mcp_server - Ready (6 tools) +🟢 arm_mcp_server - Ready (5 tools) Tools: - check_image - knowledge_base_search - mca - migrate_ease_scan - skopeo - - sysreport_instructions ``` ### Use Arm prompt files with the MCP Server diff --git a/content/install-guides/github-copilot.md b/content/install-guides/github-copilot.md index 43ab408851..51ea8a6318 100644 --- a/content/install-guides/github-copilot.md +++ b/content/install-guides/github-copilot.md @@ -248,10 +248,6 @@ Create an `mcp.json` file in the `.vscode` directory with the following configur "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } @@ -278,10 +274,6 @@ Add the following configuration to the user-level `mcp.json` file: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } @@ -291,8 +283,6 @@ Add the following configuration to the user-level `mcp.json` file: After saving your `mcp.json` file, a **Start** button appears at the top of the servers list. Select this button to start the Arm MCP Server. -To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device. - ## Optional: Use a Docker replacement containerization tool You can use other containerization tools besides Docker that are free and do not require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the options below and use its CLI in place of docker. @@ -319,8 +309,6 @@ Add the following configuration to the user-level `mcp.json` file: "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } @@ -351,8 +339,6 @@ Add the following configuration to the user-level `mcp.json` file: "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } @@ -384,8 +370,6 @@ Add the following configuration to the user-level `mcp.json` file: "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } @@ -417,8 +401,6 @@ Add the following configuration to the user-level `mcp.json` file: "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ] } diff --git a/content/install-guides/kiro-cli.md b/content/install-guides/kiro-cli.md index 23cd53cc5c..b2e1aaf41f 100644 --- a/content/install-guides/kiro-cli.md +++ b/content/install-guides/kiro-cli.md @@ -278,10 +278,6 @@ Replace the path `/path/to/your/workspace` with the path to your local codebase: "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", - "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", - "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -291,8 +287,6 @@ Replace the path `/path/to/your/workspace` with the path to your local codebase: } ``` -To enable Arm Performix features through the Arm MCP Server, replace `/path/to/your/ssh/private_key` and `/path/to/your/ssh/known_hosts` with the SSH private key and `known_hosts` file used for your target device. - ### (Optional) Use an alternative containerization tool You can use other containerization tools besides Docker that are free and don't require licenses, such as Podman, Finch, Colima, and Rancher Desktop. Choose one of the following options and use its CLI in place of `docker` to configure the Arm MCP Server. @@ -318,8 +312,6 @@ Add the following configuration to the user-level `~/.kiro/settings/mcp.json` fi "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -349,8 +341,6 @@ Add the following configuration to the user-level `~/.kiro/settings/mcp.json` fi "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -382,8 +372,6 @@ Add the following configuration to the user-level `~/.kiro/settings/mcp.json` fi "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, @@ -415,8 +403,6 @@ Add the following configuration to the user-level `~/.kiro/settings/mcp.json` fi "-i", "--pull=always", "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", "armlimited/arm-mcp:latest" ], "env": {}, diff --git a/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview.md b/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview.md index 50713c9d18..8e8a9cf540 100644 --- a/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview.md +++ b/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview.md @@ -49,7 +49,7 @@ You don't need all of these tools immediately. You'll start by using image inspe ### knowledge_base_search -Searches an Arm knowledge base of learning resources, Arm intrinsics, and software version compatibility using semantic similarity. Given a natural language query, it returns matching resources with URLs, titles, and content snippets ranked by relevance. +Searches an Arm knowledge base of learning resources, Arm intrinsics, software version compatibility, and guidance for collecting system architecture, CPU, memory, and other host hardware details using semantic similarity, returning matching resources with URLs, titles, and content snippets ranked by relevance. **Use case:** Finding documentation, tutorials, or version compatibility information for Arm migration. @@ -77,12 +77,6 @@ An assembly code performance analyzer that predicts performance on different CPU **Use case:** Analyzing and optimizing performance-critical assembly code when migrating between processor types. -### sysreport_instructions - -Provides instructions for installing and using sysreport, a tool that obtains system information related to system architecture, CPU, memory, and other hardware details. - -**Use case:** Understanding the target Arm system's capabilities before deployment. - ## Setting up the Arm MCP Server To use the Arm MCP Server with an AI coding assistant, you need to configure the assistant to connect to the MCP server. Connecting your assistant allows it to query Arm-specific tools, documentation, and capabilities exposed through the Model Context Protocol (MCP). diff --git a/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/3-simd-migration.md b/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/3-simd-migration.md index 5c469ae466..b0bca3b91f 100644 --- a/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/3-simd-migration.md +++ b/content/learning-paths/servers-and-cloud-computing/arm-mcp-server/3-simd-migration.md @@ -191,7 +191,7 @@ A prompt file instructs the AI assistant how to analyze and transform the projec Create the following prompt file at `.github/prompts/arm-migration.prompt.md`: ```markdown --- -tools: ['search/codebase', 'edit/editFiles', 'arm-mcp/skopeo', 'arm-mcp/check_image', 'arm-mcp/knowledge_base_search', 'arm-mcp/migrate_ease_scan', 'arm-mcp/mca', 'arm-mcp/sysreport_instructions'] +tools: ['search/codebase', 'edit/editFiles', 'arm-mcp/skopeo', 'arm-mcp/check_image', 'arm-mcp/knowledge_base_search', 'arm-mcp/migrate_ease_scan', 'arm-mcp/mca'] description: 'Scan a project and migrate to Arm architecture' --- @@ -201,6 +201,7 @@ Steps to follow: * Look in all Dockerfiles and use the check_image and/or skopeo tools to verify Arm compatibility, changing the base image if necessary. * Look at the packages installed by the Dockerfile and send each package to the knowledge_base_search tool to check each package for Arm compatibility. If a package isn't compatible, change it to a compatible version. When invoking the tool, explicitly ask "Is [package] compatible with Arm architecture?" where [package] is the name of the package. * Look at the contents of any requirements.txt files line-by-line and send each line to the knowledge_base_search tool to check each package for Arm compatibility. If a package isn't compatible, change it to a compatible version. When invoking the tool, explicitly ask "Is [package] compatible with Arm architecture?" where [package] is the name of the package. +* If system architecture, CPU, memory, or other host details are required, use `arm-mcp/knowledge_base_search` to find the existing Sysreport Learning Path and guide the user through its prerequisites and workflow. * Look at the codebase that you have access to, and determine what the language used is. * Run the migrate_ease_scan tool on the codebase, using the appropriate language scanner based on what language the codebase uses, and apply the suggested changes. Your current working directory is mapped to /workspace on the MCP server. * OPTIONAL: If you have access to build tools, rebuild the project for Arm, if you're running on an Arm-based runner. Fix any compilation errors. diff --git a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md index a05acdbaa7..3c2a9730d0 100644 --- a/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md +++ b/content/learning-paths/servers-and-cloud-computing/docker-mcp-toolkit/2-setup.md @@ -38,16 +38,15 @@ Search for **Arm** in the catalog and add the [Arm MCP Server](https://hub.docke Configure it by setting the directory path to your local code. This allows the `migrate_ease_scan` and `mca` tools to access your source files. Click **Save** after setting the path. -The Arm MCP Server provides six tools: +The Arm MCP Server provides five tools: | Tool | Description | |------|-------------| -| `knowledge_base_search` | Semantic search of Arm learning resources, intrinsics documentation, and software compatibility | +| `knowledge_base_search` | Semantic search of Arm learning resources, intrinsics documentation, software compatibility, and host hardware information | | `migrate_ease_scan` | Code scanner for C++, Python, Go, JavaScript, and Java Arm compatibility analysis | | `check_image` | Docker image architecture verification for Arm64 support | | `skopeo` | Remote container image inspection without downloading | | `mca` | Machine Code Analyzer for assembly performance and IPC predictions | -| `sysreport_instructions` | System architecture information gathering | ### GitHub Official MCP Server @@ -98,4 +97,4 @@ You have: - Connected VS Code with GitHub Copilot to the MCP Gateway - Verified that Copilot can access migration tools -Next, you'll examine the demo application to identify x86-specific code that needs adaptation for Arm64. \ No newline at end of file +Next, you'll examine the demo application to identify x86-specific code that needs adaptation for Arm64. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-get-started/add_target.md b/content/learning-paths/servers-and-cloud-computing/performix-get-started/add_target.md index 7b1cca5aa2..66d3aec852 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-get-started/add_target.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-get-started/add_target.md @@ -16,7 +16,7 @@ Performix runs on your local machine (Windows, macOS, or Linux). The tool connec For a walkthrough of the Performix GUI and setup process, see this video on [getting started with Arm Performix](https://youtu.be/_eX8ZpNT0kc?si=WrQg5daHxUc0MFbR). -In addition to the GUI, you can use Arm Performix through the command line. You can also use [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) to integrate Performix into AI-assisted workflows with the [Arm MCP Server](https://developer.arm.com/servers-and-cloud-computing/arm-mcp-server). +In addition to the GUI, you can use Arm Performix through the command line. Arm Performix also includes a local Model Context Protocol (MCP) server for AI-assisted workflows. For a setup example, see [Generate Arm Performix AI insights in Visual Studio Code with Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/). ## Configure SSH key-based authentication diff --git a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_index.md b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_index.md index ab198b5b80..a3b6d6f93a 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/_index.md @@ -96,13 +96,9 @@ further_reading: link: /learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/ type: learning-path - resource: - title: Identify code hotspots using Arm Performix through the Arm MCP Server - link: /learning-paths/servers-and-cloud-computing/performix-mcp-agent/ + title: Generate Arm Performix AI insights in Visual Studio Code with Codex + link: /learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/ type: learning-path - - resource: - title: Arm MCP Server GitHub Repository - link: https://github.com/arm/mcp - type: website - resource: title: KleidiAI GitHub Repository link: https://gitlab.arm.com/kleidi/kleidiai diff --git a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3.md b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3.md index 49671419f9..a69d68e713 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-3.md @@ -77,4 +77,4 @@ Finally, in dynamic functions, you can break down operation types to individual You've now used Instruction Mix to confirm that baseline runtime is dominated by scalar-heavy `matmul` execution. -Next, you can optionally learn to optimize `matmul` with vector intrinsics and use the Arm MCP Server with Performix. You can also skip to [Compare Neon and SVE with the Arm Performix Instruction Mix recipe](/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5/) to compare updated Instruction Mix and throughput across scalar, Neon, SVE, and KleidiAI variants. +Next, you can optionally learn to optimize `matmul` with vector intrinsics and use the Arm Performix MCP server. You can also skip to [Compare Neon and SVE with the Arm Performix Instruction Mix recipe](/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-5/) to compare updated Instruction Mix and throughput across scalar, Neon, SVE, and KleidiAI variants. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4.md b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4.md index 2f4be0e49f..4da83c61bf 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/how-to-4.md @@ -1,6 +1,6 @@ --- title: (Optional) Optimize matmul with vector intrinsics -description: Optionally implement a custom Neon or SVE matrix multiplication kernel and profile it with Arm Performix or the Arm MCP Server. +description: Optionally implement a custom Neon or SVE matrix multiplication kernel and profile it using the Arm Performix GUI or the Arm Performix MCP server. weight: 5 ### FIXED, DO NOT MODIFY @@ -35,37 +35,28 @@ Example solutions are available in: You can use `AGENTS.md` in the GPT-2 example repository for guided learning support. -### Use the Arm MCP Server with Performix +### Use the Arm Performix MCP server -You can also use an MCP-compatible coding assistant, such as GitHub Copilot or Codex, with the Arm MCP Server. This gives the assistant direct tool access to run Performix recipes on your remote Arm target and create a faster feedback loop while you iterate on `matmul_user`. +You can also use an MCP-compatible coding assistant, such as GitHub Copilot or Codex, with the Arm Performix MCP server. This gives the assistant access to Performix tools so it can run recipes on your configured remote Arm target and help you iterate on `matmul_user`. -For setup details, see [Automate x86-to-Arm application migration using Arm MCP Server](/learning-paths/servers-and-cloud-computing/arm-mcp-server/). +For setup instructions, see [Configure the Arm Performix MCP server in Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex/). -Install Docker if needed, then pull the MCP server image: +After you confirm that the MCP server is connected, use a focused prompt: -```bash -docker pull armlimited/arm-mcp:latest -``` +```text +Use the Arm Performix MCP server to list the available recipes and targets. + +For the target named "", run the Instruction Mix recipe with this workload: +"/home/ubuntu/GPT-2-Example/build/gpt2_user --model gpt2-medium \"Once upon a time\" -n 150" -To allow Performix access to remote targets from inside the container, mount your workspace plus SSH key and known hosts in your Codex MCP configuration (example `~/.codex/config.toml`): - -```output -[mcp_servers.arm-mcp] -command = "docker" -args = [ - "run", - "--rm", - "-i", - "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", - "armlimited/arm-mcp" -] +Before starting, inspect the recipe parameters, target support, and MCP guidance. Repeat the target and workload, and ask me to confirm them. If target preparation or collection fails, stop and report the error and suggested remediation. When the run succeeds, summarize the Instruction Mix results for `matmul_user` and suggest Neon or SVE improvements. ``` -Restart your coding assistant, then prompt it to run Performix Instruction Mix and Code Hotspots on your `gpt2_user` binary and suggest Arm intrinsics improvements. +{{% notice Note %}} + +The Arm Performix MCP server can run Instruction Mix and generate Dynamic Insights for successful Instruction Mix runs. -![Screenshot of a coding assistant prompt configured to use Arm MCP Server tools for running Performix recipes and analyzing `matmul_user` optimization opportunities in the GPT-2 workload.#center](./mcp-performix-prompt.webp "Coding assistant prompt for Performix analysis through Arm MCP Server") +{{% /notice %}} ## What you've accomplished and what's next diff --git a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/mcp-performix-prompt.webp b/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/mcp-performix-prompt.webp deleted file mode 100644 index 4e0b6d8edb..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/performix-instruction-mix/mcp-performix-prompt.webp and /dev/null differ diff --git a/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/1-what-is-the-skill.md b/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/1-what-is-the-skill.md index ffd7c99aac..21c826c3b8 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/1-what-is-the-skill.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/1-what-is-the-skill.md @@ -22,8 +22,7 @@ When the skill is active, the assistant: - Asks for the target, binary path, and workload command before profiling - Chooses the narrowest Performix recipe that answers your question -- Runs the recipe through the `apx` command-line interface (CLI), or through the - Arm Model Context Protocol (MCP) Server +- Runs the recipe through the Arm Performix `apx` command-line interface (CLI) - Returns a structured analysis report with a bottleneck summary, key metrics, hot functions, ranked recommendations, and a single next step @@ -52,7 +51,7 @@ Each recipe provides a different view of application performance: - To use the Memory Access recipe, enable the Statistical Profiling Extension (SPE). - The host machine can be macOS, Windows, or Linux on either arm64 or x86-64. The host can connect to the target locally or over SSH. -- The skill guides AI assistants to use the `apx` CLI by default. If `apx` isn’t installed or available, it asks how you want to proceed rather than switching tools automatically. You can use the Arm MCP Server as an alternative tool, especially if you want fully agent-driven launch-mode profiling. Note that the MCP server doesn’t expose the System Characterization recipe. +- The skill guides AI assistants to use the `apx` CLI by default. If `apx` isn’t installed or available, it asks how you want to proceed rather than switching tools automatically. {{% /notice %}} ## What you've learned and what's next diff --git a/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_index.md b/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_index.md index 533fc59e0d..69e45c9abd 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-llm-agent-skill/_index.md @@ -95,7 +95,7 @@ further_reading: link: /learning-paths/servers-and-cloud-computing/performix-microarchitecture/ type: learning-path - resource: - title: Optimize memory access behavior using Arm Performix and the Arm MCP Server + title: Optimize memory access behavior using the Arm Performix MCP server link: /learning-paths/servers-and-cloud-computing/performix-memory-access/ type: learning-path @@ -105,4 +105,3 @@ weight: 1 # _index.md always has weight of 1 to order corr layout: "learningpathall" # All files under learning paths have this same wrapper learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. --- - diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/1-overview.md b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/1-overview.md index be633e557c..0e4b6c99d6 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/1-overview.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/1-overview.md @@ -1,6 +1,6 @@ --- -title: Understand AI-driven profiling with Arm Performix MCP tool -description: Understand how the Arm MCP Server exposes Arm Performix so an AI agent can run Code Hotspots profiling and propose evidence-based optimizations. +title: Understand AI-driven profiling with the Arm Performix MCP server +description: Understand how the Arm Performix MCP server enables an AI agent to run Code Hotspots profiling and propose evidence-based optimizations. weight: 2 ### FIXED, DO NOT MODIFY @@ -9,62 +9,62 @@ layout: learningpathall ## Why profile with Arm Performix using AI -The Arm MCP Server exposes Arm Performix as a first-class tool that AI coding assistants can invoke directly. Rather than switching between your IDE and the Performix GUI to analyze results and then back again to apply code changes, an AI agent can orchestrate the entire profiling pipeline. Configuring the recipe, launching the collection run, retrieving hotspot data, and proposing optimizations can all be part of a single agentic workflow. +The Arm Performix MCP server exposes Performix tools that AI coding assistants can invoke directly. Rather than switching between your IDE and the Performix GUI to analyze results and then back again to apply code changes, an AI agent can orchestrate the entire profiling pipeline. Configuring the recipe, launching the collection run, retrieving hotspot data, and proposing optimizations can all be part of a single agentic workflow. -## What the Arm Performix tool is +## What the Arm Performix MCP server is -Arm Performix is a performance profiling tool that simplifies the workflow of collecting CPU samples, building flame graphs, and identifying the functions that dominate application runtime. +Arm Performix is a performance profiling tool that simplifies the workflow of collecting CPU samples, building flame graphs, and identifying the functions that dominate application runtime. -When you integrate Arm Performix into the MCP server, the tool lets an AI agent orchestrate the entire profiling pipeline — configuring the recipe, launching the collection run, and retrieving the resulting hotspot data — without manual interaction with the Performix engine. +Arm Performix includes a local Model Context Protocol (MCP) server. The installed `apx` executable starts the server with the `mcp start` arguments and gives a compatible AI assistant access to Performix targets, recipes, runs, and AI insights. You don't need to context switch between your IDE and the Performix GUI to analyze results and then back again to apply code changes. An AI agent can do all of this for you in a single agentic workflow. -## How the MCP tool works +## How the MCP workflow works -The `apx_recipe_run` tool in the Arm MCP Server accepts a recipe name, a binary path on the remote target, and SSH connection details. It starts the Performix collection run on the configured remote target, waits for the application to finish, and then returns a structured summary of the profiling results. The summary includes the top CPU-time-consuming functions ordered by sample percentage, call stack context for each hotspot, and any relevant observations about the application's runtime behavior. +The agent uses separate Performix tools for collection and analysis: + +- `list_recipes` identifies the recipes available in the installed Performix version. +- `list_targets` identifies targets that are already configured in Performix. +- `recipe_info` checks the selected recipe's parameters and support for a target. +- `run_recipe` runs Code Hotspots against a selected target and returns a run ID and status. +- `generate_ai_insights` prepares measured evidence and recipe guidance for a successful run. The agent uses this data to cross-reference hotspot function names against the source files in your workspace, reason about why those functions are expensive, and propose specific code changes. Because the AI can see both the profiling output and the source code simultaneously, it avoids the guesswork that's common in manual profiling workflows. -You'll use this tool in the following sections to automate the Code Hotspots recipe on a C++ application running on an Arm Neoverse target and identify and fix the most CPU-intensive functions. The agent will drive three successive optimization passes — each validated by a re-profile before moving to the next — to achieve a measured ~12x runtime improvement. +You'll use the Arm Performix MCP server in the following sections to automate the Code Hotspots recipe on a C++ application running on an Arm Neoverse target and identify and fix the most CPU-intensive functions. The agent will drive three successive optimization passes — each validated by a re-profile before moving to the next — to achieve a measured ~12x runtime improvement. -## How to interact with the Arm MCP Server for profiling +## How to interact with the Arm Performix MCP server for profiling -The Arm MCP Server supports the same interaction styles as the rest of its tool suite: direct chat, prompt files, and agentic workflows. For profiling tasks, prompt files are the recommended approach. Profiling workflows typically involve multiple sequential steps — building the application, running a recipe, reading results, editing code, and repeating. Encoding this sequence in a prompt file makes it repeatable, shareable, and easy to version-control alongside the application. +The Arm Performix MCP server supports direct chat, prompt files, and agentic workflows. For profiling tasks, prompt files are the recommended approach. Profiling workflows typically involve multiple sequential steps — building the application, running a recipe, reading results, editing code, and repeating. Encoding this sequence in a prompt file makes it repeatable, shareable, and easy to version-control alongside the application. ### Direct AI chat -You can ask your AI assistant direct questions and it'll invoke the `apx_recipe_run` tool when appropriate. For example: +You can ask your AI assistant direct questions and it'll invoke the Arm Performix MCP tools when appropriate. For example: ```text -Run the Code Hotspots recipe on /home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug and tell me which functions are the hottest +Use the Arm Performix MCP server to list the configured targets. ``` -Direct chat is useful for quick, exploratory checks. It works well when you already know the binary path and just want a fast hotspot summary before committing to deeper analysis. +Direct chat is useful for quick, exploratory checks. It works well when you already know the target and binary path and just want a fast hotspot summary before committing to deeper analysis. ### Prompt files -For repeatable workflows, a prompt file encodes the full profiling sequence as a structured instruction set. Prompt files reference the `arm-mcp/apx_recipe_run` tool alongside other tools such as `edit/editFiles`, which allows the agent to profile the application and then immediately propose source edits based on what it finds. You'll create a prompt file in the next sections to run the Code Hotspots recipe on the Mandelbrot example. +For repeatable workflows, a prompt file encodes the full profiling sequence as a structured instruction set. Include the target name, absolute workload command, confirmation requirement, and run ID rather than binding the prompt to internal MCP tool names. This keeps the prompt portable across compatible AI assistants and allows the agent to profile the application and then propose source edits based on what it finds. ### Agentic workflows -Tools such as GitHub Copilot Agent Mode, Claude Code, Kiro, and OpenAI Codex support autonomous multi-step execution. When you combine a prompt file with an agentic workflow, the profiling step is deterministic: the agent calls `arm-mcp/apx_recipe_run` through the Arm MCP Server, which runs the Performix recipe on your target and returns the identified hotspots as structured, reproducible data. The agent then reasons over those hotspots, locating the corresponding source code, forming a hypothesis about why each function is expensive, and proposing a targeted change — before rebuilding and calling `arm-mcp/apx_recipe_run` again to measure the delta. +Tools such as GitHub Copilot Agent Mode, Claude Code, Kiro, and OpenAI Codex support autonomous multi-step execution. When you combine a prompt file with an agentic workflow, the profiling step is deterministic: the agent uses the Arm Performix MCP server to run the recipe on your target and receives a run ID, then generates AI insights for that run. The agent then reasons over those hotspots, locating the corresponding source code, forming a hypothesis about why each function is expensive, and proposing a targeted change — before rebuilding and running the recipe again to measure the delta. Every decision in the loop is grounded in the hotspot data returned by the tool; the AI never guesses at performance characteristics. -## Set up the Arm MCP Server - -To use the Arm MCP Server with an AI coding assistant, configure the assistant to connect to the MCP server. Connecting your assistant allows it to query Arm-specific tools, documentation, and capabilities exposed through the Model Context Protocol (MCP). +## Set up the Arm Performix MCP server -The required configuration steps vary by AI coding assistant. For step-by-step instructions on connecting AI coding assistants to the Arm MCP server, see the following install guides: +Configure your AI coding assistant to start the installed `apx` executable with `mcp start`. The server name is `arm-performix`. -- [GitHub Copilot](/install-guides/github-copilot/) -- [Antigravity CLI](/install-guides/antigravity/) -- [Kiro CLI](/install-guides/kiro-cli/) -- [Codex CLI](/install-guides/codex-cli/) -- [Claude Code](/install-guides/claude-code/) +For a tested configuration and verification workflow, complete [Generate Arm Performix AI insights in Visual Studio Code with Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/) before continuing. ## What you've learned and what's next -You've now learned what the Arm Performix tool for the Arm MCP Server is and how the tool works. You've also learned why the tool is useful and how you can interact with it. +You've now learned what the Arm Performix MCP server is and how it works. You've also learned why the server is useful and how you can interact with it. Next, you'll build the Mandelbrot example application on your remote Arm server and confirm that Arm Performix can reach the target. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/2-setup.md b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/2-setup.md index cdc1a8acf4..309c1c5915 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/2-setup.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/2-setup.md @@ -1,6 +1,6 @@ --- title: Build the Mandelbrot example on Arm Neoverse -description: Build the Mandelbrot C++ example on an Arm Neoverse target and confirm the binary path that Performix will profile through the Arm MCP Server. +description: Build the Mandelbrot C++ example on an Arm Neoverse target and confirm that the dedicated Arm Performix MCP server can use the configured target. weight: 3 ### FIXED, DO NOT MODIFY @@ -17,13 +17,21 @@ The application generates a 1920×1080 bitmap of the Mandelbrot set by iterating You don't need to understand the Mandelbrot algorithm to follow the Learning Path. -## Connect to your Arm target +## Confirm your Arm Performix target For profiling, you'll target an AWS Graviton3-based metal instance (`m7g.metal`) with 64 Neoverse V1 cores. Any Arm Linux server with multiple cores works, but a metal instance gives you direct access to all hardware threads without the overhead of virtualization. -Connect to the remote target via SSH through the Arm MCP Server. The `apx_recipe_run` tool accepts the target host IP address and SSH username directly as parameters, so there's no separate target configuration step required. +The dedicated Arm Performix MCP server uses targets that are already configured in Performix. Record the friendly target name because you'll give it to your AI assistant in the next section. -Ensure your remote Arm server is reachable over SSH from the machine running your AI coding assistant, and follow the [Configure your MCP client](https://github.com/arm/mcp?tab=readme-ov-file#2-configure-your-mcp-client) instructions in the Arm MCP Server repository before continuing. +If you haven't added the target, follow [Set up Arm Performix](/learning-paths/servers-and-cloud-computing/performix-get-started/add_target/). Remote authentication uses SSH keys, and strict host-key checking requires the target and any jump-node keys in `known_hosts`. + +Test the configured connection from the host running Arm Performix. Replace `` with the friendly target name: + +```bash +apx target test --target +``` + +Continue when the test confirms that Performix can reach the intended target. ## Build the application on the remote server @@ -63,4 +71,4 @@ Note the absolute path to the binary on the remote server. You'll need this when You've now got everything in place for profiling: a compiled, debug-enabled binary on an Arm Neoverse target that Performix can reach. -Next, you'll create a GitHub Copilot prompt file to drive the Code Hotspots recipe through the Arm MCP Server. +Next, you'll ask your AI assistant to run the Code Hotspots recipe through the Arm Performix MCP server. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/3-run-hotspot.md b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/3-run-hotspot.md index bca90e9dda..8207d779b7 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/3-run-hotspot.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/3-run-hotspot.md @@ -1,70 +1,74 @@ --- title: Run Code Hotspots with an AI agent -description: Use a GitHub Copilot prompt file to run the Arm Performix Code Hotspots recipe through the Arm MCP Server and review structured hotspot output. +description: Use an AI agent and the dedicated Arm Performix MCP server to run Code Hotspots and review evidence tied to a specific run ID. weight: 4 ### FIXED, DO NOT MODIFY layout: learningpathall --- -## Execute profiling through the Arm MCP Server +## Execute profiling through the Arm Performix MCP server -You'll use a GitHub Copilot prompt file to drive the Code Hotspots recipe through the Arm MCP Server. The agent confirms your target details, runs the recipe autonomously, and returns structured profiling results. - -## Use the Arm MCP arm-hotspots-optimization prompt file +You'll keep collection and analysis as separate requests. This lets you confirm the target and workload before remote execution and use the resulting run ID for analysis. {{% notice Note %}} -If you prefer a different AI assistant than Visual Studio Code with GitHub Copilot, see [Configure other AI agents](#optional-configure-other-ai-agents) at the end of this section for equivalent configurations for Kiro and OpenAI Codex. +The prompts use natural language instead of internal MCP tool names. This makes them suitable for compatible AI coding assistants that are connected to the dedicated Arm Performix MCP server. For a tested setup, see [Configure the Arm Performix MCP server in Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex/). {{% /notice %}} -The Arm MCP Server repository includes a ready-made prompt file called `arm-hotspots-optimization` that guides an AI agent through the full Code Hotspots workflow: baseline profiling, hotspot identification, targeted code changes, and re-profiling to confirm the improvement. You don't need to write this file yourself. You can copy it from the repository. - -Open the Mandelbrot-Example repository in Visual Studio Code on your local machine. Create the directory `.github/prompts/` if it doesn't already exist: - -```bash -mkdir -p .github/prompts -``` +## Verify the recipe and target -Download the prompt file from the Arm MCP repository and place it in that directory: +Ask your AI assistant to list the available recipes and configured targets: -```bash -curl -o .github/prompts/arm-hotspots-optimization.prompt.md \ - https://raw.githubusercontent.com/arm/mcp/main/agent-integrations/vs-code/arm-hotspots-optimization.prompt.md +```text +Use the Arm Performix MCP server to list the available recipes and configured +targets. Confirm that Code Hotspots is available. For each target, include its +name, connection type, and whether it is the default. ``` -You can also view the full prompt at [github.com/arm/mcp](https://github.com/arm/mcp/blob/main/agent-integrations/vs-code/arm-hotspots-optimization.prompt.md). It instructs the agent to confirm the workload command and target details with you before running, follow the loop of baseline profile → one focused code change → re-profile → compare delta, and report results in concrete numbers at each step. - -## Invoke the prompt file +Choose the friendly target name that you verified in the previous section. You don't need to provide its SSH username or IP address again because those details belong to the Performix target configuration. -With GitHub Copilot connected to the Arm MCP Server, open Copilot Chat in Agent Mode and invoke the prompt with the slash command: +Before collection, ask the assistant to check the recipe against that target: ```text -/arm-hotspots-optimization +Use the Arm Performix MCP server to check whether Code Hotspots supports target +"". Summarize the recipe parameters and their default values. Do +not start a run. ``` -Copilot reads the prompt file and walks you through a series of confirmation questions before running anything. Answer each question in turn: - -First, select where the workload is running — choose **Remote machine (SSH)** for an Arm cloud instance. +Replace `` and continue only when the recipe is available and the target is supported. -![GitHub Copilot agent chat asking where the workload is running, with menu choices for localhost or remote machine (SSH)#center](images/mcp-performix-setup1.png "Agent prompt: select workload location") +## Run the Code Hotspots recipe -Next, enter the absolute path to the binary on the remote server. +Replace `` in this prompt, then send it to your AI assistant: -![GitHub Copilot agent chat prompting the user to enter the absolute path to the executable or workload command#center](images/mcp-performix-setup2.png "Agent prompt: enter binary path") +```text +Use Arm Performix to run the Code Hotspots recipe on target "" +with workload +"/home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug". +Before starting, repeat the target and workload and ask me to confirm them. +When the run completes, return its run ID and collection status. +``` -Then, enter the SSH username used to connect to the target machine. +Review the target and workload before approving collection. The dedicated server runs the recipe, waits for it to finish, and returns a stable run ID with the collection status. -![GitHub Copilot agent chat asking what SSH username should be used to connect to the target machine#center](images/mcp-performix-setup3.png "Agent prompt: enter SSH username") +{{% notice Note %}} +The single-threaded workload can take one to two minutes on the example system. Runtime and sample counts vary with the target, workload build, and Performix version. +{{% /notice %}} -Finally, enter the IP address or hostname of your remote Arm machine. +## Generate an AI insight -![GitHub Copilot agent chat asking for the IP address of the remote Arm machine#center](images/mcp-performix-setup4.png "Agent prompt: enter remote IP address") +Use the returned run ID to request evidence for that exact profile: -After you've answered all four questions, the agent calls `arm-mcp/apx_recipe_run` to start the Code Hotspots recipe and waits for the Mandelbrot binary to finish. The single-threaded build takes approximately one to two minutes to run. +```text +Use Arm Performix to generate an AI insight for run ID "". +Identify the highest-impact findings, cite the profile evidence that supports them, +and suggest investigation or optimization steps. State any missing +evidence or uncertainty. +``` -## Read the agent output +Replace `` with the ID from the completed Code Hotspots run. -After the profiling run completes, the agent returns a structured summary. +After the agent generates the AI insight, it returns a structured summary. The output is similar to: @@ -99,11 +103,6 @@ key observation: the inner loop in getIterations spends more than 60% of total CPU time in the escape condition check and std::complex arithmetic machinery, not in the Mandelbrot iteration itself. -knowledge_base_search result for "optimizing hypot libm Arm Neoverse": - - Arm Performance Libraries vector math functions provide optimized implementations - for Neoverse targets. - Link: https://developer.arm.com/documentation/101004/latest - Proposed optimizations (not yet applied): 1. Replace abs(z) > THRESHOLD with a squared-magnitude check: (z.real()*z.real() + z.imag()*z.imag()) > THRESHOLD*THRESHOLD @@ -120,42 +119,14 @@ Proposed optimizations (not yet applied): The agent has surfaced the same hotspots that a manual Performix session would identify: `__complex_abs` and `hypotf64` dominating through the inner loop in `Mandelbrot::getIterations`, plus significant `std::complex` operator overhead from the debug build. You don't need to open the Performix GUI, configure the recipe, or manually inspect the flame graph. -## (Optional) Configure other AI agents - -The same profiling workflow works with other agentic AI assistants. The core prompt logic is identical across tools; only the file location and invocation format changes. - -### Kiro steering document - -The Arm MCP repository includes a ready-made Kiro steering document for this workflow. Create the `.kiro/steering/` directory if it doesn't already exist, then download the file: - -```bash -mkdir -p .kiro/steering -curl -o .kiro/steering/arm-hotspots-optimization.md \ - https://raw.githubusercontent.com/arm/mcp/main/agent-integrations/kiro/arm-hotspots-optimization.md -``` - -You can view the full steering document at [github.com/arm/mcp](https://github.com/arm/mcp/blob/main/agent-integrations/kiro/arm-hotspots-optimization.md). It uses `inclusion: always`, so Kiro loads it automatically for every session in the workspace. Reference it explicitly in chat by typing `#arm-hotspots-optimization`. +The following flame graph from the same single-threaded Mandelbrot workload shows `std::__complex_abs` as the dominant sampled function. -### OpenAI Codex prompt file - -The Arm MCP repository also includes a ready-made Codex prompt file. Create the prompts directory if it doesn't already exist, then download the file: - -```bash -mkdir -p ~/.codex/prompts -curl -o ~/.codex/prompts/arm-hotspots-optimization \ - https://raw.githubusercontent.com/arm/mcp/main/agent-integrations/codex/arm-hotspots-optimization.md -``` - -You can view the full prompt at [github.com/arm/mcp](https://github.com/arm/mcp/blob/main/agent-integrations/codex/arm-hotspots-optimization.md). Invoke it with: - -```bash -codex /prompts:arm-hotspots-optimization -``` +![Arm Performix flame graph for the single-threaded Mandelbrot workload showing std::__complex_abs as the dominant hotspot, which confirms the square-root-based escape check is a candidate for investigation#center](../cpu_hotspot_performix/single-thread-flame-graph.jpg "Single-threaded Mandelbrot flame graph in Arm Performix") ## What you've accomplished and what's next -You've now used the Arm MCP `arm-hotspots-optimization` prompt file — invoked with `/arm-hotspots-optimization` — to drive the Arm Performix Code Hotspots recipe end-to-end through the Arm MCP Server. +You've now used the dedicated Arm Performix MCP server to select a configured target, run Code Hotspots, and generate an AI insight for a specific run ID. -The agent confirmed your target details, ran the recipe autonomously, and identified `getIterations` as the dominant hotspot. It found that ~33% of total CPU time is spent inside the sqrt-based escape condition check (`__complex_abs` and `hypotf64`), and noted significant `std::complex` operator overhead from the debug build. It proposed three targeted optimizations: eliminating the sqrt, replacing `std::complex` with raw double arithmetic, and enabling compiler optimizations. +The agent identified `getIterations` as the dominant hotspot. It found that ~33% of total CPU time is spent inside the sqrt-based escape condition check (`__complex_abs` and `hypotf64`), and noted significant `std::complex` operator overhead from the debug build. It proposed three targeted optimizations: eliminating the sqrt, replacing `std::complex` with raw double arithmetic, and enabling compiler optimizations. Next, you'll apply those optimizations one at a time, rebuilding and re-profiling after each change to confirm the improvement with real data. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/4-optimize.md b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/4-optimize.md index 82d1c5528d..33d718e150 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/4-optimize.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/4-optimize.md @@ -15,7 +15,7 @@ In the previous section, the agent identified three optimization opportunities: 2. Replace `std::complex` with raw `double` arithmetic to remove all complex operator overhead 3. Build with `-O3` to enable inlining, loop unrolling, and auto-vectorization -Rather than making these changes manually, you can ask the agent to apply each one for you. Because the Arm MCP Server connects to your remote target over SSH, the agent can edit the source files directly on the server, rebuild, and re-profile — all in a single turn. You'll validate each change by asking the agent to compare the new profiling results against the previous run before moving on. +You can ask the agent to apply each change when it has access to your source and build environment. Otherwise, apply and rebuild the change through your normal remote development workflow. The Arm Performix MCP server profiles the configured target and analyzes saved runs; it doesn't by itself provide remote source-editing or deployment tools. You'll validate each change by asking the agent to compare the new profiling results against the previous run before moving on. {{% notice Note %}} The agent will typically surface these optimizations itself based on the profiling results, without you needing to prompt it explicitly. The following prompts are for explicit reference. You can use them if the agent hasn't already proposed the change, or to direct it to a specific optimization. @@ -28,16 +28,17 @@ The inner loop in `Mandelbrot::getIterations` calls `std::abs(z)` on every itera Ask the agent to apply the fix, rebuild, and re-profile in one step. If the agent hasn't already proposed this change, use the following prompt: ```text -On the remote server, replace the abs(z) > THRESHOLD escape check in +Replace the abs(z) > THRESHOLD escape check in getIterations with a squared-magnitude comparison using a precomputed threshold_sq = THRESHOLD * THRESHOLD. Rebuild the debug binary with -`make clean && make single_thread DEBUG=1`, then re-run the Code Hotspots -recipe on /home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug -and compare with the previous run. Has the proportion of samples in -__complex_abs and hypotf64 changed? +`make clean && make single_thread DEBUG=1`. Then use the Arm Performix MCP +server to re-run the Code Hotspots recipe on target "" with +workload "/home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread_debug". +Generate an AI insight for the new run and compare it with run ID "". +Has the proportion of samples in __complex_abs and hypotf64 changed? ``` -The agent calls `arm-mcp/apx_recipe_run` again and returns the comparison. The `std::__complex_abs` and `hypotf64` symbols disappear from the hotspot list entirely. Both functions are gone because the squared-magnitude check never calls them. +Replace `` and `` before sending the prompt. The agent runs the Code Hotspots recipe again and returns the comparison. The `std::__complex_abs` and `hypotf64` symbols disappear from the hotspot list entirely. Both functions are gone because the squared-magnitude check never calls them. The hotspot distribution shifts: `getIterations` drops from 28.5% to 18.4% self-time, and the freed CPU budget is now visible in `std::complex` operator symbols. The overall sample count is slightly lower, but the profile structure reveals that `std::complex` operator overhead is now the next bottleneck to address. @@ -53,15 +54,17 @@ $$im_{new} = 2 \cdot re_z \cdot im_z + im_c$$ The fix eliminates every `std::complex` method call from the inner loop. If the agent hasn't already proposed this change, use the following prompt to direct it: ```text -On the remote server, rewrite the getIterations function in +Rewrite the getIterations function in src/mandelbrot_single_thread.cpp to use plain double variables zr and zi instead of std::complex, expanding z*z + c algebraically. -Rebuild with `make clean && make single_thread DEBUG=1`, then re-run the -Code Hotspots recipe and compare with the previous run. Have the -std::complex operator symbols disappeared from the hotspot list? +Rebuild with `make clean && make single_thread DEBUG=1`. Then use the Arm +Performix MCP server to re-run the Code Hotspots recipe on target +"" with the same workload. Generate an AI insight for the new +run and compare it with run ID "". Have the std::complex +operator symbols disappeared from the hotspot list? ``` -The agent calls `arm-mcp/apx_recipe_run` and returns the comparison. Every `std::complex` function—`__muldc3`, `operator*=`, `operator+=`, `operator+`, `operator*`, `__rep`—is gone from the profile. +Replace the placeholders with the target name and the run ID from the previous step. The agent runs the Code Hotspots recipe and returns the comparison. Every `std::complex` function—`__muldc3`, `operator*=`, `operator+=`, `operator+`, `operator*`, `__rep`—is gone from the profile. Total profile sample count drops from approximately 48,750 (baseline) to approximately 11,457, a reduction of ~76% and a measured ~4x speedup. @@ -74,14 +77,15 @@ Building with `-O3` lets the compiler inline `getIterations` into `draw`, unroll Ask the agent to rebuild with the release target and re-profile. If it hasn't already suggested this step, use the following prompt: ```text -On the remote server, rebuild the application without the DEBUG flag using +Rebuild the application without the DEBUG flag using `make clean && make single_thread`, then run the Code Hotspots recipe on -/home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread and compare -with the previous run. How has the hotspot distribution changed and what is -the runtime improvement? +target "" with workload +"/home/ec2-user/Mandelbrot-Example/build/mandelbrot_single_thread". Generate +an AI insight for the new run and compare it with run ID "". +How has the hotspot distribution changed and what is the runtime improvement? ``` -The agent calls `arm-mcp/apx_recipe_run` on the new binary path and returns the result. The `getIterations` function no longer appears as a separate hotspot because the compiler has inlined it completely into `draw`. Total profile sample count drops to approximately 3,997 — roughly 12x fewer samples than the original baseline of ~48,750, indicating a ~12x speedup. +Replace the placeholders before sending the prompt. The agent runs the Code Hotspots recipe on the new binary path and returns the result. The `getIterations` function no longer appears as a separate hotspot because the compiler has inlined it completely into `draw`. Total profile sample count drops to approximately 3,997 — roughly 12x fewer samples than the original baseline of ~48,750, indicating a ~12x speedup. The only remaining hotspot is `Mandelbrot::draw` itself at ~98.6% of samples, which now includes both the iteration and colorizing passes. The colorizing pass calls `pow(255, hue)` per pixel — visible as `powf64` at ~0.7% — but this is a small fraction of total time at this scale. @@ -98,4 +102,4 @@ The cumulative result, measured by profile sample counts, was a reduction from a | After raw double arithmetic | ~11,457 | ~4× | | After `-O3` | ~3,997 | ~12× | -The same pattern applies to any C++ application on Arm Neoverse. Run the Code Hotspots recipe to locate the hottest functions, let the agent cross-reference the source and the Arm knowledge base, apply the suggested changes, and re-profile to confirm. This evidence-driven loop is faster and less error-prone than manual profiling because the AI maintains context across all steps and keeps the profiling data visible alongside the code throughout. +The same pattern applies to any C++ application on Arm Neoverse. Run the Code Hotspots recipe to locate the hottest functions, let the agent cross-reference the source, apply the suggested changes, and re-profile to confirm. This evidence-driven loop is faster and less error-prone than manual profiling because the AI maintains context across all steps and keeps the profiling data visible alongside the code throughout. diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/_index.md b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/_index.md index 96586d092c..4f80b6dfbf 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/_index.md @@ -1,20 +1,20 @@ --- -title: Identify and optimize code hotspots using Arm Performix through the Arm MCP Server +title: Identify and optimize code hotspots using the Arm Performix MCP server -description: Learn how to use an AI agent and the Performix tool through the Arm MCP Server to run the Code Hotspots recipe on a C++ application, interpret flame graph results, and apply targeted optimizations on Arm Neoverse. +description: Learn how to use an AI agent and the Arm Performix MCP server to run the Code Hotspots recipe on a C++ application, interpret profile evidence, and apply targeted optimizations on Arm Neoverse. minutes_to_complete: 30 who_is_this_for: This is an advanced topic for developers who want to use AI-powered tools to automate performance profiling and optimization of C++ applications on Arm Neoverse servers. learning_objectives: - - Describe how the Arm Performix tool in the Arm MCP Server enables AI-driven profiling workflows - - Configure a GitHub Copilot prompt file to run the Code Hotspots recipe on a remote Arm target - - Use an AI agent to interpret flame graph results and identify the hottest functions in a C++ application + - Describe how the dedicated Arm Performix MCP server enables AI-driven profiling workflows + - Run the Code Hotspots recipe on a configured remote Arm target through an AI agent + - Use an AI agent to interpret profile evidence and identify the hottest functions in a C++ application - Apply AI-suggested optimizations to reduce application runtime on Arm Neoverse prerequisites: - - Completion of the [Automate x86-to-Arm application migration using Arm MCP Server](/learning-paths/servers-and-cloud-computing/arm-mcp-server/) Learning Path, or equivalent familiarity with configuring the Arm MCP Server in an AI coding assistant + - Completion of the [Generate Arm Performix AI insights in Visual Studio Code with Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/) Learning Path, or equivalent familiarity with configuring the Arm Performix MCP server in an AI coding assistant - Access to an Arm-based cloud instance running Linux, such as an AWS Graviton3 instance - Access to Arm Performix configured with the remote Arm target. See the [Arm Performix install guide](/install-guides/performix/) for setup instructions - Basic understanding of C++ @@ -34,37 +34,39 @@ generated_summary_faq: faq_generated_at: '2026-07-07T16:22:08Z' faq_source_hash: a81d31a804debf71196a478bdf388c9e58b6dab67a9e881b916f3d0169d9555d summary: >- - You'll combine the Arm MCP Server's `apx_recipe_run` tool with an AI agent to run the complete Code Hotspots workflow on an Arm Neoverse target. First, you'll build an intentionally unoptimized Mandelbrot - C++ application on a remote Arm Linux target, then use a GitHub Copilot prompt file to run - the Performix Code Hotspots recipe. The agent confirms target details, executes collection, - and returns a flame graph with structured hotspot data to pinpoint the hottest functions. + You'll combine the dedicated Arm Performix MCP server with an AI agent to run the complete Code + Hotspots workflow on an Arm Neoverse target. First, you'll build an intentionally unoptimized Mandelbrot + C++ application on a remote Arm Linux target, then use an AI agent to run the Performix Code Hotspots + recipe. The agent confirms the configured target, executes collection, and returns a run ID. You'll use + that run ID to generate AI insights with structured hotspot data to pinpoint the hottest functions. Guided by the agent, you'll apply concrete code changes, such as math simplifications and enabling - a higher optimization level, directly on the server over SSH. Then, you'll re-run the recipe to compare - results. The end-to-end flow keeps profiling, interpretation, and edits within a single AI-assisted - loop. + a higher optimization level, through your source and build environment. Then, you'll re-run the recipe + to compare results. The end-to-end flow keeps profiling, interpretation, and edits within a single + AI-assisted loop. faqs: - - question: Which prompt file should I use to run the Code Hotspots recipe? + - question: How do I configure the Arm Performix MCP server? answer: >- - Use the `arm-hotspots-optimization` prompt file from the Arm MCP Server repository with GitHub - Copilot. It directs the agent to confirm the remote target, run the recipe, and return structured - profiling results. + Follow the [Generate Arm Performix AI insights in Visual Studio Code with Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/) + Learning Path to start the installed `apx` executable with the `mcp start` arguments and verify that + your AI coding assistant can list Performix recipes and configured targets. - question: What result should I expect after the profiling run completes? answer: >- - Expect a flame graph and a hotspot summary that highlights the hottest functions in the - Mandelbrot application. Use these outputs to guide which code changes to apply first. + Expect a completed run status and a run ID. Use that run ID to request an AI insight with a hotspot + summary that highlights the hottest functions in the Mandelbrot application. Use this output to guide + which code changes to apply first. - question: Should I compile the Mandelbrot example with optimizations before profiling? answer: >- No. The single-threaded, unoptimized build is intentional so the hotspot analysis produces a clear signal. The agent later proposes enabling `-O3` as part of the optimization pass. - question: How do I know the agent is targeting the correct machine? answer: >- - The agent explicitly confirms your remote target details before running the Code Hotspots - recipe. Review this confirmation and proceed only if it matches your intended Arm target. + The agent explicitly confirms your configured Performix target name and workload before running the + Code Hotspots recipe. Review this confirmation and proceed only if it matches your intended Arm target. - question: What should I check if the Code Hotspots run fails to start? answer: >- - Confirm that Arm Performix is configured with your remote Arm target and that the MCP Server - can reach it over SSH. Also verify that the Mandelbrot application builds on the target - system. + Confirm that Arm Performix is configured with your remote Arm target and that the target connection + succeeds. Also verify that the Mandelbrot application builds on the target system. You can test the + connection with `apx target test --target `. # END generated_summary_faq author: Pareena Verma @@ -92,12 +94,12 @@ further_reading: link: /learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/ type: learning-path - resource: - title: Automate x86-to-Arm application migration using Arm MCP Server - link: /learning-paths/servers-and-cloud-computing/arm-mcp-server/ + title: Generate Arm Performix AI insights in Visual Studio Code with Codex + link: /learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/ type: learning-path - resource: - title: Arm MCP Server GitHub Repository - link: https://github.com/arm/mcp + title: Arm Performix GitHub repository + link: https://github.com/arm/performix type: website - resource: title: Arm Performix @@ -114,4 +116,3 @@ weight: 1 # _index.md always has weight of 1 to order corr layout: "learningpathall" # All files under learning paths have this same wrapper learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. --- - diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup1.png b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup1.png deleted file mode 100644 index 1e38e51be9..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup1.png and /dev/null differ diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup2.png b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup2.png deleted file mode 100644 index e6142cd145..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup2.png and /dev/null differ diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup3.png b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup3.png deleted file mode 100644 index a7939da641..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup3.png and /dev/null differ diff --git a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup4.png b/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup4.png deleted file mode 100644 index f25834f644..0000000000 Binary files a/content/learning-paths/servers-and-cloud-computing/performix-mcp-agent/images/mcp-performix-setup4.png and /dev/null differ diff --git a/content/learning-paths/servers-and-cloud-computing/performix-memory-access/_index.md b/content/learning-paths/servers-and-cloud-computing/performix-memory-access/_index.md index 3c81d15b91..27e0555708 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-memory-access/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-memory-access/_index.md @@ -1,23 +1,24 @@ --- -title: Optimize memory access behavior using Arm Performix and the Arm MCP Server +title: Optimize memory access behavior using the Arm Performix MCP server -description: Learn how to profile and optimize memory access behavior in a C++ particle simulation on Arm Linux using the Arm Performix Memory Access recipe through the Arm MCP Server. +description: Learn how to profile and optimize memory access behavior in a C++ particle simulation on Arm Linux using the Arm Performix Memory Access recipe and the Arm Performix MCP server. minutes_to_complete: 45 -who_is_this_for: This is an introductory topic for C++ developers who want to use Arm Performix and the Arm MCP Server to diagnose cache and address translation behavior in applications running on Arm Neoverse servers. +who_is_this_for: This is an introductory topic for C++ developers who want to use the Arm Performix MCP server to diagnose cache and address translation behavior in applications running on Arm Neoverse servers. learning_objectives: - Explain how L1 cache hits, TLB misses, and page walks affect C++ application performance. - Build and visualize the orbiting galaxies example on an Arm Neoverse server. - Inspect and optimize the particle data structure using insights from the memory access recipe. - - Use the Arm MCP Server in combination with Arm Performix for an agentic solution. + - Use the Arm Performix MCP server with an AI coding agent to support an optimization workflow. prerequisites: - Access to an Arm Neoverse bare metal server. - Basic understanding of memory hierarchy within a CPU. - Basic C++ development experience. - Familiarity with the Linux command line. + - An MCP-compatible coding assistant. The example uses OpenAI Codex, which requires an OpenAI account. author: Kieran Hejmadi @@ -42,7 +43,7 @@ operatingsystems: further_reading: - resource: - title: Identify code hotspots using Arm Performix through the Arm MCP Server + title: Identify and optimize code hotspots using the Arm Performix MCP server link: /learning-paths/servers-and-cloud-computing/performix-mcp-agent/ type: learning-path - resource: @@ -54,8 +55,8 @@ further_reading: link: /learning-paths/servers-and-cloud-computing/performix-microarchitecture/ type: learning-path - resource: - title: Automate x86-to-Arm application migration using Arm MCP Server - link: /learning-paths/servers-and-cloud-computing/arm-mcp-server/ + title: Generate Arm Performix AI insights in Visual Studio Code with Codex + link: /learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/ type: learning-path - resource: title: Arm Performix diff --git a/content/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-3.md b/content/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-3.md index c9ca107484..8d8a816b37 100644 --- a/content/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-3.md +++ b/content/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-3.md @@ -1,5 +1,6 @@ --- -title: Optimize the application manually and with the Arm MCP Server +title: Optimize the application manually and with the Arm Performix MCP server +description: Use Arm Performix profile evidence and its standalone MCP server to optimize the particle layout and validate the improvement. weight: 5 ### FIXED, DO NOT MODIFY @@ -33,9 +34,9 @@ To measure wall time and compare it against the baseline, run: The hot loop is instrumented with `scopedTimer`, so you'll also see the loop duration printed directly to the terminal. Compare it with the baseline result of 571 milliseconds shown at the end of the section. -## Optimize with an AI agent and the Arm MCP Server +## Optimize with an AI agent and the Arm Performix MCP server -You can use the Arm Model Context Protocol (MCP) Server with a code assistant such as Kiro, Gemini, Codex, or GitHub Copilot to optimize the application. The MCP server includes direct tool support to invoke Performix on a remote target. It integrates with MCP-compatible coding assistants and can provide performance insights to create a useful feedback loop. The following example shows how to connect to OpenAI Codex. For other tools, see [your preferred coding assistant](/learning-paths/servers-and-cloud-computing/arm-mcp-server/1-overview/). +Arm Performix includes a local Model Context Protocol (MCP) server that you can use with an MCP-compatible coding assistant. The server can list Performix targets and runs, run recipes, and make profiling evidence available to the assistant. The following example shows how to connect the Arm Performix MCP server to OpenAI Codex. For other supported coding assistants, see [Configure the Arm Performix MCP server](https://developer.arm.com/documentation/110163/latest/Gather-performance-insights-with-AI-coding-agents/Configure-the-Arm-Performix-MCP-server). {{% notice Note %}} @@ -43,33 +44,48 @@ You need an OpenAI account to use the Codex CLI. {{% /notice %}} -[Install Docker](/install-guides/docker/) and pull the MCP server image. +Arm Performix is already installed from the setup earlier in this Learning Path. Configure Codex to start the local MCP server through the Arm Performix `apx` executable. Add the following to `~/.codex/config.toml`, replacing `` with the full path for your host operating system: -```bash -docker pull armlimited/arm-mcp:latest +```toml +[mcp_servers.arm-performix] +command = "" +args = ["mcp", "start"] ``` -To ensure the MCP server can invoke `performix` on remote machines, pass optional Docker arguments for your SSH private key and known hosts file. For example, use this TOML format for the Codex CLI by adding the following to `~/.codex/config.toml`: +For default `apx` paths and configuration through the Codex interface, see [Configure the Arm Performix MCP server in Codex](/learning-paths/servers-and-cloud-computing/performix-agentic-dynamic-insights-codex/configure_mcp_codex/). -```toml -[mcp_servers.arm-mcp] -command = "docker" -args = [ - "run", - "--rm", - "-i", - "-v", "/path/to/your/workspace:/workspace", - "-v", "/path/to/your/ssh/private_key:/run/keys/ssh-key.pem:ro", - "-v", "/path/to/your/ssh/known_hosts:/run/keys/known_hosts:ro", - "armlimited/arm-mcp" -] +The MCP server uses the targets configured in Arm Performix. For remote Linux targets, configure key-based SSH access and make sure your `known_hosts` file contains the target host key. + +Restart Codex and ask it to inspect the Memory Access recipe before running it on the configured target. Replace the target name and workload path in this example: + +```text +Use the Arm Performix MCP server to inspect the parameters and target support +for the Memory Access recipe. Run the recipe on target "" with +workload "/home//Orbiting-Galaxy-Example/build/baseline". Before +starting, repeat the target and workload and ask me to confirm them. When the +run completes, return its run ID and summarize the measured L1 cache, latency, +and TLB evidence. ``` -Restart Codex and ask your coding assistant to run the `memory access` recipe, interpret the results, and inspect the relevant source code. Your prompt can include the remote target, workload binary, and source directory: +{{% notice Note %}} +Dynamic Insights aren't available for Memory Access runs. The MCP server can still run the recipe and query its measured data. Validate the L1 cache, latency, and TLB findings in the Performix GUI. +{{% /notice %}} + +The Arm Performix MCP server manages targets, recipes, and run data. It doesn't provide remote source-file access by itself. To use Codex for the code changes, make the `Orbiting-Galaxy-Example` checkout available in the Codex workspace. + +After the run completes, replace `` and ask Codex to connect the measurements to the source before proposing a change: -![Codex prompt requesting the Arm MCP server to run memory access and code hotspot recipes on the remote baseline workload, showing how to pass target, binary path, and source directory details.#center](./codex_prompt.webp "Prompting Codex to analyze the baseline workload with Arm MCP") +```text +Use the Arm Performix MCP server to query Memory Access run "". Report +the L1C load hit rate, average L1C load latency, L2C load percentage, and TLB +walk evidence for update_positions(). Then inspect src/users_solution in the +current workspace and propose a minimal data-layout optimization based on the +measurements and source. Do not edit any files until I approve the proposal. +``` + +After you approve the proposal, ask Codex to update `src/users_solution`. Rebuild the binary on the target, rerun Memory Access against `build/users_solution`, and compare the same metrics with the baseline run. If Codex can't access the target checkout, apply the proposed patch on the target and continue to use the MCP server for collection and analysis. -Alternatively, you can use the curated [arm-full-optimization.md](https://github.com/arm/mcp/blob/main/agent-integrations/codex/arm-full-optimization.md) prompt file. +For more prompt patterns, see [Example prompts for dynamic agentic insights](https://developer.arm.com/documentation/110163/latest/Gather-performance-insights-with-AI-coding-agents/Example-prompts-for-dynamic-agentic-insights). ## Review the optimized solution @@ -109,7 +125,7 @@ The following diagram compares the baseline and optimized layouts. Even though e To see what fully optimized results look like, run the Performix Memory Access recipe against the pre-built reference binary. In the Performix GUI, rerun the recipe and change the binary path from `~/Orbiting-Galaxy-Example/build/baseline` to `~/Orbiting-Galaxy-Example/build/optimized`. -![Performix Memory Access results for the optimized binary showing 100 percent L1C load hits for the selected function and lower average L1C latency, confirming improved memory locality after the data layout change.#center](./performix_after_optimization.webp "Memory access results after the Structure of Arrays optimization") +![Performix Memory Access results for the optimized binary showing 99.99 percent L1C load hits and 10.89-cycle average L1C latency for update_positions(), confirming improved memory locality after the data layout change.#center](./performix_after_optimization.webp "Memory access results after the Structure of Arrays optimization") The optimized result shows much stronger L1 cache behavior. The hot update path now has `100%` L1C loads in the captured result and a lower average L1C latency than the baseline. This confirms that the data layout change improved locality, not just wall-clock time. @@ -124,6 +140,8 @@ Run the binaries directly on the remote machine without Performix to compare bot The hot loop is also instrumented with `scopedTimer`, so you can directly observe the speedup from the change. +The output is similar to: + ```output Baseline took 571 milliseconds Command being timed: "./build/baseline" @@ -162,12 +180,12 @@ Optimized took 279 milliseconds | Wall time (ms) | 571 | 279 | The optimized layout improves cache usage and removes pointer chasing, roughly halving execution time. | | Max RSS (KB) | 92,720 | 64,044 | Structure of Arrays reduces memory footprint by removing per-object overhead and cold fields. | | Minor page faults | 22,655 | 15,500 | Fewer pages are touched due to more compact, contiguous storage of only needed data fields. | -| L1 cache hit rate (%) | 66.3 | 99.3 | Hot data is now accessed in a cache-friendly pattern, maximizing L1 cache effectiveness. | -| L1 avg latency (cycles)| 26.2 | 11.7 | Each L1 load takes fewer cycles because pointer chasing is removed. | +| L1 cache hit rate (%) | 66.32 | 99.99 | Hot data is now accessed in a cache-friendly pattern, maximizing L1 cache effectiveness. | +| L1 avg latency (cycles)| 26.15 | 10.89 | Each L1 load takes fewer cycles because pointer chasing is removed. | ## What you've accomplished -You used Arm Performix and the Arm MCP Server to identify a memory access bottleneck in a C++ particle simulation. You then connected the profile data to source code, found that the hot loop suffered from poor data layout and unnecessary pointer chasing, and improved the implementation with a Structure of Arrays layout. You validated the change with direct wall-time measurements and a second Performix run. +You used Arm Performix manually and through the Arm Performix MCP server to identify a memory access bottleneck in a C++ particle simulation. You then connected the profile data to source code, found that the hot loop suffered from poor data layout and unnecessary pointer chasing, and improved the implementation with a Structure of Arrays layout. You validated the change with direct wall-time measurements and a second Performix run. This approach combines measurement tools, code context, and focused prompts to iterate on real bottlenecks.