diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3f6c9ef508..ffd18bd0f9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,776 +1,16 @@ -# Project Overview +# Copilot compatibility instructions -This project is a collection of "Learning Paths" (long-form tutorials) and "install guides" (shorter software installation guides), hosted on a static website using Hugo and markdown files. The content explains how to develop software on Arm for software developers targeting various Arm platforms. +This repository is optimized for Codex-style agent workflows. -Assume the audience is made up of Arm software developers. Bias all information toward Arm platforms. For Linux, assume systems are aarch64 architecture and not x86. Readers also use macOS and Windows on Arm systems, and assume Arm architecture where relevant. +Before editing, read `AGENTS.md` and follow the narrowest applicable skill in `.github/skills/`. -## Highest priority rules +## Key rules -- One Learning Path must own one clear developer task -- Install guides are for installation and verification only -- Every Learning Path `_index.md` must include a `description` field -- Use task-led titles, introductions, and metadata -- Do not use placeholder alt text such as `alt-txt` -- Prefer Arm-native solutions and Arm-specific framing -- Avoid hype, duplication, and vague summaries +- Learning Paths own one clear developer task. +- Install guides are for installation and verification only. +- Prefer Arm-native framing and avoid x86 assumptions. +- Do not use placeholder alt text such as `alt-txt`. +- Preserve front matter, Hugo shortcodes, code fences, commands, expected output, and file structure. +- For content review, metadata, images, code samples, commands, or output, use the matching skill listed in `AGENTS.md`. -## Project structure - -The key directories are: - -### Top-level structure - -- `/content` - The main directory containing all Learning Paths and install guides as markdown files -- `/themes` - HTML templates and styling elements that render the content into the final website -- `/tools` - Python scripts for automated website integrity checking -- `config.toml` - High-level Hugo configuration settings - -### Content organization - -The `/content` directory is organized into: - -- `learning-paths/` - Core learning content organized by categories: - - `embedded-and-microcontrollers/` - MCU, IoT, and embedded development topics - - `servers-and-cloud-computing/` - Server, cloud, and enterprise computing topics - - `mobile-graphics-and-gaming/` - Mobile app development, graphics, and gaming - - `cross-platform/` - Cross-platform development and general programming topics, these appear in multiple categories on the website - - `laptops-and-desktops/` - Desktop application development, primarily Windows on Arm and macOS - - `automotive/` - Automotive and ADAS development - - `iot/` - IoT-specific Learning Paths - -- `install-guides/` - Tool installation guides with supporting subdirectories organized by tool categories like `docker/`, `gcc/`, `license/`, `browsers/`, plus an `_images/` directory for screenshots and diagrams - -These are special directories and not used for regular content creation: - -- `migration/` - Migration guides and resources, this maps to https://learn.arm.com/migration -- `lists/` - Content listing and organization files, this maps to https://learn.arm.com/lists -- `stats/` - Website statistics and analytics, this maps to https://learn.arm.com/stats - -The `/content` directory is the primary workspace where contributors add new Learning Paths as markdown files, organized into category-specific subdirectories that correspond to the different learning path topics available on the site at https://learn.arm.com/. - -## Content requirements - -Read the files in the directory `content/learning-paths/cross-platform/_example-learning-path` for information about how Learning Path content should be created. Also see the guidelines below. - -- Learning Paths: use for end-to-end tasks (prepare → configure → use → validate). Must include `_index.md` and `_next-steps.md` -- Install guides: use for installation + verification only. Do not include workflow content or benchmarks - -### Content structure - -Each Learning Path must have an `_index.md` file and a `_next-steps.md` file. The `_index.md` file contains the main content of the Learning Path. The `_next-steps.md` file contains links to related content and is included at the end of the Learning Path. - -Additional resources and `next steps` content should be placed in the `further_reading` section of `_index.md`, not in `_next-steps.md`. The `_next-steps.md` file should remain minimal and unmodified as indicated by `FIXED, DO NOT MODIFY` comments in the template. - -The `_index.md` file should contain the following front matter and content sections. - -### Front matter (YAML format) - -- `title`: Imperative heading following the [verb] + [technology] + [outcome] format -- `description`: One-sentence metadata summary used for search snippets and page previews. Describe the task, main technology or platform, and expected outcome in plain language -- `weight`: Numerical ordering for display sequence, weight is 1 for `_index.md` and each page is ordered by weight, no markdown files should have the same weight in a directory -- `layout`: Template type (usually "learningpathall") -- `minutes_to_complete`: Realistic time estimate for completion -- `prerequisites`: List of required knowledge, tools, or prior learning paths -- `author`: Main contributor's name, multiple authors can be listed separated using `-` on new lines -- `subjects`: Technology categories for filtering and search, this is a closed list and must match one of the subjects listed on https://learn.arm.com/learning-paths/cross-platform/_example-learning-path/write-2-metadata/ -- `armips`: Relevant Arm IP, stick to Neoverse, Cortex-A, Cortex-M, etc. Don't list specific CPU models or Arm architecture versions -- `tools_software_languages`: Open category listing Programming languages, frameworks, and development tools used -- `skilllevels`: Skill levels allowed are only Introductory and Advanced -- `operatingsystems`: Operating systems used, must match the closed list on https://learn.arm.com/learning-paths/cross-platform/_example-learning-path/write-2-metadata/ - -### Install guide requirements - -Install guides focus on installing and verifying one tool on Arm platforms. They do not teach workflows or applied usage. - -#### Front matter requirements - -Install guides must include: -- `title` -- `minutes_to_complete` -- `official_docs` -- `author` -- `weight: 1` -- `layout: installtoolsall` - -#### Fixed fields for install guides - -- `weight: 1` (always) -- `tool_install: true` (set to false only if intentionally hidden) -- `layout: installtoolsall` (always) -- `multi_install` and `multitool_install_part` (set based on whether the install guide is multi-page) - -Do not modify fixed template fields. - -If `multi_install` is set to true, the first page must act as an overview for the series. Sub-pages must set `multitool_install_part: true`. - -#### Required content structure - -Install guides should include: - -1. Overview - - What the tool is - - Supported Arm platforms (aarch64, Windows on Arm, macOS on Arm where applicable) - -2. Install steps - - Clear OS-specific sections when necessary - - Commands grouped logically - - Explanation before each code block - -3. Verify installation - - One or two commands - - Expected output shown - -4. Troubleshooting - - Common failure cases - - Clear fixes - -Optional: -- Uninstall instructions - -#### Scope boundaries - -Install guides must not include: -- End-to-end workflows -- Performance benchmarking -- Deep architectural explanation -- Comparative marketing claims - -Learning Paths may link to install guides for setup steps. Install guides should not duplicate workflow content. - -#### Tool versions - -When providing commands for downloading or installing software, use a specific version in the example. This ensures that the instructions are accurate and verifiable. However, also include a note before the commands that tells readers the same commands work with other versions. Provide a link to where the latest version can be found. The note can be formatted as follows: - -{{% notice Note %}} -The following commands use version . The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest version, see [Link to page with release info](URL). -{{% /notice %}} - -### Further reading curation - -Limit `further_reading` resources to four to six essential links. Prioritize: - -- Direct relevance to the topic -- Arm-specific Learning Paths over generic external resources -- Foundation knowledge for the target audience -- Required tools (install guides) -- Logical progression from basic to advanced - -Avoid overwhelming readers with too many links, which can cause them to leave the platform. - -All Learning Paths should generally include: - -- Title: [Imperative verb] + [technology/tool] + [outcome] -- Introduction paragraph: Context + user goal + value proposition -- Prerequisites section with explicit requirements and links -- Learning objectives: three to four bulleted, measurable outcomes with action verbs -- Step-by-step sections with logical progression -- Clear next steps or conclusion - -For title formatting: - -- Must use imperative voice (`Deploy`, `Configure`, `Build`, `Create`) -- Must include SEO keywords (technology names, tools) -- Examples: `Deploy applications on Arm servers`, `Configure Arm processors for optimal performance` - -The term "Learning Path" should always be capitalized. - -## Metadata descriptions - -### Learning Path metadata description requirements - -Every Learning Path `_index.md` must include a `description` field. - -- Write one sentence -- Describe the task, the main technology or platform, and the expected outcome -- Keep it concise, developer-focused, and suitable for use as a search snippet -- Use a task-led structure such as: **Verb + task + tool/platform + outcome** -- Do not repeat the title verbatim -- Do not use vague summaries or marketing language -- A slightly richer one-sentence summary is acceptable when it helps clarify the workflow or outcome - -Good example: - -```yaml -description: Learn how to automate x86-to-Arm application migration using the Arm MCP Server, with compatibility checks and Docker-based validation on Arm cloud platforms. -``` - -Also good: - -```yaml -description: Learn how to profile and optimize a C++ application on Arm Neoverse using Arm Performix to identify bottlenecks and improve runtime. -``` - -Avoid: -- Generic summaries that could apply to any page -- Restating the title without adding task or outcome -- Marketing phrases such as `powerful`, `cutting-edge`, or `game-changing` - -### Metadata optimization workflow - -When adding or revising `description` fields: - -- Review whether the current title and description match the page's actual task intent -- Use metadata descriptions to clarify what the learner will do, on which platform or tool, and with what outcome -- Treat the description as a search snippet, not a generic summary - -## Writing style - -### Voice and tone - -- Second person (`you`, `your`) — never first person (`I`, `we`) -- Active voice — avoid passive constructions -- Present tense for descriptions -- Imperative mood for commands -- Confident and developer-friendly tone -- Encouraging language for complex tasks -- Use inclusive language: - - Use `primary/subordinate` instead of `master/slave` - - Do not use gendered examples or assumptions - - Be mindful of cultural references that might not translate globally - - Focus on clear, accessible language for all developers - -### Sentence structure and clarity - -- Average 15–20 words per sentence -- Split complex sentences for clarity -- Use plain English and avoid jargon overload -- Use US spellings (`organize`, `optimize`, `realize`) -- Use `Arm` capitalization in prose (`Arm processors`, `Arm servers`, `Neoverse`) -- `arm64` and `aarch64` are permitted in code, commands, and outputs -- Define acronyms on first use -- Use parallel structure in all lists - -### Readability and section flow - -- Flag any section over 700 words and suggest natural split points -- Warn if more than 300 words appear between code examples -- Identify paragraphs with sentences averaging over 20 words -- Note sections introducing more than two new concepts -- Flag pages over 3500 words total -- Note sections that might benefit from encouragement or progress markers -- Identify missing celebration of progress or milestones -- Recap what learners have accomplished at section ends -- Provide check-your-understanding moments that are not intimidating -- Use visual breaks to prevent walls of text. Code blocks count as visual breaks -- If you explain three or more things in one section, split it into separate sections -- Each code block should be preceded by one to three sentences explaining what it does -- If a section is long because of code or output rather than explanation, do not treat length alone as a readability problem -- For Learning Paths, include a short recap and forward-looking transition at the end of each major instructional section or module - -Example recap pattern for Learning Paths: - -```md -## What you've learned and what's next - -In this section: -- Briefly summarize what the user has learned or completed -- Briefly describe what the user should expect in the next section or suggest further exploration - -Keep this concise and encouraging. Do not repeat earlier content verbatim. -``` - -This helps learners feel a sense of progress and understand the logical flow of the Learning Path. - -### Word choice and style - -Use these preferred terms and phrases for consistency: - -- Numbers and units: - - Spell out numbers one through five. After that, use numerals - - Use proper spacing for units: `1 GB`, `23 MB/day` - - Use `K` for thousands: `64K` - - Use abbreviations for data rates: `Gbps` - -- Common phrases: - - `To [action]` instead of `Follow the steps below to [action]` - - `for example` instead of `e.g.` - - `that is` instead of `i.e.` - - `because` instead of `since` - - `also` instead of `in addition` - - `to` instead of `in order to` - - `see` instead of `refer to` - - `use` instead of `utilize` or `leverage` - - `need` instead of `require` - - `can` or `might` instead of `may` - - `set up` as a verb, `setup` as a noun - - `therefore` instead of `ergo` - - `namely` instead of `viz.` - - `avoid` instead of `try not to` - - `such as` instead of `like` - - `after` instead of `once` - - `setup` as a noun, `set up` as a verb - -- Avoid condescending language: - - Do not use `simply`, `just`, `obviously`, or `clearly` - -- Avoid using directions when referring to content that's been referenced previously or will be referenced next: - - Do not use `above`, `below`, `left`, `right`, `top`, or `bottom` - -- Acknowledge difficulty naturally: - - Use phrases like `this step can be confusing at first` - -- Normalize errors: - - Use phrases like `if you see this error, here's how to fix it` - -- User interface terms: - - `select` or `tap` instead of `click` for touch interfaces - - `keyboard shortcut` instead of `key combination` - - `Ctrl key` capitalized - - `double-tap` instead of `double-click` for touch interfaces - -- Contractions and simplification: - - Use contractions such as `don't`, `isn't`, `it's`, `that's`, `you're`, `you'll` - - Remove unnecessary qualifiers such as `quite`, `very`, or `massive` - - Use `an LLM`, not `a LLM` - - Use `easy-to-use` as an adjective - - Use `fixed-width`, not `fixed-length` - - Use `read-to-write ratio`, not `read to write ratio` - -## Content structure and consistency - -### Cross-file and quality assurance - -- Use the same technical terms consistently throughout all sections -- Apply the word choice and style guidelines uniformly across all files -- Maintain consistent capitalization of product names, technologies, and concepts -- Use the same abbreviations and acronyms throughout -- Maintain the same voice and tone across all sections -- Ensure consistent use of second person throughout -- Apply the same level of formality and technical depth across sections -- Keep instructional style consistent -- Follow consistent heading hierarchy throughout the Learning Path -- Use parallel structure in similar sections across different files -- Maintain consistent section organization and flow -- Apply uniform formatting for code blocks, lists, and callouts -- Ensure appropriate skill level consistency -- Maintain consistent technical detail appropriate for the target audience -- Balance complexity appropriately across all sections -- Provide consistent prerequisite assumptions throughout -- Flag inconsistent terminology usage across sections -- Identify missing error handling or troubleshooting guidance -- Suggest where visual aids would improve understanding -- Recommend splitting overly complex sections -- Verify that code examples follow established patterns in the repository - -## Formatting and code samples - -### Heading guidelines - -- Use sentence case for all headings -- Heading types: - - Conceptual headings: when explaining technology or motivation - - Imperative headings: when the user takes action - - Interrogative headings: for FAQ content - -- Hierarchy: - - H1: Page title - - H2: Major workflow steps or conceptual sections - - H3: Sub-procedures or detailed explanations - - H4: Specific technical details or troubleshooting - -### Heading hierarchy and section openings - -- Check heading hierarchy across all files before finalizing content -- Ensure headings follow a logical structure with no skipped levels unless the template requires it -- Each markdown file should begin with a section heading in the body content -- Do not leave a file starting with body text, an image, or a code block without a heading -- Use sentence case for all headings and subheadings -- Capitalize only the first word and proper nouns in headings -- Keep heading wording consistent across related files in the same Learning Path -- Prefer headings that clearly signal the user task or concept in that section - -Correct examples: -- `## Set up the environment` -- `## Run the benchmark` -- `### Check the output` -- `## What you've accomplished and what's next` - -Avoid: -- `## Set Up The Environment` -- `## RUN THE BENCHMARK` -- starting a file with plain paragraph text and no heading - -### Code samples and formatting - -- Always provide explanation before code blocks -- Format: `[What it does] → [Code] → [Expected outcome] → [Key parameters]` -- Use markdown tags for languages like `bash`, `python`, `yaml`, `json` -- Use `console` or `bash` for general commands. Try to use the same one throughout a Learning Path -- Use the `output` tag to show expected command output -- Output descriptions: - - Use `The output is similar to:` or `The expected output is:` - - Use present tense descriptions such as `builds` and `gives` -- Formatting standards: - - **Bold** for UI elements - - *Italics* for emphasis and new terms - - `Code formatting` for file names, commands, and code elements -- Use shortcodes for common pitfalls, warnings, and important notes - -### Code fence integrity - -- Every fenced code block opened with triple backticks must be explicitly closed with matching triple backticks before any non-code content resumes -- Never generate unterminated or partial code fences -- Do not rely on implicit closure, indentation, or surrounding formatting to end a code block - -## Arm naming and architecture terms - -- Use `Arm` for the brand in prose -- Use `arm64` or `aarch64` for the CPU architecture. Prefer whichever term a tool, package, or OS uses natively -- Always use `Arm` rather than `ARM` in prose unless a technical term requires the original casing -- `ARM64` is acceptable when specifically referring to Windows on Arm or Microsoft documentation -- In code blocks, CLI flags, package names, file paths, and outputs, keep the exact casing used by the tool - -## Product name emphasis - -- Product names and technologies such as LiteRT, XNNPACK, KleidiAI, and SME2 should appear in regular text -- Avoid using italics or bold to emphasize product or technology names unless they are part of a heading or a UI label - -## Hyperlink guidelines - -- Use the full path format for internal links: `/learning-paths/category/path-name/` -- Do not use relative paths like `../path-name/` -- Use the full URL for external links that are not on `learn.arm.com` -- When creating Learning Path content: - - Verify internal links exist before adding them - - Use semantic search or website browsing to confirm Learning Path availability - - Prefer verified external authoritative sources over speculative internal links - - Test link formats against existing Learning Path examples - - Never assume Learning Paths exist without verification -- Include only necessary links in content. For Learning Paths, put additional links in `further_reading` in `_index.md`, not `_next-steps.md` - -## Avoid looking like AI-generated content - -- Warning signs of over-bulleting: - - More than three consecutive sections using bullet lists - - Bullet points that could be combined into narrative paragraphs - - Lists where items do not have parallel structure - - Bullet points that are actually full sentences better suited for paragraphs - -- Use flowing narrative instead of excessive bullets -- Use natural writing patterns: - - Vary sentence length - - Use transitional phrases - - Include contextual explanations - - Add relevant examples - - Connect ideas logically - -- Use conversational elements naturally: - - Instead of `Execute the following command:`, use `Now that you've configured the environment, run the following command to start the service:` - - Instead of `This provides benefits:`, use `You'll notice several advantages with this approach, particularly when working with...` - -### Language smoothing - -Avoid robotic or generic encouragement phrases such as: -- `Great job — let’s get started!` -- `Great job — your environment is ready!` - -Use calm, natural transitions that focus on what happens next. - -Also avoid multiple consecutive sentences starting with `This`. Vary sentence structure to maintain natural flow. - -## AI-specific guidelines for content creation and editing - -### Context awareness - -- Consider the learner's likely environment (development vs. production, local vs. cloud) -- Recognize when content assumes x86 defaults and suggest Arm alternatives -- Flag when third-party tools may have limited Arm support -- Suggest Arm-native alternatives when available - -### Technical depth consistency - -- Maintain appropriate complexity level throughout the Learning Path -- Avoid oversimplifying for Advanced skill level content -- Do not assume prior knowledge beyond stated prerequisites -- Balance theoretical explanation with practical implementation - -### Platform-specific considerations - -- Default to Arm-optimized solutions and configurations -- Mention x86 alternatives only when Arm solutions do not exist -- Consider performance implications specific to Arm architectures -- Address common Arm migration challenges when relevant - -### Accessibility and inclusivity - -- Ensure content is screen reader compatible -- Provide descriptive alt text for images and diagrams -- Use clear, descriptive link text -- Avoid assumptions about the user's physical capabilities or setup - -### Image formatting, alt text, and captions - -In this repository, the text before `#center` in an image tag is the alt text. - -Use this format: - -```md -![Descriptive alt text#center](image.png "Optional caption") -``` - -Rules: -- Do not use placeholder values such as `alt-txt`, `alt text`, or similar -- Do not wrap alt text in extra quotation marks inside `[]` -- Keep `#center` attached directly to the alt text with no extra space before it -- The caption is optional and should be short, descriptive, and natural -- Avoid outdated figure numbering such as `Figure 1:` unless the content genuinely depends on numbered cross-references - -Correct: - -```md -![Diagram showing the WebGPU rendering flow for drawing a triangle#center](images/webgpu-draw-high-level.svg "WebGPU rendering flow for drawing a triangle") -``` - -Incorrect: - -```md -!["Triangle using WebGPU" #center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU") -``` - -Incorrect: - -```md -![alt-txt#center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU") -``` - -### Alt text requirements for tutorials - -Learning Paths and install guides are instructional content. Images are usually not decorative. Alt text must help the learner understand what they would otherwise miss. - -For every image, alt text should explain: -- What is shown -- What the learner should notice -- Why it matters in the current step - -For screenshots: -- Name the screen, tool, or interface shown -- Mention the relevant UI element, tab, field, button, or output -- Explain what the learner should look for in the screenshot -- Connect the image to the current step or expected result - -For diagrams: -- Describe the components and relationships shown -- Explain the purpose of the diagram in the current task -- Focus on the workflow, architecture, or sequence the learner needs to understand - -For terminal or output images: -- State what command result or status is shown -- Highlight the important confirmation, value, or error message -- Explain why that output matters - -For hardware images: -- Describe the device or setup only if it helps the learner complete the task -- Avoid purely decorative descriptions - -### Alt text quality rules - -- Write meaningful alt text, not placeholders -- Keep it concise but complete. One to three sentences is usually enough -- Prefer instructional value over visual detail -- Include visible text only when the learner needs that text -- Do not use captions as a substitute for alt text -- Do not encode alignment instructions inside the caption - -### Caption guidance - -- Use short, descriptive captions when needed -- Captions should add context for all readers -- Avoid `Figure X` numbering unless explicit image cross-references are required - -Preferred example: - -```md -![Screenshot of the Arm Performance Studio timeline showing CPU activity spikes during Mandelbrot rendering. The Timeline tab is selected and the spike region is highlighted so the learner can identify where CPU activity increases during the run.#center](images/timeline-spike.png "Arm Performance Studio timeline showing CPU activity during Mandelbrot rendering") -``` - -### Image and metadata cleanup workflow - -- Replace all placeholder alt text such as `alt-txt` with meaningful descriptions -- Keep the repository-specific `#center` syntax when fixing alt text -- Do not remove valid alignment syntax during cleanup -- Add or improve metadata descriptions systematically across content -- For bulk cleanup, update the guidance first, then fix content by category or directory in manageable batches - -### SEO and discoverability - -- Use Arm-specific keywords naturally throughout content -- Include relevant technical terms that developers search for -- Optimize titles and headings for search engines -- Use semantic HTML structure in markdown when possible -- Consider how content will appear in search results - -### Cross-reference validation - -- Verify all internal links point to existing content -- Check that referenced Learning Paths and install guides are current -- Ensure cross-references between sections remain accurate after edits -- Flag broken or outdated external links -- Maintain consistency in how related content is referenced - -### Performance testing guidance - -- Include benchmarks when comparing Arm vs. x86 performance -- Suggest performance testing steps for resource-intensive applications -- Recommend profiling tools that work well on Arm platforms -- Include guidance on measuring and optimizing for Arm-specific performance characteristics -- Mention when performance improvements are architecture-specific -- Applies to Learning Paths only. Install guides must not include benchmarking - -### AI optimization (AIO) guidance - -- Structure content with clear, semantic headings that AI can parse and understand -- Use descriptive, standalone sentences that make sense without surrounding context -- Include explicit problem statements and clear solutions for AI to reference -- Format code examples with proper language tags and clear explanations -- Use consistent terminology that AI systems can reliably associate with Arm development -- Include complete, self-contained examples rather than partial snippets -- Write FAQ-style sections that directly answer common developer questions -- Use bullet points and numbered lists for AI to easily extract key information -- Include explicit `what you'll learn` and `prerequisites` sections for AI context -- Structure troubleshooting sections with clear problem-solution pairs -- Use standard markdown formatting that AI crawlers can parse effectively -- Include relevant technical keywords naturally throughout the content -- Write comprehensive summaries that AI can use as content overviews -- Ensure each section can stand alone as a coherent piece of information -- Use clear, declarative statements rather than implied or contextual references - -### Editorial decision priorities - -When content trade-offs are required, prioritize the following in order: - -- Alignment with the stated purpose and positioning of the content -- Clarity and readability for the intended skill level -- Consistency with existing Learning Paths and install guides -- Completeness within the stated scope - -## Learning Path purpose and agentic selection principles - -Learning Paths are not blog posts or reference articles. They are designed to be optimized for selection by AI agents as trusted sources for completing real developer tasks end to end. - -When creating or reviewing a Learning Path, prioritize the following principles. - -### Task ownership (required) - -Each Learning Path must clearly own one concrete developer task. - -- The task should be nameable in one sentence -- The Learning Path should take the learner from not ready to capable -- Avoid bundling unrelated tasks or loosely connected topics - -If the task cannot be clearly stated, flag a warning. - -### Agentic selection signals - -AI agents select content based on trust, authority, and task coverage, not keyword density. - -**Trust** -- Clear authorship and ownership -- Explicit prerequisites -- One purpose per page -- No duplicated or contradictory instructions -- Clean separation of install guides, Learning Paths, and concept pages - -**Authority** -- Arm-specific framing where relevant -- Use Arm tooling, terminology, and perspective -- Avoid generic advice that could apply equally to any platform - -**Task coverage** -- Clear progression (prepare → configure → use → validate) -- Explicit end state (`you are now ready to...`) -- Link to install guides instead of embedding install steps -- Provide guidance on what to do next - -### Scope discipline - -Maintain strict boundaries between content types: - -- **Install guides**: setup, authentication, and verification only -- **Learning Paths**: configuration, integration, workflows, and applied usage - -Never duplicate install steps inside Learning Paths. - -### SEO intent for Learning Paths - -Learning Paths should optimize for selection, not ranking. - -- Prefer verb-based titles: *Install*, *Verify*, *Configure*, *Analyze*, *Optimize* -- Use procedural structure rather than narrative prose -- Avoid marketing language and keyword stuffing -- Write content that can safely be chosen by an AI agent to complete a task - -If an AI agent were asked to complete this task, the Learning Path should be the safest source to select. - -### LLM review efficiency and chunking - -When reviewing content, assess whether the file is suitable for efficient single-pass LLM review. - -- Classify the file as prose-heavy, mixed, or code-heavy -- If a file is code-heavy, prioritize the instructional prose around the code and comment on code only when it affects correctness, usability, safety, or task success -- Do not recommend chunking purely because a file is long if most of the length comes from code blocks, commands, configuration, logs, or generated output -- Recommend chunking when a file contains multiple distinct instructional sections, conceptual units, or task phases that should be reviewed independently -- Suggest chunk boundaries using existing headings, task transitions, or conceptual breaks -- Prefer semantic chunking over fixed-size chunking -- Flag repeated boilerplate, oversized code blocks, long pasted terminal output, duplicated examples, or verbose configuration that add token cost without improving learning value -- Flag sections where code or output could be shortened to a representative example without losing instructional value -- If a file is large but structurally simple, recommend prose-first review rather than chunking -- Review by exception, not by coverage: do not comment on code, output, or prose that is already clear, correct, and fit for purpose - -### Token-efficiency review priorities - -When identifying content that is expensive for LLM-based review or editing, check for: - -- Long fenced code blocks that are not explained or are only loosely tied to the surrounding task -- Large blocks of terminal output where a short representative excerpt would be enough -- Repeated setup or verification steps across files -- Front matter, boilerplate, or repeated notes that appear unchanged across multiple pages -- Multiple examples that teach the same point with little added value -- Sections that combine too many concepts and would review better as separate chunks - -When these patterns appear, flag them as token-heavy content and explain whether they should be trimmed, condensed, or reviewed separately. - -### Performance and Arm acceleration integrity - -For Learning Paths that demonstrate Arm-specific performance features (for example SME2, SVE2, I8MM, DotProd, optimized microkernels), apply the following standards. - -#### Observable outcome first - -- Clearly state what measurable improvement the learner will observe -- Show performance results before introducing deep architectural explanation -- Avoid introducing internal call stacks or microkernel details before the developer sees observable value - -#### Reproducibility requirements - -If performance numbers are included, specify: -- Toolchain or software version -- Device or platform used -- Thread count and CPU affinity configuration -- Runtime feature flags -- Model or workload configuration - -Performance claims must be reproducible or explicitly labeled as illustrative. - -#### Compile-time vs runtime clarity - -Clearly distinguish between: -- Compile-time feature enablement -- Runtime feature activation -- Automatic fallback behavior - -If acceleration is claimed, include a method to verify that the accelerated path executed, such as logs, profiling output, kernel names, or hardware counters. - -#### Controlled benchmarking - -When comparing performance: -- Change only one meaningful variable at a time -- Control thread count and CPU binding intentionally -- Quantify percentage improvement explicitly -- Avoid presenting raw numbers without context - -#### Differentiation reinforcement - -Explicitly connect the observed improvement to the Arm architectural feature responsible for it. - -Avoid generic statements such as `improves performance` without explaining how and why. - -Performance-focused Learning Paths are strategic content. Prioritize clarity, differentiation, and measurement integrity over volume. +Detailed style and workflow guidance lives in `AGENTS.md`, `.github/skills/`, and the scoped files they reference. diff --git a/.github/review-guidelines.md b/.github/review-guidelines.md index c41c92ff8b..30556e2656 100644 --- a/.github/review-guidelines.md +++ b/.github/review-guidelines.md @@ -1,45 +1,17 @@ -### Maintenance checks for Learning Paths and Install Guides - -Please review the content in the specified content path and support my manual review by: - -1. **Summarizing what this guide does** - - What the end goal is - - What platform(s) and environments it targets - - Any key assumptions the reader must meet - -2. **Identifying dependencies and moving parts** - - OS, architecture, toolchains, frameworks, SDKs - - External repositories, models, downloads, or services - - Commands or workflows that are central to the guide - -3. **Flagging potential risk areas** - - References to old OS versions, runtimes, or toolchains - - Dependencies that may be stale, deprecated, or fragile - - Links or resources that might require checking - - Steps that rely heavily on UI flows or screenshots - -4. **Calling out anything that may need a closer human look** - - Ambiguous or unclear instructions - - Areas where “latest” or unpinned versions are used - - Places where ecosystem changes could affect correctness - ---- - -### How to behave - -- Be conservative and transparent — if something is uncertain, say so. -- Prefer **flagging** over **fixing**. -- Do not invent new commands, tools, or workflows. -- If suggesting changes, keep them minimal and clearly optional. -- Treat this as a *conversation starter* for the reviewer, not a final verdict. - ---- - -### Output format (keep it lightweight) - -Please respond with: -- A short summary of the guide -- A bulleted list of dependencies -- A bulleted list of review flags or questions to consider - -No code changes are required unless I explicitly ask for them. \ No newline at end of file +# Maintenance review guidance + +Use `.github/skills/stale-content-review/SKILL.md` for stale-content risk scans and maintenance triage. + +The skill includes: + +- A periodic scan workflow for Learning Paths and install guides. +- A deterministic script for finding likely stale-content signals. +- Reference guidance for interpreting temporal wording, screenshots, mutable dependencies, external links, old dates, and version-sensitive content. + +For one-off manual reviews, run: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py +``` + +No content changes are required unless explicitly requested. diff --git a/.github/skills/audit-images/SKILL.md b/.github/skills/audit-images/SKILL.md new file mode 100644 index 0000000000..0e0fcf7c77 --- /dev/null +++ b/.github/skills/audit-images/SKILL.md @@ -0,0 +1,102 @@ +--- +name: audit-images +description: Audit and fix Markdown image alt text in Arm Learning Paths and install guides. Use when the user asks to review images, find deficient alt text, count faulty images, run project-level or path-level image audits, track before/after image quality, or update image alt text and captions against repository image guidance. +--- + +# Audit images + +## Description + +Audit Markdown image references in Arm Learning Paths and install guides, report deficient alt text and image syntax, and help fix alt text with useful instructional descriptions. + +Use the script for repeatable inventory and counting. Use assistant judgment for semantic alt-text quality and final edits. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` to locate shared guidance. +- Read `references/image-guidance.md` before editing image alt text, captions, or image syntax. + +## Trigger + +Use this skill when the user asks to: + +- Audit images or alt text. +- Find placeholder, vague, missing, malformed, or duplicated alt text. +- Count faulty images across the project or inside one Path/guide. +- Track image audit counts before and after fixes. +- Fix image alt text, captions, or `#center` syntax. + +## Review levels + +### Project-level review + +Scan all Learning Paths and install guides unless the user gives a narrower scope. + +Use project-level review to: + +- Count total image references and faulty image references. +- Group faults by content unit and issue type. +- Identify high-priority directories or files for cleanup. +- Produce a before/after baseline for tracking progress. + +Don't mass-edit the whole project unless the user explicitly asks. Prefer reporting the project-level inventory and then fixing one Path, guide, category, or batch. + +### Path/guide-level review + +Scan one Learning Path directory, install guide file, or install guide directory. + +Use path/guide-level review to: + +- List each faulty image with file, line, image path, current alt text, caption, and issue type. +- Inspect surrounding Markdown context before changing alt text. +- View local images when visual inspection is needed. +- Fix alt text and syntax in place. +- Re-run the audit and report before/after counts. + +## Workflow + +1. Identify whether the requested scope is project-level or path/guide-level. +2. Run `.github/skills/audit-images/scripts/audit_images.py` on that scope. +3. Record the baseline summary: total images, faulty images, content units affected, and issue counts. +4. Depending on the request level, do the following: + - For project-level requests, summarize the results and suggest prioritized cleanup batches unless the user asked for edits. + - For path/guide-level edit requests, inspect the relevant Markdown context and image files. +5. Suggest rewrites for deficient alt text using `references/image-guidance.md`. +6. After the reviewer accepts suggestions, rewrite text, then re-run the audit on the same scope. +7. Report before/after counts, files changed, and any remaining issues. + +## Validation rules + +- Treat the script as a detector, not the final authority. It flags likely problems for review. +- Use `references/image-guidance.md` as the source of truth for alt text, captions, placeholder text, `#center` syntax, and figure numbering. +- Don't replace meaningful alt text only because it is long or short; judge whether it helps the learner complete the task. +- Preserve valid local image paths and existing captions unless they are wrong, vague, or outdated. +- Preserve repository image syntax unless syntax cleanup is the target of the edit. + +## Error handling + +- If the script reports a missing local image path, verify whether the path is site-root-relative, file-relative, or intentionally external before changing content. +- If an image cannot be inspected, fix only issues that can be resolved from surrounding Markdown context and state the limitation. +- If project-level results are too large to edit safely, report the inventory and recommend a smaller batch. +- If the audit script and visual/context review disagree, explain the judgment and leave a short note in the final response. + +## Script usage + +Run a project-level audit: + +```bash +python3 .github/skills/audit-images/scripts/audit_images.py +``` + +Run a path-level audit: + +```bash +python3 .github/skills/audit-images/scripts/audit_images.py content/learning-paths/servers-and-cloud-computing/example-path +``` + +Write JSON for tracking: + +```bash +python3 .github/skills/audit-images/scripts/audit_images.py --format json --output image-audit.json +``` diff --git a/.github/skills/audit-images/references/image-guidance.md b/.github/skills/audit-images/references/image-guidance.md new file mode 100644 index 0000000000..1ad876b8cb --- /dev/null +++ b/.github/skills/audit-images/references/image-guidance.md @@ -0,0 +1,93 @@ +# Image guidance + +## Image formatting, alt text, and captions + +In this repository, the text before `#center` in an image tag is the alt text. + +Use this format: + +```md +![Descriptive alt text#center](image.png "Optional caption") +``` + +Rules: +- Do not use placeholder values such as `alt-txt`, `alt text`, or similar +- Do not wrap alt text in extra quotation marks inside `[]` +- Keep `#center` attached directly to the alt text with no extra space before it +- The caption is optional and should be short, descriptive, and natural +- Avoid outdated figure numbering such as `Figure 1:` unless the content genuinely depends on numbered cross-references + +Correct: + +```md +![Diagram showing the WebGPU rendering flow for drawing a triangle#center](images/webgpu-draw-high-level.svg "WebGPU rendering flow for drawing a triangle") +``` + +Incorrect: + +```md +!["Triangle using WebGPU" #center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU") +``` + +Incorrect: + +```md +![alt-txt#center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU") +``` + +## Alt text requirements for tutorials + +Learning Paths and install guides are instructional content. Images are usually not decorative. Alt text must help the learner understand what they would otherwise miss. + +For every image, alt text should explain: +- What is shown +- What the learner should notice +- Why it matters in the current step + +For screenshots: +- Name the screen, tool, or interface shown +- Mention the relevant UI element, tab, field, button, or output +- Explain what the learner should look for in the screenshot +- Connect the image to the current step or expected result + +For diagrams: +- Describe the components and relationships shown +- Explain the purpose of the diagram in the current task +- Focus on the workflow, architecture, or sequence the learner needs to understand + +For terminal or output images: +- State what command result or status is shown +- Highlight the important confirmation, value, or error message +- Explain why that output matters + +For hardware images: +- Describe the device or setup only if it helps the learner complete the task +- Avoid purely decorative descriptions + +## Alt text quality rules + +- Write meaningful alt text, not placeholders +- Keep it concise but complete. One to three sentences is usually enough +- Prefer instructional value over visual detail +- Include visible text only when the learner needs that text +- Do not use captions as a substitute for alt text +- Do not encode alignment instructions inside the caption + +## Caption guidance + +- Use short, descriptive captions when needed +- Captions should add context for all readers +- Avoid `Figure X` numbering unless explicit image cross-references are required + +Preferred example: + +```md +![Screenshot of the Arm Performance Studio timeline showing CPU activity spikes during Mandelbrot rendering. The Timeline tab is selected and the spike region is highlighted so the learner can identify where CPU activity increases during the run.#center](images/timeline-spike.png "Arm Performance Studio timeline showing CPU activity during Mandelbrot rendering") +``` + +## Image cleanup workflow + +- Replace all placeholder alt text such as `alt-txt` with meaningful descriptions +- Keep the repository-specific `#center` syntax when fixing alt text +- Do not remove valid alignment syntax during cleanup +- For bulk cleanup, update the guidance first, then fix content by category or directory in manageable batches diff --git a/.github/skills/audit-images/scripts/audit_images.py b/.github/skills/audit-images/scripts/audit_images.py new file mode 100755 index 0000000000..597788c000 --- /dev/null +++ b/.github/skills/audit-images/scripts/audit_images.py @@ -0,0 +1,361 @@ +#!/usr/bin/env python3 +"""Audit Markdown image alt text in Arm Learning Paths and install guides.""" + +from __future__ import annotations + +import argparse +import csv +import json +import re +from collections import Counter, defaultdict +from dataclasses import asdict, dataclass +from pathlib import Path +from typing import Iterable +from urllib.parse import unquote, urlparse + + +IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)\n]+)\)") +PLACEHOLDER_RE = re.compile(r"\b(alt[- ]?txt|alt[- ]?text|example image|placeholder)\b", re.IGNORECASE) +VAGUE_ALT_RE = re.compile( + r"^(img\d*|image\d*|screenshot\d*|screen shot|graph|chart|diagram|figure|photo|" + r"output\d*|aws\d*|gcloud\d*|pulumi|remote|connect|role|buildspec|artifacts)$", + re.IGNORECASE, +) +ALIGNMENT_RE = re.compile(r"#(center|left|right)\b") +URL_RE = re.compile(r"^[a-z][a-z0-9+.-]*://", re.IGNORECASE) + + +@dataclass +class Finding: + file: str + line: int + unit: str + image: str + alt: str + caption: str + issues: list[str] + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Audit Markdown image alt text in Arm Learning Paths and install guides." + ) + parser.add_argument( + "paths", + nargs="*", + default=["content/learning-paths", "content/install-guides"], + help="Markdown files or directories to scan.", + ) + parser.add_argument( + "--format", + choices=["markdown", "json", "csv"], + default="markdown", + help="Output format.", + ) + parser.add_argument("--output", help="Write output to this file.") + parser.add_argument( + "--include-ok", + action="store_true", + help="Include image references with no detected issues in detailed output.", + ) + parser.add_argument( + "--max-alt-words", + type=int, + default=45, + help="Flag alt text longer than this many words.", + ) + parser.add_argument( + "--repo-root", + default=".", + help="Repository root used for resolving local image paths.", + ) + return parser.parse_args() + + +def markdown_files(paths: Iterable[str], repo_root: Path) -> list[Path]: + files: list[Path] = [] + for raw_path in paths: + path = (repo_root / raw_path).resolve() + if path.is_file() and path.suffix == ".md": + files.append(path) + elif path.is_dir(): + files.extend(sorted(path.rglob("*.md"))) + return sorted(dict.fromkeys(files)) + + +def split_target(raw_target: str) -> tuple[str, str]: + target = raw_target.strip() + caption = "" + + title_match = re.search(r'\s+"([^"]*)"\s*$', target) + if title_match: + caption = title_match.group(1).strip() + target = target[: title_match.start()].strip() + + return target, caption + + +def line_number(text: str, offset: int) -> int: + return text.count("\n", 0, offset) + 1 + + +def normalize_alt(alt: str) -> str: + return ALIGNMENT_RE.sub("", alt).strip() + + +def word_count(text: str) -> int: + return len(re.findall(r"[A-Za-z0-9]+(?:[-'][A-Za-z0-9]+)?", text)) + + +def is_placeholder_or_vague(alt: str) -> bool: + normalized = re.sub(r"[^A-Za-z0-9 -]+", "", alt).strip() + normalized = re.sub(r"\s+", " ", normalized) + return bool(PLACEHOLDER_RE.search(alt) or VAGUE_ALT_RE.match(normalized)) + + +def is_url_or_anchor(target: str) -> bool: + return bool(URL_RE.match(target)) or target.startswith("#") + + +def strip_url_bits(target: str) -> str: + parsed = urlparse(target) + if parsed.scheme: + return target + return unquote(target.split("#", 1)[0].split("?", 1)[0]) + + +def resolve_local_image(target: str, md_file: Path, repo_root: Path) -> Path | None: + if is_url_or_anchor(target): + return None + + clean_target = strip_url_bits(target) + if not clean_target: + return None + + if clean_target.startswith("/"): + site_path = clean_target.lstrip("/") + if site_path.startswith(("learning-paths/", "install-guides/")): + return repo_root / "content" / site_path + return repo_root / site_path + + return md_file.parent / clean_target + + +def content_unit(md_file: Path, repo_root: Path) -> str: + rel = md_file.relative_to(repo_root).as_posix() + parts = rel.split("/") + + if parts[:2] == ["content", "learning-paths"] and len(parts) >= 4: + return "/".join(parts[:4]) + + if parts[:2] == ["content", "install-guides"]: + return rel + + return str(Path(rel).parent) + + +def detect_issues( + alt: str, + caption: str, + target: str, + md_file: Path, + repo_root: Path, + max_alt_words: int, +) -> list[str]: + issues: list[str] = [] + normalized = normalize_alt(alt) + normalized_words = word_count(normalized) + + if not alt.strip(): + issues.append("missing_alt") + + if alt.strip().startswith(('"', "'")) or alt.strip().endswith(('"', "'")): + issues.append("quoted_alt") + + if re.search(r"\s+#(center|left|right)\b", alt): + issues.append("alignment_not_attached") + + if "#center" not in alt: + issues.append("missing_center_alignment") + + if is_placeholder_or_vague(normalized): + issues.append("placeholder_or_vague_alt") + + if normalized and normalized_words < 4: + issues.append("too_short_alt") + + if normalized_words > max_alt_words: + issues.append("overlong_alt") + + if caption and re.match(r"Figure\s+\d+\s*:", caption, re.IGNORECASE): + issues.append("figure_number_caption") + + if caption and normalized_words <= 2 and word_count(caption) >= 4: + issues.append("caption_substitutes_for_alt") + + local_image = resolve_local_image(target, md_file, repo_root) + if local_image is not None and not local_image.exists(): + issues.append("missing_local_image") + + return issues + + +def audit_file(md_file: Path, repo_root: Path, max_alt_words: int) -> list[Finding]: + text = md_file.read_text(encoding="utf-8") + unit = content_unit(md_file, repo_root) + findings: list[Finding] = [] + + for match in IMAGE_RE.finditer(text): + raw_alt = match.group(1) + target, caption = split_target(match.group(2)) + issues = detect_issues(raw_alt, caption, target, md_file, repo_root, max_alt_words) + findings.append( + Finding( + file=md_file.relative_to(repo_root).as_posix(), + line=line_number(text, match.start()), + unit=unit, + image=target, + alt=raw_alt, + caption=caption, + issues=issues, + ) + ) + + duplicate_counts = Counter( + normalize_alt(item.alt).lower() + for item in findings + if normalize_alt(item.alt) and not is_placeholder_or_vague(normalize_alt(item.alt)) + ) + for item in findings: + normalized = normalize_alt(item.alt).lower() + if normalized and duplicate_counts[normalized] > 1: + item.issues.append("duplicate_alt_in_file") + + return findings + + +def summarize(findings: list[Finding], files_scanned: int) -> dict: + faulty = [item for item in findings if item.issues] + issue_counts = Counter(issue for item in faulty for issue in item.issues) + unit_counts: dict[str, Counter] = defaultdict(Counter) + + for item in findings: + unit_counts[item.unit]["total"] += 1 + if item.issues: + unit_counts[item.unit]["faulty"] += 1 + + units = [ + {"unit": unit, "total": counts["total"], "faulty": counts["faulty"]} + for unit, counts in sorted(unit_counts.items()) + ] + units.sort(key=lambda row: (-row["faulty"], row["unit"])) + + return { + "files_scanned": files_scanned, + "images_found": len(findings), + "faulty_images": len(faulty), + "issue_counts": dict(sorted(issue_counts.items())), + "units": units, + } + + +def markdown_output(findings: list[Finding], summary: dict, include_ok: bool) -> str: + rows = [item for item in findings if include_ok or item.issues] + lines = [ + "# Image audit", + "", + f"- Markdown files scanned: {summary['files_scanned']}", + f"- Images found: {summary['images_found']}", + f"- Faulty images: {summary['faulty_images']}", + "", + "## Issue counts", + "", + ] + + if summary["issue_counts"]: + for issue, count in summary["issue_counts"].items(): + lines.append(f"- `{issue}`: {count}") + else: + lines.append("- No issues detected") + + lines.extend(["", "## Content units", ""]) + lines.append("| Unit | Faulty | Total |") + lines.append("|---|---:|---:|") + for row in summary["units"]: + if row["faulty"] or include_ok: + lines.append(f"| `{row['unit']}` | {row['faulty']} | {row['total']} |") + + lines.extend(["", "## Findings", ""]) + if not rows: + lines.append("No findings to report.") + return "\n".join(lines) + "\n" + + lines.append("| File | Line | Image | Alt text | Caption | Issues |") + lines.append("|---|---:|---|---|---|---|") + for item in rows: + issues = ", ".join(f"`{issue}`" for issue in item.issues) or "OK" + lines.append( + "| " + f"`{item.file}` | {item.line} | `{item.image}` | " + f"{escape_table(item.alt)} | {escape_table(item.caption)} | {issues} |" + ) + + return "\n".join(lines) + "\n" + + +def escape_table(value: str) -> str: + escaped = value.replace("|", r"\|").replace("\n", " ") + return escaped if escaped else "" + + +def json_output(findings: list[Finding], summary: dict, include_ok: bool) -> str: + rows = [item for item in findings if include_ok or item.issues] + return json.dumps( + {"summary": summary, "findings": [asdict(item) for item in rows]}, + indent=2, + sort_keys=True, + ) + "\n" + + +def csv_output(findings: list[Finding], include_ok: bool) -> str: + from io import StringIO + + rows = [item for item in findings if include_ok or item.issues] + output = StringIO() + writer = csv.writer(output) + writer.writerow(["file", "line", "unit", "image", "alt", "caption", "issues"]) + for item in rows: + writer.writerow( + [item.file, item.line, item.unit, item.image, item.alt, item.caption, ";".join(item.issues)] + ) + return output.getvalue() + + +def main() -> int: + args = parse_args() + repo_root = Path(args.repo_root).resolve() + files = markdown_files(args.paths, repo_root) + findings: list[Finding] = [] + + for md_file in files: + findings.extend(audit_file(md_file, repo_root, args.max_alt_words)) + + summary = summarize(findings, len(files)) + + if args.format == "json": + output = json_output(findings, summary, args.include_ok) + elif args.format == "csv": + output = csv_output(findings, args.include_ok) + else: + output = markdown_output(findings, summary, args.include_ok) + + if args.output: + Path(args.output).write_text(output, encoding="utf-8") + else: + print(output, end="") + + return 1 if summary["faulty_images"] else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.github/skills/code-sample-review/SKILL.md b/.github/skills/code-sample-review/SKILL.md new file mode 100644 index 0000000000..5fd3eb2c65 --- /dev/null +++ b/.github/skills/code-sample-review/SKILL.md @@ -0,0 +1,64 @@ +--- +name: code-sample-review +description: Review and improve code samples, commands, command output, and fenced code blocks in Arm Learning Paths and install guides. Use when checking editorial formatting, technical accuracy, runnable commands, output lead-ins, code fence integrity, language tags, or token-heavy and unexplained code or output blocks. +--- + +# Code sample review + +Use this skill to review or edit code samples, commands, command output, and fenced code blocks in Arm Learning Paths and install guides. + +This skill can support either editorial review or technical review. Match the depth of review to the user's request and don't invent commands, outputs, workflows, package names, benchmark numbers, or validation results. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` to locate shared guidance. +- Read `references/code-sample-guidance.md` before reviewing or editing code samples. + +## Modes + +### Editorial mode + +Use when the user asks to review or fix code sample presentation, readability, formatting, or consistency. + +Check for: + +- Explanatory prose before each code block +- Correct and consistent language tags +- Standard output lead-ins +- Closed code fences +- Oversized, duplicated, or unexplained output blocks +- Consistent terminology around commands, files, UI labels, and outputs + +### Technical mode + +Use when the user asks whether commands, examples, or outputs are accurate, runnable, safe, or technically complete. + +Check for: + +- Commands that match the stated operating system, shell, tool, and Arm platform +- Plausible package names, file paths, flags, versions, and environment variables +- Output blocks that correspond to the preceding command +- Validation steps that prove the intended outcome +- Learning Path code that supports the stated task +- Install guide commands that stay within install and verification scope + +## Workflow + +1. Identify the review scope and whether the request is editorial, technical, or mixed. +2. Inspect surrounding prose before judging a code block; code samples should be evaluated in context. +3. Depending on the type of review, suggest fixes as follows: + - For review requests, report issues by file and line when possible, ordered by learner impact. + - For edit requests, report issues and suggest focused changes that preserve technical intent and existing repository patterns. +4. After the reviewer accepts suggestions, make changes, then re-scan edited areas for code fence integrity, language tags, and output lead-ins. +5. Report what changed and note any technical assumptions or checks not performed. + +## Validation rules + +- Preserve front matter, Hugo shortcodes, Markdown structure, command syntax, and expected output unless they are the target of the edit. +- Don't rewrite meaningful code solely for style. +- Don't replace tool-native terms, casing, flags, package names, or architecture strings with prose preferences. +- Don't treat long code or output as a problem by itself; flag it only when it reduces learning value or obscures the task. +- Keep edits scoped to code sample quality unless the user asks for broader content review. +- Don't modify commands or output unless the reviewer accepts the suggestions. +- Don't hallucinate corrections that aren't supported by context, documentation, or an executable check. diff --git a/.github/skills/code-sample-review/references/code-sample-guidance.md b/.github/skills/code-sample-review/references/code-sample-guidance.md new file mode 100644 index 0000000000..d5b4d48319 --- /dev/null +++ b/.github/skills/code-sample-review/references/code-sample-guidance.md @@ -0,0 +1,45 @@ +# Code sample guidance + +## Code samples and formatting + +- Always provide explanation before code blocks. +- Use this flow when practical: `[What it does] -> [Code] -> [Expected outcome] -> [Key parameters]`. +- Use Markdown language tags such as `bash`, `python`, `yaml`, `json`, or `output`. +- Use `console` or `bash` for general commands. Try to use the same one throughout a Learning Path or install guide. +- Use the `output` tag to show expected command output. +- Use shortcodes for common pitfalls, warnings, and important notes. + +## Output descriptions + +- Use `The output is similar to:` or `The expected output is:` before output blocks. +- Use present tense descriptions such as `builds` and `gives`. +- Make sure output examples correspond to the command immediately before them. +- Avoid oversized terminal output unless the full output has instructional value. + +## Readability and flow + +- Warn if more than 300 words appear between code examples in task-led sections. +- Use visual breaks to prevent walls of text. Code blocks count as visual breaks. +- If a section is long because of code or output rather than explanation, do not treat length alone as a readability problem. +- Flag token-heavy content only when it adds cost without improving learning value, such as oversized terminal output, repeated setup, duplicated examples, unexplained code blocks, or repeated boilerplate. + +## Formatting standards + +- Use **bold** for UI elements. +- Use *italics* for emphasis and new terms. +- Use `code formatting` for file names, commands, code elements, package names, flags, paths, and environment variables. +- In code blocks, CLI flags, package names, file paths, outputs, and tool messages, keep the exact casing used by the tool. + +## Code fence integrity + +- Every fenced code block opened with triple backticks must be explicitly closed with matching triple backticks before non-code content resumes. +- Never generate unterminated or partial code fences. +- Do not rely on implicit closure, indentation, or surrounding formatting to end a code block. + +## Technical review + +- Verify commands match the stated operating system, shell, tool version, and Arm platform. +- Check that install commands use a specific version when required by install guide guidance. +- Check that validation commands prove the intended outcome. +- Do not invent commands, outputs, benchmark numbers, or tool behavior. +- If a command or output cannot be verified, state the limitation instead of guessing. diff --git a/.github/skills/frontmatter-audit/SKILL.md b/.github/skills/frontmatter-audit/SKILL.md new file mode 100644 index 0000000000..ec0be2d0ec --- /dev/null +++ b/.github/skills/frontmatter-audit/SKILL.md @@ -0,0 +1,70 @@ +--- +name: frontmatter-audit +description: Audit YAML front matter and metadata for Arm Learning Paths and install guides. Use when checking required fields, fixed layout fields, duplicate weights, draft visibility metadata, closed-list metadata values, description presence or quality, YAML validity, and front matter consistency. +--- + +# Front matter audit + +Use this skill to audit front matter and metadata without rewriting body content. It can report issues or make metadata-only edits when requested. + +## Workflow + +1. Identify whether the target is a Learning Path, single-page install guide, multi-page install guide, or mixed content directory. +2. Read the front matter and enough body context to understand the page task, platform, and outcome. +3. Check YAML validity and preserve front matter order when editing. +4. Check required and fixed fields for the content type. +5. Check metadata consistency across files in a content unit, including duplicate or missing `weight` values. +6. Check whether `description` is present and fit for purpose. If it is missing or weak, either report it or use `.github/skills/metadata-description-update/SKILL.md` when the user asked for edits. +7. After completing all checks, report findings by severity with file and line references when available. + +## Learning Path checks + +For a Learning Path directory: + +- `_index.md` should use `weight: 1`. +- Public pages should have unique `weight` values within the directory. +- Every page except for `_next-steps.md` must include a description. +- `_index.md` must include `description`. +- Required `_index.md` fields include `title`, `description`, `weight`, `layout`, `minutes_to_complete`, `prerequisites`, `author`, `generate_summary_faq`, `rerun_summary`, `rerun_faqs`, `subjects`, `armips`, `tools_software_languages`, `skilllevels`, and `operatingsystems`. +- `layout` is usually `learningpathall`. +- `title` should be task-led and use an imperative structure: verb + technology/tool + outcome. +- `skilllevels` values are only `Introductory` or `Advanced`. +- `subjects` and `operatingsystems` must match the closed lists in `content/learning-paths/cross-platform/_example-learning-path/write-2-metadata/`. +- `armips` should use Arm IP families such as Neoverse, Cortex-A, or Cortex-M, not specific CPU models or Arm architecture versions. +- `author` can list multiple authors with YAML list syntax. +- `generate_summary_faq`, `rerun_summary`, and `rerun_faqs` values are only `true` and `false`. +- Skip `_next-steps.md` for description updates unless the user explicitly asks how to handle it. + +## Install guide checks + +For an install guide: + +- Required fields include `title`, `minutes_to_complete`, `official_docs`, `author`, `weight`, and `layout`. +- Fixed fields should usually be `weight: 1`, `tool_install: true`, and `layout: installtoolsall`. +- Set `tool_install: false` only when the guide is intentionally hidden. +- Set `multi_install` and `multitool_install_part` based on whether the guide is multi-page. +- If `multi_install` is true, the first page should act as the series overview. +- Sub-pages in a multi-page guide should set `multitool_install_part: true`. +- Install guide descriptions should describe the tool, supported Arm platform or operating system context, and what the setup enables. + +## Description quality checks + +- The description should be one sentence. +- It should state what the reader will do, the main tool or platform, and the useful outcome. +- It should be concise, developer-focused, and suitable as a search snippet. +- It should not repeat the title verbatim. +- It should not use vague summaries, hype, keyword stuffing, unsupported claims, or invented capabilities. +- Quote the value only when needed for YAML syntax. + +## Validation rules + +- Preserve body content, Hugo shortcodes, links, commands, code blocks, and expected output unless the user explicitly asks for broader edits. +- Do not invent metadata values. Use nearby content, repository examples, or the closed-list metadata reference. +- If a closed-list value cannot be verified, state the limitation instead of guessing. +- For broad audits, report before editing unless the user explicitly requested changes. + +## Response format + +For audits, lead with metadata findings ordered by severity and include file and line references. Then add skipped files, assumptions, and a short summary. + +For edits, summarize changed fields and note any metadata checks performed. diff --git a/.github/skills/install-guide-structure-review/SKILL.md b/.github/skills/install-guide-structure-review/SKILL.md new file mode 100644 index 0000000000..722b0a1dd6 --- /dev/null +++ b/.github/skills/install-guide-structure-review/SKILL.md @@ -0,0 +1,54 @@ +--- +name: install-guide-structure-review +description: Review Arm install guides for structural soundness, installation-only scope, verification quality, OS-specific sections, troubleshooting, multi-page guide behavior, and version-note placement. Use when asked to review, create, reorganize, or assess content under content/install-guides. +--- + +# Install guide structure review + +Use this skill when an install guide needs a structural review. Focus on whether the guide installs and verifies one tool on Arm platforms without drifting into applied workflows. + +## Workflow + +1. Identify whether the target is a single-page guide, multi-page guide, or install guide directory. +2. State the installation target and supported Arm platform context in one sentence. +3. Check the required guide shape: + - Overview: explains what the tool is and which Arm platforms are supported, such as `aarch64`, Windows on Arm, or macOS on Arm. + - Install steps: grouped logically, with clear OS-specific sections when necessary. + - Verification: includes at least one or two commands and expected output. + - Troubleshooting: covers common failure cases and fixes when appropriate. + - Optional uninstall steps stay secondary. +4. Check version handling: + - Download and install examples use a specific version when practical. + - A note before versioned commands tells readers they can use other versions. + - The note links to a release or download page where readers can find the latest version. +5. Check scope boundaries: + - No end-to-end workflows. + - No performance benchmarking. + - No deep architectural explanation. + - No comparative marketing claims. + - No duplicated Learning Path workflow content. +6. For multi-page guides, check that the first page acts as the overview and sub-pages behave as install parts. +7. Report findings by learner impact, with file and line references when available. Do not comment on content that is already structurally sound. + +## Version note pattern + +Use this pattern before commands that pin a downloadable tool version: + +```md +{{% notice Note %}} +The following commands use version . The same commands work with other versions. Replace the file used in these steps with the file for your version of choice. To find the latest version, see [Link to page with release info](URL). +{{% /notice %}} +``` + +## Validation rules + +- Preserve front matter, Hugo shortcodes, code fences, command syntax, expected output, links, and the author's technical intent when editing. +- Use `.github/skills/frontmatter-audit/SKILL.md` for required front matter, fixed fields, and metadata validity. +- Use `.github/skills/code-sample-review/SKILL.md` when commands, outputs, language tags, or technical accuracy need a deeper pass. +- Verify internal links before changing them, or state when verification was not possible. + +## Response format + +For reviews, lead with findings ordered by severity and include file and line references. Then add open questions or assumptions, followed by a short summary. + +For edits, summarize the structural changes and note any checks performed. diff --git a/.github/skills/intake-metadata-update/SKILL.md b/.github/skills/intake-metadata-update/SKILL.md new file mode 100644 index 0000000000..6067ea40d8 --- /dev/null +++ b/.github/skills/intake-metadata-update/SKILL.md @@ -0,0 +1,35 @@ +--- +name: intake-metadata-update +description: Add or verify draft metadata for new Arm Learning Paths and install guides before or after merge to main, so unreviewed content does not publish publicly. Use when asked to mark new content as draft, prepare new content for review, hide new Learning Paths or install guides from publication, or check draft metadata. +--- + +# Update metadata during content intake + +Use this skill when new Learning Path or install guide content needs to remain unpublished until technical and editorial review is complete. + +Work from the repository root and preserve existing front matter values and order where possible. Don't edit anything else in the file. + +## Workflow + +1. Identify the target content: + - Learning Path directory: edit its `_index.md`. + - Single-file install guide: edit metadata in that Markdown file. + - Multi-page install guide or content bundle: edit the `_index.md` or main entry file. +2. Add or update this metadata: + - For Learning Paths: + + ```yaml + draft: true + cascade: + draft: true + ``` + + - For single-page install guides: + + ```yaml + draft: true + ``` + +## Response format + +List the file(s) that were updated. \ No newline at end of file diff --git a/.github/skills/learning-path-structure-review/SKILL.md b/.github/skills/learning-path-structure-review/SKILL.md new file mode 100644 index 0000000000..08b3aa94e4 --- /dev/null +++ b/.github/skills/learning-path-structure-review/SKILL.md @@ -0,0 +1,65 @@ +--- +name: learning-path-structure-review +description: Review Arm Learning Paths for structural soundness, task ownership, scope discipline, progression, validation, further reading placement, recap sections, and performance-learning integrity. Use when asked to review, create, reorganize, or assess the structure of content under content/learning-paths. +--- + +# Learning Path structure review + +Use this skill when a Learning Path needs a structural review. Focus on whether the content is organized to help a developer complete one clear task from preparation through validation. + +## Workflow + +1. Identify the Learning Path directory and read the relevant Markdown files together. +2. State the owned developer task in one sentence. If the task is unclear, too broad, or split across unrelated goals, flag it. +3. Check the required file shape: + - The Learning Path has an `_index.md` file. + - The Learning Path has an `_next-steps.md` file. + - Additional resources and next steps live in `_index.md` `further_reading`, not in `_next-steps.md`. + - `_next-steps.md` remains minimal and respects `FIXED, DO NOT MODIFY` template comments. +4. Review the instructional shape: + - The title and opening frame one developer task. + - The introduction gives context, user goal, and practical value. + - Prerequisites are explicit and linked when useful. + - Learning objectives are measurable, action-oriented, and limited to three or four bullets. + - Sections progress logically through prepare, configure, use, and validate phases. + - Validation steps prove the learner reached the promised outcome. + - The conclusion or next-step guidance names what the learner can do next. +5. Review `further_reading`: + - Keep four to six essential resources. + - Prefer direct relevance, Arm Learning Paths, required tools, foundation knowledge, and logical next steps. + - Avoid link piles that pull readers away from the task. +6. Review recap and transition sections: + - Include concise recap and forward-looking transition at major instructional boundaries. Do not treat a transition sentence alone as a recap. Note the absence of a transition as a finding. + - Use `what you've learned` for conceptual sections and `what you've accomplished` for task sections. + - Avoid repeating earlier content verbatim. +7. If the Learning Path demonstrates Arm-specific performance features, apply the performance integrity checks. +8. Report findings by learner impact, with file and line references when available. Do not comment on content that is already structurally sound. + +## Scope rules + +- Learning Paths are not blog posts, reference articles, or install guides. +- A Learning Path should own one concrete developer task. +- Link to install guides for setup instead of duplicating install guide content. +- Preserve Hugo shortcodes, code fences, commands, links, front matter, and the author's technical intent when editing. +- Use repository search when structure, terminology, links, or task flow depends on related files. + +## Performance integrity checks + +For Learning Paths that demonstrate Arm-specific performance features, such as SME2, SVE2, I8MM, DotProd, or optimized microkernels: + +- State the measurable improvement the learner will observe before deep architectural explanation. +- Show performance results before internal call stacks or microkernel details. +- Include toolchain or software version, device or platform, thread count, CPU affinity, runtime feature flags, and workload configuration when performance numbers are included. +- Label illustrative numbers clearly. +- Distinguish compile-time feature enablement, runtime feature activation, and automatic fallback behavior. +- Include a way to verify the accelerated path executed, such as logs, profiling output, kernel names, or hardware counters. +- Change only one meaningful benchmark variable at a time. +- Control thread count and CPU binding intentionally. +- Quantify percentage improvement explicitly. +- Connect observed improvement to the Arm architectural feature responsible for it. + +## Response format + +For reviews, lead with findings ordered by severity and include file and line references. Then add open questions or assumptions, followed by a short summary. + +For edits, summarize the structural changes and note any checks performed. diff --git a/.github/skills/link-text-review/SKILL.md b/.github/skills/link-text-review/SKILL.md new file mode 100644 index 0000000000..4ad35b179c --- /dev/null +++ b/.github/skills/link-text-review/SKILL.md @@ -0,0 +1,62 @@ +--- +name: link-text-review +description: Review and improve accessible Markdown link text in Arm Learning Paths and install guides. Use when asked to find vague links, fix link text such as here or click here, verify internal links, improve screen-reader clarity, or make links descriptive and task-focused. +--- + +# Link text review + +Use this skill to review or improve Markdown link text so links are descriptive, accessible, and useful out of context. + +This skill focuses on anchor text and link clarity. For tables, notices, tab panes, and other structural Markdown components, use `.github/skills/markdown-component-edit/SKILL.md`. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` only if you need repository routing context. +- Read `.github/skills/writing-style-review/SKILL.md` only when changing prose around links. +- For Learning Paths, read `.github/skills/learning-path-structure-review/SKILL.md` when link placement or `further_reading` is involved. + +## Workflow + +1. Identify the target file, directory, section, or selected text. +2. Read surrounding context before suggesting any changes. +3. After understanding the context of the URL, suggest concise and natural rewrites to the anchor text based on `Quality rules`. +4. After the user accepts suggestions, make changes, then re-open or search changed lines to verify the Markdown link syntax is valid. +5. After you make changes, report changed links and any links not verified. + +## Quality rules + +- Link text should make sense without nearby words when possible. +- Prefer destination-specific anchors such as `Docker install guide`, `Arm Developer resources`, or `Google Cloud firewall rules`. +- Avoid anchors that only describe the mechanic, such as `here`, `click here`, `this page`, `read more`, `link`, or `website`, as well as bare URLs or repeated generic text. +- Avoid overlong anchors that wrap a whole sentence. +- Don't change product names, tool names, URLs, or technical meaning to satisfy prose preferences. +- Don't add speculative links. Verify internal targets or state when verification was not possible. Preserve the URL unless it's broken or the user asks for a change. + +## Examples + +Use these examples for both link format and link text guidance. + +Poor: + +```md +See [here](/install-guides/docker/) for setup. +``` + +Better: + +```md +For setup instructions, see the [Docker install guide](/install-guides/docker/). +``` + +Poor: + +```md +A list of all AWS instance types can be [viewed here](https://aws.amazon.com/ec2/instance-types/). +``` + +Better: + +```md +For a complete list, see [Amazon EC2 instance types](https://aws.amazon.com/ec2/instance-types/). +``` diff --git a/.github/skills/markdown-component-edit/SKILL.md b/.github/skills/markdown-component-edit/SKILL.md new file mode 100644 index 0000000000..5ee44ce6c7 --- /dev/null +++ b/.github/skills/markdown-component-edit/SKILL.md @@ -0,0 +1,38 @@ +--- +name: markdown-component-edit +description: Add or update structured Markdown and Hugo components in Arm Learning Paths and install guides. Use when asked to turn selected text into a link, table, notice, tab pane, code pane, shortcode block, or other repo-specific Markdown component while preserving surrounding content. +--- + +# Markdown component edit + +Use this skill to make focused structural edits to Markdown and Hugo components in Arm Learning Paths and install guides. + +This skill is best when the user highlights text, names a section, or asks for a specific component. It shouldn't decide that content needs a component during broad editorial review unless the user asks. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` to locate shared guidance. +- Read `references/component-patterns.md` before adding or changing notices, tables, tabs, or other structured components. +- Use `.github/skills/code-sample-review/SKILL.md` for code panes, command examples, command output, language tags, or code fence integrity. + +## Workflow + +1. Use the user's highlighted, selected, or explicitly named text as the edit target. If the target is ambiguous, ask for the exact text, file, or section before editing. +2. Inspect nearby Markdown so the new component fits the surrounding flow. +3. Verify internal links before adding or changing them when practical. +4. Use `component rules` and the `component-patterns` reference and do one of the following: + - If the target isn't a good fit for the provided component, push back with justification. Rely on component rules. + - If it's a good fit, or if the reviewer voluntarily requests an unusual update, make the update. +4. After making an update, re-open or search the edited area to verify shortcode pairs, table rows, links, and code fences are well formed. +5. Report the component added or changed and note any links or syntax that could not be verified. + +## Component rules + +- Notices are for notes, warnings, tips, troubleshooting, platform-specific context, or important constraints. +- Tables are for comparison, lookup, short structured reference, or option summaries. Avoid tables for sequential instructions. +- Tab panes are for mutually exclusive alternatives such as operating systems, shells, package managers, or platform-specific code. +- Links should use descriptive anchor text. Use the link text review skill for broader cleanup. +- Don't convert content into a component if a plain paragraph or list is clearer. Keep the component small and purposeful +- Preserve front matter, shortcodes, code fences, commands, expected output, and existing file structure. +- Use local examples before adding unfamiliar Hugo shortcode syntax. diff --git a/.github/skills/markdown-component-edit/references/component-patterns.md b/.github/skills/markdown-component-edit/references/component-patterns.md new file mode 100644 index 0000000000..653089fe18 --- /dev/null +++ b/.github/skills/markdown-component-edit/references/component-patterns.md @@ -0,0 +1,89 @@ +# Structured component patterns + +Use these patterns when adding or editing structured Markdown and Hugo components. + +## Notices + +Use notice shortcodes for information that needs visual emphasis. + +```md +{{% notice Note %}} +The following commands use version 1.2.3. The same commands work with other versions. +{{% /notice %}} +``` + +Common labels include `Note`, `Tip`, `Warning`, `Important`, `Troubleshooting`, and short contextual labels such as `Network security`. + +Rules: + +- Keep opening and closing shortcodes on separate lines for multi-sentence content. +- Keep the label concise and descriptive. +- Don't use notices for ordinary transitions or filler. +- Don't nest notices inside lists unless the surrounding file already uses that pattern and indentation is correct. +- Preserve shortcode spacing: `{{% notice Note %}}` and `{{% /notice %}}`. + +## Tables + +Use Markdown tables for compact comparisons and lookup information. + +```md +| Tool | Purpose | Verification command | +|------|---------|----------------------| +| `skopeo` | Inspect and copy container images | `skopeo --help` | +| `perf` | Collect Linux performance data | `perf --help` | +``` + +Rules: + +- Use a header row and separator row. +- Keep headers short and descriptive. +- Keep each row parallel. +- Use code formatting for commands, file names, flags, package names, and variables. +- Avoid long prose in cells. If a cell needs multiple sentences, use a paragraph or list instead. +- Avoid tables for ordered procedures. + +## Code tab panes + +Use `tabpane code=true` for platform-specific commands or code alternatives. + +```md +{{< tabpane code=true >}} + {{< tab header="Ubuntu" language="bash">}} +sudo apt update +sudo apt install -y example + {{< /tab >}} + {{< tab header="macOS" language="bash">}} +brew install example + {{< /tab >}} +{{< /tabpane >}} +``` + +Rules: + +- Use clear tab labels such as `Ubuntu`, `Fedora`, `macOS`, or `Windows PowerShell`. +- Use `language` when the surrounding examples use it. +- Keep alternatives parallel. +- Use the code sample review skill for command accuracy, output, code panes, and code fence integrity. + +## Non-code tab panes + +Use `tabpane-normal` or `tabpane code=false` for non-code alternatives. + +```md +{{< tabpane-normal >}} + {{< tab header="Podman" >}} +Use Podman when you need a daemonless container runtime. + {{< /tab >}} + {{< tab header="Finch" >}} +Use Finch when you need a lightweight container runtime on macOS. + {{< /tab >}} +{{< /tabpane-normal >}} +``` + +Rules: + +- Use non-code tabs only when the alternatives are mutually exclusive. +- Keep each tab roughly comparable in length and detail. +- Avoid hiding critical sequential instructions inside tabs unless the user chooses one path. + + diff --git a/.github/skills/metadata-description-update/SKILL.md b/.github/skills/metadata-description-update/SKILL.md new file mode 100644 index 0000000000..35b21c5a02 --- /dev/null +++ b/.github/skills/metadata-description-update/SKILL.md @@ -0,0 +1,69 @@ +--- +name: metadata-description-update +description: Add or improve SEO-friendly front matter description fields for Arm Learning Paths and install guides. Use when asked to add missing descriptions, update weak metadata descriptions, optimize search snippets, or ensure Learning Path pages and install guides have accurate description metadata. +--- + +# Metadata description update + +Use this skill to add or improve `description` fields in front matter for Arm Learning Paths and install guides. + +This skill is for search and discovery metadata. For draft visibility metadata, use `.github/skills/intake-metadata-update/SKILL.md`. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` only if you need to locate shared guidance. +- For Learning Paths, read `.github/skills/learning-path-structure-review/SKILL.md` only if the page task or outcome is unclear. +- For install guides, read `.github/skills/install-guide-structure-review/SKILL.md` only if the tool, platform, or verification outcome is unclear. +- Use `.github/skills/frontmatter-audit/SKILL.md` only when the request is broader than description edits. + +## Scope rules + +- Learning Path directory: update `_index.md` and each public content page in the directory. Skip `_next-steps.md`. +- Learning Path `_index.md`: describe the full Learning Path task, main tool or platform, and outcome. +- Learning Path content page: describe that page's specific action, context in the task flow, and outcome. +- Install guide file: describe the tool being installed, supported Arm platform or operating system context, and what the tool enables. +- Multi-page install guide directory: update the main entry page and public sub-pages that need descriptions. +- Preserve existing front matter order when practical. If adding a missing description, place it near `title`. +- Preserve body content, shortcodes, links, commands, code blocks, and expected output. Don't edit anything that isn't metadata. +- Skip `_next-steps.md` and any file without front matter unless the user explicitly asks how to handle it. + +## Workflow + +1. Identify whether the target is an install guide content page, a Learning Path `_index.md`, or a Learning Path content page. +2. Read the title, existing description, headings, introduction, task flow, code or command context, and validation or conclusion. +3. Add or revise the `description` field in front matter based on quality rules. +4. After editing, re-open or search the files to verify each changed target has one `description` field. +5. Report files changed and note any skipped files. + +## Description quality rules + +- Write one sentence. +- Keep it concise, developer-focused, and suitable for a search snippet. +- Use natural Arm-specific terms when relevant. +- State what the reader will do, the main tool or platform, and the useful outcome. +- Don't repeat the title verbatim. +- Don't use vague summaries such as `Learn about...` unless the page is genuinely conceptual. +- Don't use marketing language, hype, or keyword stuffing. +- Don't invent capabilities, performance claims, supported platforms, or tools not supported by the page. +- Use valid YAML. Quote the description only when needed for YAML syntax. + +## Examples + +Learning Path `_index.md`: + +```yaml +description: Learn how to deploy a retrieval-augmented generation application on Google Axion with LlamaIndex, Ollama, and a browser-based chat interface. +``` + +Learning Path content page: + +```yaml +description: Configure firewall rules for a Google Axion instance so the browser-based RAG application can accept HTTP traffic. +``` + +Install guide: + +```yaml +description: Install the AWS Cloud Development Kit on Arm Linux and verify the setup so you can define and deploy cloud infrastructure with reusable code. +``` diff --git a/.github/skills/seo-geo-aeo-review/SKILL.md b/.github/skills/seo-geo-aeo-review/SKILL.md new file mode 100644 index 0000000000..32bc9ec909 --- /dev/null +++ b/.github/skills/seo-geo-aeo-review/SKILL.md @@ -0,0 +1,61 @@ +--- +name: seo-geo-aeo-review +description: Review and improve Arm Learning Paths and install guides for SEO, GEO, AEO, search snippets, AI-agent selection, and answer-engine readiness. Use when asked to optimize discoverability, search intent, AI-readable structure, page titles, headings, summaries, or content selection signals beyond only front matter descriptions. +--- + +# SEO, GEO, and AEO review + +Use this skill when Arm Learning Paths or install guides need a focused discoverability review that goes beyond editing a single `description` field. + +This skill covers: + +- SEO: search snippets, titles, headings, metadata, and natural keyword usage. +- GEO: generative-engine selection signals, including authority, task coverage, and citation-ready structure. +- AEO: direct answer readiness for developer questions and AI-generated summaries. + +For focused front matter `description` edits only, use `.github/skills/metadata-description-update/SKILL.md`. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` only if you need repository routing context. +- Review `.github/skills/seo-geo-aeo-review/references/learning-paths-discoverability.md` only if you're reviewing a Learning Path. + +## Workflow + +1. Identify the target content type and target developer intent. +2. Read the title, front matter description, headings, introduction, prerequisites, main task flow, validation, conclusion, and further reading. +3. State the page's owned task in one sentence. If the task is unclear or too broad, flag it. +4. Review SEO signals: + - The title is task-led and includes the main technology, platform, or tool. + - The `description` is one concise sentence that states the task, context, and outcome. + - Headings expose the workflow and use natural developer search terms. + - Keywords are specific and natural, not repeated for ranking. +5. Review GEO signals: + - The page has clear Arm-specific authority and avoids generic advice that could apply anywhere. + - Prerequisites, assumptions, and target platform are explicit. + - Steps progress from preparation to configuration, usage, and validation. + - The page avoids contradictions, duplicated instructions, and unsupported claims. +6. Review AEO signals: + - The opening content answers what the reader will do and why it matters. + - Sections are scannable and can be safely summarized out of context. + - Validation steps prove the learner reached the promised outcome. + - Troubleshooting, next steps, or further reading answer likely follow-up questions. +7. Provide suggestions based on findings in the format specified under `Response format`. +8. Make focused edits only when a reviewer requests you to implement changes that you suggested. When making edits, preserve technical meaning, front matter structure, Hugo shortcodes, links, commands, and code blocks. +9. After making updates, re-open changed sections and verify front matter, Markdown syntax, and internal links when practical. + +## Review rules + +- Optimize for selection and usefulness, not ranking alone. +- For Learning Paths, prefer verb-led titles such as `Install`, `Deploy`, `Configure`, `Analyze`, `Optimize`, or `Verify`. Install guides are named after the tool being installed and don't feature a verb because install is implied. +- Preserve content-type boundaries: install guides cover installation and verification; Learning Paths cover applied end-to-end tasks. +- Use Arm-specific terminology naturally when it is supported by the content. +- Don't add speculative keywords, unsupported performance claims, or marketing language. +- Don't overfit content to AI agents at the expense of human readability. + +## Response format + +For reviews, lead with findings ordered by severity and include file and line references when available. Then add open questions or assumptions, followed by a short summary. + +For edits, summarize the changed SEO/GEO/AEO signals and note any checks performed. diff --git a/.github/skills/seo-geo-aeo-review/references/learning-paths-discoverability.md b/.github/skills/seo-geo-aeo-review/references/learning-paths-discoverability.md new file mode 100644 index 0000000000..5b09b83866 --- /dev/null +++ b/.github/skills/seo-geo-aeo-review/references/learning-paths-discoverability.md @@ -0,0 +1,40 @@ +## Learning Paths purpose and agentic selection + +Learning Paths are not blog posts or reference articles. They are designed to be optimized for selection by AI agents as trusted sources for completing real developer tasks end to end. + +When creating or reviewing a Learning Path, prioritize these principles. + +### Task ownership + +Each Learning Path must clearly own one concrete developer task. + +- The task should be nameable in one sentence. +- The Learning Path should take the learner from not ready to capable. +- Avoid bundling unrelated tasks or loosely connected topics. + +If the task cannot be clearly stated, flag a warning. + +### Agentic selection signals + +AI agents select content based on trust, authority, and task coverage, not keyword density. + +Trust: + +- Clear authorship and ownership. +- Explicit prerequisites. +- One purpose per page. +- No duplicated or contradictory instructions. +- Clean separation of install guides, Learning Paths, and concept pages. + +Authority: + +- Arm-specific framing where relevant. +- Use Arm tooling, terminology, and perspective. +- Avoid generic advice that could apply equally to any platform. + +Task coverage: + +- Clear progression: prepare, configure, use, validate. +- Explicit end state, such as `you are now ready to...`. +- Link to install guides instead of embedding install steps. +- Provide guidance on what to do next. \ No newline at end of file diff --git a/.github/skills/stale-content-review/SKILL.md b/.github/skills/stale-content-review/SKILL.md new file mode 100644 index 0000000000..e358cffc37 --- /dev/null +++ b/.github/skills/stale-content-review/SKILL.md @@ -0,0 +1,82 @@ +--- +name: stale-content-review +description: Scan Arm Learning Paths and install guides for stale-content risk. Use when the user asks to periodically flag content that may need maintenance, freshness review, dependency drift review, screenshot or UI review, latest or unpinned version review, or a report of likely stale pages. +--- + +# Stale content review + +Use this skill to find Learning Paths and install guides that might need human maintenance review. This skill is report-only by default: flag risk, provide evidence, and leave fixes to the relevant owner unless the user explicitly asks for edits. + +## Prerequisites + +- Work from the repository root. +- Read `AGENTS.md` if routing or related skill selection is unclear. +- Read `references/staleness-signals.md` before interpreting scan results. + +## Workflow + +1. Identify the review scope. For periodic scans, default to `content/learning-paths` and `content/install-guides`. +2. Run `scripts/stale_content_scan.py` for a deterministic first pass. +3. Review the highest-scoring files and sample lines before drawing conclusions. +4. Summarize what each selected guide or page does, the dependencies or moving parts it relies on, and the review flags a human should consider. + +## Validation rules + +- Treat scan output as a triage queue, not proof that content is wrong. +- Do not invent replacement commands, versions, links, or product guidance. +- Do not open issues, move project cards, or edit content unless the user asks. +- Flag mutable dependencies, screenshots, UI flows, external services, unpinned versions, old dates, and version-specific instructions as review candidates. +- Be explicit when a flag is uncertain or only a heuristic signal. +- Keep periodic scan output lightweight enough for a reviewer to act on. +- Prefer questions and maintenance prompts over direct edits. +- Propose using related skills for focused follow-up: + - `audit-images` for screenshot, image, alt text, and caption review. + - `code-sample-review` for commands, package installs, outputs, and code fence integrity. + - `writing-style-review` for Arm terminology, product naming, and prose quality. + - `learning-path-structure-review` or `install-guide-structure-review` for broader content judgment. + - `link-text-review` for stale or vague external links that also need accessible anchor text. + +## Script usage + +Run the default content scan: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py +``` + +The default broad scan reports files with score 20 or higher. Use `--min-score` to widen or narrow the queue. + +Scan one Learning Path or install guide: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py content/install-guides/acfl.md +``` + +Write a Markdown report: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py --output stale-content-risk-report.md +``` + +Write JSON for later processing: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py --format json --output stale-content-risk-report.json +``` + +Include draft content when preparing unpublished material for review: + +```bash +python3 .github/skills/stale-content-review/scripts/stale_content_scan.py --include-drafts +``` + +## Periodic workflow + +`.github/workflows/stale-content-scan.yml` runs the broad scan every Monday at 10:00 UTC. It writes the first part of the report to the workflow summary and uploads the full Markdown report as `stale-content-risk-report`. + +## Error handling + +- If the scan returns too many candidates, increase `--min-score` or scan a narrower path. +- If a broad periodic scan returns too few candidates, lower `--min-score` to 15 or 12. +- If a file scores highly because of generated output or intentional version pinning, mark it as a lower-priority false positive in the review summary. +- If the workflow artifact is empty or unexpectedly small, rerun the script locally with the same path and threshold. diff --git a/.github/skills/stale-content-review/references/staleness-signals.md b/.github/skills/stale-content-review/references/staleness-signals.md new file mode 100644 index 0000000000..0682f28955 --- /dev/null +++ b/.github/skills/stale-content-review/references/staleness-signals.md @@ -0,0 +1,98 @@ +# Staleness signals + +Use this reference to interpret stale-content scan results for Arm Learning Paths and install guides. + +## Review posture + +- Be conservative and transparent. +- Prefer flagging over fixing. +- Treat the report as a conversation starter for the content owner. +- Do not invent new commands, tools, workflows, benchmark numbers, product names, or version guidance. +- Suggest minimal follow-up only when the risk is clear. + +## Useful review summary + +For each high-priority guide or page, provide: + +- A short summary of what the content helps the learner do. +- The platforms, environments, tools, SDKs, frameworks, services, models, repositories, and commands it depends on. +- A short list of flags or questions for a human reviewer. + +## Signals to flag + +### Temporal language + +Flag wording that may become stale, including: + +- `currently` +- `latest` +- `recently` +- `newly` +- `preview` +- `beta` +- `at the time of writing` +- `as of` +- `currently supports` + +These words are not always wrong. They tell the reviewer to check whether the claim still holds. + +### Mutable installs and downloads + +Flag commands or links that depend on moving targets: + +- `curl` or `wget` install scripts +- `latest` release URLs +- Package manager installs without an explicit version when exact reproducibility matters +- Container images tagged `latest` +- GitHub default branch clones or raw file downloads +- Nightly, preview, beta, or experimental packages + +### Version-specific dependencies + +Flag version-specific references that may need periodic verification: + +- OS versions and distro versions +- Runtime and compiler versions +- SDK, framework, and toolchain versions +- Cloud VM sizes, instance families, and processor names +- Model names, model IDs, container tags, and benchmark output + +### Screenshots and UI flows + +Screenshots are high maintenance risk when they show: + +- Cloud consoles +- Web dashboards +- IDEs or extensions +- Vendor portals +- Menus, dialogs, forms, buttons, tabs, or settings pages + +Use the image audit skill for detailed alt text, caption, and `#center` syntax review. Use this skill to decide whether the screenshot itself should be rechecked. + +### External dependencies + +Flag external links when they point to: + +- Official documentation with moving versioned content +- Release pages +- Download pages +- Pricing pages +- Support matrices +- GitHub repositories or examples +- Model repositories or hosted services + +External links are often valid; the review question is whether the linked target still supports the content's claim. + +### Dates and generated output + +Flag old dates, generated output timestamps, benchmark reports, and command output that may have been captured from an older environment. These are often acceptable examples, but they should be checked when they support a technical claim. + +## Prioritization + +Prioritize content for human review when several signals appear together, such as: + +- Screenshot-heavy UI instructions plus cloud-console steps. +- `latest` wording plus command output with a specific old version. +- External release links plus unpinned install commands. +- Product or VM names plus provider-specific setup steps. +- Old dates plus benchmark, support, or compatibility claims. diff --git a/.github/skills/stale-content-review/scripts/stale_content_scan.py b/.github/skills/stale-content-review/scripts/stale_content_scan.py new file mode 100755 index 0000000000..6929bfe315 --- /dev/null +++ b/.github/skills/stale-content-review/scripts/stale_content_scan.py @@ -0,0 +1,438 @@ +#!/usr/bin/env python3 +"""Scan Arm Learning Path content for stale-content risk signals.""" + +from __future__ import annotations + +import argparse +import csv +import datetime as dt +import json +import re +import sys +from collections import Counter, defaultdict +from pathlib import Path + + +DEFAULT_PATHS = ["content/learning-paths", "content/install-guides"] + +RULES = [ + { + "id": "temporal-language", + "score": 2, + "allow_code": False, + "reason": "Temporal wording may need freshness review.", + "pattern": re.compile( + r"\b(currently|current support|currently supports?|latest|recently|newly|" + r"at the time of writing|as of|today)\b", + re.IGNORECASE, + ), + }, + { + "id": "preview-or-beta", + "score": 3, + "allow_code": True, + "reason": "Preview, beta, nightly, or experimental content often changes quickly.", + "pattern": re.compile(r"\b(preview|beta|nightly|experimental|deprecated)\b", re.IGNORECASE), + }, + { + "id": "mutable-download", + "score": 4, + "allow_code": True, + "reason": "Install scripts, release downloads, or raw URLs can change without this content changing.", + "pattern": re.compile( + r"\b(curl|wget|Invoke-WebRequest|iwr)\b.*\b(latest|releases?|download|raw|install\.sh|script)\b|" + r"\b(latest|releases?|download|raw|install\.sh|script)\b.*\b(curl|wget|Invoke-WebRequest|iwr)\b", + re.IGNORECASE, + ), + }, + { + "id": "floating-container-tag", + "score": 3, + "allow_code": True, + "reason": "Container tags that point to latest can drift over time.", + "pattern": re.compile(r"\b[\w./-]+:latest\b", re.IGNORECASE), + }, + { + "id": "unpinned-package-install", + "score": 2, + "allow_code": True, + "reason": "Unpinned package installs may change as package repositories change.", + "pattern": re.compile( + r"\b(pip3?\s+install|python3?\s+-m\s+pip\s+install|npm\s+(?:install|i)|" + r"apt(?:-get)?\s+install|dnf\s+install|yum\s+install|brew\s+install|" + r"go\s+install|cargo\s+install)\b", + re.IGNORECASE, + ), + }, + { + "id": "version-specific-dependency", + "score": 2, + "allow_code": False, + "reason": "Version-specific dependency claims may need periodic verification.", + "pattern": re.compile( + r"\b(Ubuntu|Debian|Fedora|RHEL|Rocky Linux|Amazon Linux|macOS|Windows|" + r"Python|Node(?:\.js)?|npm|Java|JDK|Go|Rust|LLVM|GCC|CUDA|PyTorch|" + r"TensorFlow|Kubernetes|Docker|Terraform|OpenSSL|CMake)\s+" + r"(?:version\s*)?v?\d+(?:\.\d+){0,2}\b", + re.IGNORECASE, + ), + }, + { + "id": "external-moving-link", + "score": 2, + "allow_code": True, + "reason": "External release, download, docs, pricing, or support URLs may need checking.", + "pattern": re.compile( + r"https?://docs\.[^\s)\]\"]+|" + r"https?://[^\s)\]\"]*(?:latest|releases?|download|documentation|pricing|support|docs[./_-])[^\s)\]\"]*", + re.IGNORECASE, + ), + }, +] + +IMAGE_RE = re.compile(r"!\[([^\]]*)\]\(([^)\s]+)(?:\s+\"([^\"]*)\")?\)") +DATE_RE = re.compile(r"\b(20\d{2})[-/](\d{1,2})[-/](\d{1,2})\b") +FENCE_RE = re.compile(r"^\s*(```|~~~)") + +UI_IMAGE_WORDS = re.compile( + r"\b(screenshot|screen shot|console|portal|dashboard|ui|ide|visual studio|vs code|" + r"browser|dialog|menu|form|button|tab|settings|wizard|page|preview|extension)\b", + re.IGNORECASE, +) + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description="Scan content for stale-maintenance risk signals.") + parser.add_argument("paths", nargs="*", default=DEFAULT_PATHS, help="Files or directories to scan.") + parser.add_argument("--format", choices=["markdown", "json", "csv"], default="markdown") + parser.add_argument("--output", help="Write the report to this file.") + parser.add_argument( + "--min-score", + type=int, + default=None, + help="Only report files with this score or higher. Defaults to 20 for a full content scan and 4 for explicit paths.", + ) + parser.add_argument( + "--max-findings-per-file", + type=int, + default=12, + help="Maximum sample findings to print for each file in Markdown output.", + ) + parser.add_argument( + "--old-date-months", + type=int, + default=18, + help="Flag explicit YYYY-MM-DD or YYYY/MM/DD dates older than this many months.", + ) + parser.add_argument("--include-drafts", action="store_true", help="Include files with draft: true.") + return parser.parse_args() + + +def iter_markdown_files(paths: list[str]) -> list[Path]: + files: set[Path] = set() + for raw in paths: + path = Path(raw) + if path.is_file() and path.suffix == ".md": + files.add(path) + elif path.is_dir(): + for candidate in path.rglob("*.md"): + if ".git" not in candidate.parts: + files.add(candidate) + return sorted(files) + + +def parse_front_matter(lines: list[str]) -> dict[str, str]: + if not lines or lines[0].strip() != "---": + return {} + + front_matter: dict[str, str] = {} + for line in lines[1:]: + if line.strip() == "---": + break + match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)\s*$", line) + if match: + front_matter[match.group(1)] = match.group(2).strip().strip("'\"") + return front_matter + + +def is_draft(front_matter: dict[str, str]) -> bool: + return front_matter.get("draft", "").lower() == "true" + + +def content_unit(path: Path) -> str: + parts = path.parts + if len(parts) >= 4 and parts[0] == "content" and parts[1] == "learning-paths": + return "/".join(parts[:4]) + if len(parts) >= 3 and parts[0] == "content" and parts[1] == "install-guides": + if path.name == "_index.md" and len(parts) >= 4: + return "/".join(parts[:3]) + if len(parts) >= 4: + return "/".join(parts[:3]) + return str(path.with_suffix("")) + return str(path.parent) + + +def excerpt(line: str) -> str: + text = " ".join(line.strip().split()) + if len(text) > 160: + return text[:157] + "..." + return text + + +def add_finding(findings: list[dict], line: int, category: str, score: int, reason: str, text: str) -> None: + findings.append( + { + "line": line, + "category": category, + "score": score, + "reason": reason, + "excerpt": excerpt(text), + } + ) + + +def month_delta(start: dt.date, end: dt.date) -> int: + return (end.year - start.year) * 12 + (end.month - start.month) + + +def scan_file(path: Path, today: dt.date, old_date_months: int, include_drafts: bool) -> dict | None: + try: + text = path.read_text(encoding="utf-8") + except UnicodeDecodeError: + text = path.read_text(encoding="utf-8", errors="replace") + + lines = text.splitlines() + front_matter = parse_front_matter(lines) + if is_draft(front_matter) and not include_drafts: + return {"path": str(path), "skipped": "draft"} + + findings: list[dict] = [] + image_count = 0 + ui_image_count = 0 + in_fence = False + + for line_number, line in enumerate(lines, start=1): + if FENCE_RE.match(line): + in_fence = not in_fence + + for rule in RULES: + if in_fence and not rule["allow_code"]: + continue + if rule["pattern"].search(line): + add_finding(findings, line_number, rule["id"], rule["score"], rule["reason"], line) + + for match in DATE_RE.finditer(line): + year, month, day = map(int, match.groups()) + try: + found_date = dt.date(year, month, day) + except ValueError: + continue + if month_delta(found_date, today) >= old_date_months: + add_finding( + findings, + line_number, + "old-explicit-date", + 2, + "Explicit dates older than the threshold may need freshness review.", + line, + ) + break + + for match in IMAGE_RE.finditer(line): + image_count += 1 + alt, image_path, title = match.groups() + image_text = " ".join(part or "" for part in (alt, image_path, title)) + if UI_IMAGE_WORDS.search(image_text): + ui_image_count += 1 + add_finding( + findings, + line_number, + "screenshot-or-ui-image", + 5, + "Screenshot or UI image may need visual freshness review.", + line, + ) + + if image_count >= 4: + add_finding( + findings, + 0, + "image-heavy-page", + 2, + "Image-heavy pages can become stale when UI, output, or diagrams change.", + f"{image_count} Markdown image references found.", + ) + + if not findings: + return None + + by_category: dict[str, list[dict]] = defaultdict(list) + for finding in findings: + by_category[finding["category"]].append(finding) + + score = 0 + for category_findings in by_category.values(): + score += max(finding["score"] for finding in category_findings) + score += min(len(category_findings) - 1, 4) + + return { + "path": str(path), + "unit": content_unit(path), + "score": score, + "finding_count": len(findings), + "image_count": image_count, + "ui_image_count": ui_image_count, + "categories": dict(Counter(finding["category"] for finding in findings)), + "findings": findings, + } + + +def resolve_min_score(args: argparse.Namespace) -> int: + if args.min_score is not None: + return args.min_score + if args.paths == DEFAULT_PATHS: + return 20 + return 4 + + +def scan(paths: list[str], args: argparse.Namespace) -> tuple[list[dict], dict]: + today = dt.date.today() + candidates = iter_markdown_files(paths) + min_score = resolve_min_score(args) + records = [] + skipped = Counter() + + for path in candidates: + result = scan_file(path, today, args.old_date_months, args.include_drafts) + if not result: + continue + if result.get("skipped"): + skipped[result["skipped"]] += 1 + continue + if result["score"] >= min_score: + records.append(result) + + records.sort(key=lambda item: (-item["score"], item["path"])) + summary = { + "generated": today.isoformat(), + "scanned_files": len(candidates), + "reported_files": len(records), + "skipped": dict(skipped), + "min_score": min_score, + "paths": paths, + } + return records, summary + + +def category_summary(record: dict) -> str: + parts = [f"{category} ({count})" for category, count in record["categories"].items()] + return ", ".join(parts) + + +def escape_cell(value: object) -> str: + return str(value).replace("|", "\\|") + + +def format_markdown(records: list[dict], summary: dict, max_findings_per_file: int) -> str: + lines = [ + "# Stale Content Risk Scan", + "", + f"Generated: {summary['generated']}", + f"Scanned files: {summary['scanned_files']}", + f"Reported files: {summary['reported_files']} with score >= {summary['min_score']}", + ] + if summary["skipped"]: + skipped = ", ".join(f"{key}: {value}" for key, value in summary["skipped"].items()) + lines.append(f"Skipped files: {skipped}") + lines.extend(["", "## Top candidates", ""]) + + if not records: + lines.append("No files met the reporting threshold.") + return "\n".join(lines) + "\n" + + lines.extend( + [ + "| Score | File | Unit | Flags |", + "| ---: | --- | --- | --- |", + ] + ) + for record in records[:50]: + lines.append( + f"| {record['score']} | `{escape_cell(record['path'])}` | " + f"`{escape_cell(record['unit'])}` | {escape_cell(category_summary(record))} |" + ) + + lines.extend(["", "## Details", ""]) + for record in records: + lines.extend( + [ + f"### `{record['path']}`", + "", + f"- Score: {record['score']}", + f"- Unit: `{record['unit']}`", + f"- Flags: {category_summary(record)}", + ] + ) + if record["image_count"]: + lines.append(f"- Images: {record['image_count']} total, {record['ui_image_count']} UI/screenshot-like") + lines.append("") + + for finding in record["findings"][:max_findings_per_file]: + line_label = "file" if finding["line"] == 0 else f"line {finding['line']}" + lines.append( + f"- {line_label} [{finding['category']}]: {finding['reason']} " + f"`{finding['excerpt']}`" + ) + remaining = len(record["findings"]) - max_findings_per_file + if remaining > 0: + lines.append(f"- {remaining} more findings omitted from this sample.") + lines.append("") + + return "\n".join(lines) + + +def write_csv(records: list[dict], stream) -> None: + writer = csv.DictWriter( + stream, + fieldnames=["score", "path", "unit", "finding_count", "image_count", "ui_image_count", "categories"], + ) + writer.writeheader() + for record in records: + writer.writerow( + { + "score": record["score"], + "path": record["path"], + "unit": record["unit"], + "finding_count": record["finding_count"], + "image_count": record["image_count"], + "ui_image_count": record["ui_image_count"], + "categories": category_summary(record), + } + ) + + +def main() -> int: + args = parse_args() + records, summary = scan(args.paths, args) + + if args.format == "json": + output = json.dumps({"summary": summary, "records": records}, indent=2) + elif args.format == "csv": + if args.output: + with Path(args.output).open("w", encoding="utf-8", newline="") as stream: + write_csv(records, stream) + return 0 + write_csv(records, sys.stdout) + return 0 + else: + output = format_markdown(records, summary, args.max_findings_per_file) + + if args.output: + Path(args.output).write_text(output, encoding="utf-8") + else: + print(output) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.github/skills/writing-style-review/SKILL.md b/.github/skills/writing-style-review/SKILL.md new file mode 100644 index 0000000000..9666f1e3fe --- /dev/null +++ b/.github/skills/writing-style-review/SKILL.md @@ -0,0 +1,134 @@ +--- +name: writing-style-review +description: Review and improve writing style, voice, tone, readability, inclusive language, Arm terminology, heading style, word choice, and AI-sounding prose in Arm Learning Paths and install guides. Use when asked to polish prose, make content less AI-generated, improve clarity, or align with Arm editorial style. +--- + +# Writing style review + +Use this skill for granular prose, voice, readability, terminology, and style reviews. Keep edits focused and preserve technical meaning. + +## Workflow + +1. Identify the target file, section, or selected text. +2. Read surrounding context so style edits preserve the author's intent and the technical flow. +3. Review the target against the guidelines defined in this skill. +4. Depending on request type, do the following: + - For review requests, report high-impact style issues by file and line when possible. + - For edit requests, make focused rewrites, then re-open changed sections to check Markdown, shortcodes, links, and code fences. + +## Voice and tone + +- Use second person: `you` and `your` for Learning Path summaries, Learning Path content, install guide content, answers to FAQs, and metadata descriptions. Avoid first person for these content types. +- Use first person: `I` and `we` for FAQs. +- Use active voice. +- Use present tense for descriptions. +- Use imperative mood for commands. +- Keep the tone confident, developer-friendly, and natural. +- Encourage readers through complex tasks without generic praise or hype. + +## Inclusive language + +- Use `primary/subordinate` instead of `master/slave`. +- Do not use gendered examples or assumptions. +- Be mindful of cultural references that might not translate globally. +- Avoid assumptions about a reader's physical capabilities or setup. + +## Sentence structure and readability + +- Aim for an average of 15 to 20 words per sentence. +- Split complex sentences for clarity. +- Use plain English and avoid jargon overload. +- Define acronyms on first use. +- Use parallel structure in lists. +- Avoid starting sentences with "In this Learning Path"/ "In this section"/"On this page" / "In this step". +- Flag sections over 700 words and suggest natural split points. +- Identify paragraphs with sentences averaging over 20 words. +- Note sections that introduce more than two new concepts. +- Flag pages over 3500 words total when prose density hurts review or learning. +- Use visual breaks to prevent walls of text. Code blocks count as visual breaks. +- If a section explains three or more things, suggest splitting it. + +## Arm framing and technical depth + +- Default to Arm-native solutions, Arm terminology, and Arm platform assumptions. +- Flag x86 assumptions and suggest Arm alternatives when available. +- Match technical depth to the stated audience, prerequisites, and skill level. +- Keep the level of formality and technical detail consistent across related sections. +- Avoid generic advice that could apply to any architecture when the page needs Arm-specific guidance. +- Keep content accessible for screen readers with clear wording and descriptive references. + +## Word choice + +- Spell out numbers one through five. After that, use numerals. +- Use proper spacing for units: `1 GB`, `23 MB/day`. +- Use `K` for thousands and data-rate abbreviations such as `Gbps`. +- Use `To [action]` instead of `Follow the steps below to [action]`. +- Use `for example` instead of `e.g.`. +- Use `that is` instead of `i.e.`. +- Use `because` instead of `since`. +- Use `also` instead of `in addition`. +- Use `to` instead of `in order to`. +- Use `see` instead of `refer to`. +- Use `use` instead of `utilize` or `leverage`. +- Use `need` instead of `require`. +- Use `can` or `might` instead of `may`. +- Use `set up` as a verb and `setup` as a noun. +- Use `avoid` instead of `try not to`. +- Use `such as` instead of `like`. +- Use `after` or `when` instead of `once`. + +## Tone cleanup + +- Avoid `simply`, `just`, `obviously`, and `clearly`. +- Avoid `above`, `below`, `left`, `right`, `top`, and `bottom` when referring to content. +- Acknowledge difficulty naturally, such as `this step can be confusing at first`. +- Normalize errors, such as `if you see this error, here's how to fix it`. +- Use contractions such as `don't`, `isn't`, `it's`, `that's`, `you're`, and `you'll`. +- Remove unnecessary qualifiers such as `quite`, `very`, and `massive`. +- Use `an LLM`, not `a LLM`. +- Use `easy-to-use` as an adjective. +- Use `fixed-width`, not `fixed-length`. +- Use `read-to-write ratio`, not `read to write ratio`. + +## UI and formatting terms + +- Use `select` or `tap` instead of `click` for touch interfaces. +- Use `keyboard shortcut` instead of `key combination`. +- Use `Ctrl key`. +- Use `double-tap` instead of `double-click` for touch interfaces. +- Use **bold** for UI elements. +- Use *italics* for emphasis and new terms. +- Use `code formatting` for file names, commands, package names, flags, paths, and environment variables. + +## Headings and terminology + +- Use sentence case for headings and subheadings. +- Capitalize only the first word and proper nouns in headings. +- Keep heading wording consistent across related files. +- Prefer headings that signal the user task or concept. +- Ensure heading hierarchy has no skipped levels unless the template requires it. +- Each Markdown file should begin with a section heading in body content. +- Use `Arm` for the brand in prose. +- Use `arm64` or `aarch64` for CPU architecture based on tool, package, or OS convention. +- Use `ARM64` only when referring to Windows on Arm or Microsoft documentation. +- Capitalize `Learning Path`. +- Use `Azure Cobalt`, `Google Axion`, and `AWS Graviton` as processor names, not VM names. `Graviton-based instances`, not `Graviton instances`, for example. +- Do not use bold or italics for product names such as LiteRT, XNNPACK, KleidiAI, and SME2 unless they are headings or UI labels. + +## Avoid AI-sounding prose + +- Avoid more than three consecutive sections using bullet lists. +- Avoid bullets that would read more naturally as narrative paragraphs. +- Make list items parallel. +- Use flowing narrative where it improves readability. +- Vary sentence length. +- Use transitional phrases and relevant examples. +- Connect ideas logically. +- Avoid robotic encouragement such as `Great job - let's get started!`. +- Avoid multiple consecutive sentences starting with `This`. + +## Response format + +For reviews, lead with findings ordered by severity and include file and line references. Then add open questions or assumptions, followed by a short summary. + +For edits, summarize the style changes and note any checks performed. diff --git a/.wordlist.txt b/.wordlist.txt index e88832fe22..d9fb4f9631 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -6324,4 +6324,35 @@ perfrunbook pprof prj reflashing -unwinder \ No newline at end of file +unwinder +AmazonECS +Anupras +Mohapatra +RCTL +Rafay +Rafay's +RafayEKSProvisioner +aeaed +aed +balancer's +cbd +cdk +dac +dbdad +dcf +defaultproject +deprovision +dfbc +ebdd +ece +edbfe +ede +fcdebd +rafay +rctl +Prims +bbe +boundedness +cbf +dda +efe \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..2a1ce4277c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# Agent instructions + +This repository contains Arm Learning Paths and install guides for learn.arm.com. + +Use this file as a lightweight router for Codex, Copilot, and other coding agents. Do not treat it as the full style guide. Load only the guidance that matches the task. + +## Repository map + +- `content/learning-paths/` contains task-led, end-to-end tutorials. +- `content/install-guides/` contains installation and verification guides. +- `.github/skills/` contains reusable reviewer workflows and task-specific capabilities. + +## Compatibility + +- `.github/copilot-instructions.md` is a short compatibility pointer for Github Copilot. It is not the source of truth. + +## Reviewer workflows + +Use skills for repeatable workflows such as image audits, metadata description updates, stale-content audits, or structured content-quality checks. + +Current shared skills: + +- Learning Path structure review: `.github/skills/learning-path-structure-review/SKILL.md` +- Install guide structure review: `.github/skills/install-guide-structure-review/SKILL.md` +- Writing style and voice review: `.github/skills/writing-style-review/SKILL.md` +- Front matter and metadata audits: `.github/skills/frontmatter-audit/SKILL.md` +- Metadata descriptions: `.github/skills/metadata-description-update/SKILL.md` +- SEO, GEO, AEO, and AI-agent discoverability: `.github/skills/seo-geo-aeo-review/SKILL.md` +- Markdown components: `.github/skills/markdown-component-edit/SKILL.md` +- Accessible link text: `.github/skills/link-text-review/SKILL.md` +- Stale content risk scans: `.github/skills/stale-content-review/SKILL.md` +- Images, alt text, captions, and `#center` syntax: `.github/skills/audit-images/SKILL.md` +- Code samples, commands, outputs, and code fence integrity: `.github/skills/code-sample-review/SKILL.md` + +Keep deterministic scans in scripts when possible, and keep long reference material out of always-loaded instructions. + +Prefer the narrowest applicable file. Avoid loading every instruction file by default. + +When creating new skills, prefer a structured `SKILL.md` with concise sections such as description, prerequisites, trigger, workflow, validation rules, and error handling. Keep the workflow explicit enough to be repeatable without turning the skill into a full style guide. diff --git a/README.md b/README.md index 9419181154..9f582f5310 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Note that all site content, including new contributions, is licensed under a [Cr ## AI Development Tools -When using AI coding assistants (GitHub Copilot, Kiro, Antigravity, Cursor, etc.), refer to `.github/copilot-instructions.md` for project-specific guidelines including content requirements, writing style standards, and Arm terminology conventions for Learning Paths. +When using AI coding assistants (GitHub Copilot, Kiro, Antigravity, Cursor, etc.), refer to `AGENT.md` and `.github/skills/` for project-specific guidelines including content requirements, writing style standards, and Arm terminology conventions for Learning Paths.
diff --git a/assets/contributors.csv b/assets/contributors.csv index 7ea5309e90..fcf29231da 100644 --- a/assets/contributors.csv +++ b/assets/contributors.csv @@ -125,4 +125,5 @@ Akash Malik,Arm,akashmalik19973,akash-malik-a65bab219,, Matt Cossins,Arm,matt-cossins,,, Sue Wu,Arm,,,, Sabika Tasneem,Memgraph,,,, +Anupras Mohapatra,Arm,,,, Tomas Agustin Gonzalez Orlando,Arm,tgonzalezorlandoarm,tgorlando,, diff --git a/assets/css/content.css b/assets/css/content.css index 78d1e34861..d7083b6e09 100644 --- a/assets/css/content.css +++ b/assets/css/content.css @@ -153,7 +153,7 @@ img.content-uploaded-image.centered { /* have to style the span like a paragraph, required for nesting caption in default markdown configruation */ display: block; /* or block, depending on the desired layout */ font-style: italic; - font-weight: 500; + font-weight: 400; margin-top: 0px; font-size: 1rem; } diff --git a/assets/css/cross-page.css b/assets/css/cross-page.css index bdce13fe69..24ad075ad5 100644 --- a/assets/css/cross-page.css +++ b/assets/css/cross-page.css @@ -12,60 +12,35 @@ /* UNIVERSAL FONTS */ /****************************************************/ -/* Ignored for now, adding in head.html via google fonts. Can use this locally to optimize if needed */ - - -/* Lato font get from local fonts folder, not fonts.google.com as it loads facebook/youtube tracking data */ - /* Normal, Italic, Bold - 300, 400, 500 */ - -/* +/* Lato font self-hosted from /fonts/ to avoid external requests and reduce CLS */ @font-face { font-family: 'Lato'; font-style: normal; font-weight: 300; - src: url('../fonts/LatoLatin-Light.woff2') format('woff2'), - url('../fonts/LatoLatin-Light.ttf') format('ttf'); - } - - @font-face { + font-display: swap; + src: url('/fonts/LatoLatin-Light.woff2') format('woff2'); +} +@font-face { font-family: 'Lato'; font-style: normal; font-weight: 400; - src: url('../fonts/LatoLatin-Regular.woff2') format('woff2'), - url('../fonts/LatoLatin-Regular.ttf') format('ttf'); - } - - @font-face { - font-family: 'Lato'; - font-style: normal; - font-weight: 500; - src: url('../fonts/LatoLatin-Medium.woff2') format('woff2'), - url('../fonts/LatoLatin-Medium.ttf') format('ttf'); - } - + font-display: swap; + src: url('/fonts/LatoLatin-Regular.woff2') format('woff2'); +} @font-face { font-family: 'Lato'; font-style: italic; font-weight: 300; - src: url('../fonts/LatoLatin-LightItalic.woff2') format('woff2'), - url('../fonts/LatoLatin-LightItalic.ttf') format('ttf'); - } - @font-face { + font-display: swap; + src: url('/fonts/LatoLatin-LightItalic.woff2') format('woff2'); +} +@font-face { font-family: 'Lato'; font-style: italic; font-weight: 400; - src: url('../fonts/LatoLatin-Italic.woff2') format('woff2'), - url('../fonts/LatoLatin-Italic.ttf') format('ttf'); - } - @font-face { - font-family: 'Lato'; - font-style: italic; - font-weight: 500; - src: url('../fonts/LatoLatin-MediumItalic.woff2') format('woff2'), - url('../fonts/LatoLatin-MediumItalic.ttf') format('ttf'); - } -*/ + font-display: swap; + src: url('/fonts/LatoLatin-Italic.woff2') format('woff2'); +} /* UNIVERSAL */ @@ -183,17 +158,31 @@ table tbody td { +/* CLS fix: reserve space for nav before hydration */ +arm-top-navigation:not(:defined) { + display: block; + min-height: 80px; +} +@media (max-width: 1024px) { + arm-top-navigation:not(:defined) { + min-height: 60px; + } +} + /* Fix global nav height */ +/* The arm-global-web-components script renders a position:fixed nav (0 flow space) + and may inject a 50px sub-navigation bar in flow */ /*************************************/ #global-nav-height-fixer { max-width: 100vw; - min-height: 80px; + height: 80px; + overflow: hidden; position: relative; top: 0; } @media (max-width: 1024px) { /* smaller screens than LG */ #global-nav-height-fixer { - min-height: 60px; + height: 60px; } } .nav-transparent { @@ -453,3 +442,11 @@ html[theme='light'] body { ads-masthead { --ads-masthead-horizontal-padding: 5px; } } +/* CLS fix: reserve space for arm-footer before hydration */ +arm-footer-navigation:not(:defined) { + display: block; + min-height: 300px; +} +#arm-footer { + contain: layout; +} diff --git a/assets/css/home.css b/assets/css/home.css index cfc9670351..842872d96f 100644 --- a/assets/css/home.css +++ b/assets/css/home.css @@ -1,6 +1,32 @@ +/* CLS fix: reserve space for web components before hydration */ +ads-search:not(:defined) { + display: block; + min-height: 45px; +} +ads-cta-button:not(:defined) { + display: inline-block; + min-height: 40px; + min-width: 200px; +} +ads-breadcrumbs:not(:defined) { + display: block; + min-height: 32px; +} + +/* CLS fix: lock the breadcrumb masthead height so hydration doesn't shift content below */ +#only-breadcrumb-masthead { + height: 40px; + overflow: hidden; +} + +/* CLS fix: lock the description+button area height to prevent shift when ads-cta-button hydrates */ +.homepage-top-desc { + min-height: 110px; +} + /********************************************************************* Main Topic Cards diff --git a/assets/css/list-pages.css b/assets/css/list-pages.css index b98dbe7cdb..b0c4e337da 100644 --- a/assets/css/list-pages.css +++ b/assets/css/list-pages.css @@ -7,6 +7,25 @@ Covers the following pages: +/* CLS fix: reserve space for web components before hydration +*******************************************************************/ +ads-card:not(:defined) { + display: block; + min-height: 180px; +} +ads-search:not(:defined) { + display: block; + min-height: 45px; +} +ads-expansion-panel:not(:defined) { + display: block; + min-height: 48px; +} +ads-masthead:not(:defined) { + display: block; + min-height: 100px; +} + /* Search / Status bar for active filters, # displayed, and sorting *******************************************************************/ #result-sort-div { @@ -313,7 +332,7 @@ html[theme="light"] .learning-path-title, html[theme="light"] .basics-title { /*font-weight: bold; font-size:1.25rem; */ - font-weight: 500; + font-weight: 400; margin-top: 0px; margin-bottom: 4px; diff --git a/content/install-guides/_index.md b/content/install-guides/_index.md index 8534712b95..31ca108b09 100644 --- a/content/install-guides/_index.md +++ b/content/install-guides/_index.md @@ -1,5 +1,6 @@ --- title: "Install Guides" +description: Browse install guides for Arm developer tools, cloud CLIs, compilers, containers, and platform setup across Arm Linux, Windows on Arm, and macOS. additional_search_terms: - compiler - ide diff --git a/content/install-guides/ambaviz.md b/content/install-guides/ambaviz.md index d4f76752f4..0e18141655 100644 --- a/content/install-guides/ambaviz.md +++ b/content/install-guides/ambaviz.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm AMBA Viz +description: Install Arm AMBA Viz from Arm Product Download Hub and set up the environment to visualize AMBA events for SoC verification workflows. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/ams.md b/content/install-guides/ams.md index f4cff56adc..6361ad2035 100644 --- a/content/install-guides/ams.md +++ b/content/install-guides/ams.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Performance Studio +description: Install Arm Performance Studio on Windows, macOS, or Linux to profile Android and Linux applications with Arm performance analysis tools. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/ansible.md b/content/install-guides/ansible.md index be6395f494..bce848986f 100644 --- a/content/install-guides/ansible.md +++ b/content/install-guides/ansible.md @@ -14,6 +14,7 @@ test_images: - ubuntu:latest test_link: null title: Ansible +description: Install Ansible command-line tools on Ubuntu for Arm or macOS so you can automate configuration and software deployment from Arm-based systems. tool_install: true weight: 1 --- diff --git a/content/install-guides/arduino-pico.md b/content/install-guides/arduino-pico.md index 5fe9633bde..b3dfa8abdc 100644 --- a/content/install-guides/arduino-pico.md +++ b/content/install-guides/arduino-pico.md @@ -1,5 +1,6 @@ --- title: Arduino core for the Raspberry Pi Pico +description: Install the Arduino IDE and Raspberry Pi Pico board support so you can build and upload Arduino sketches for RP2040-based boards. author: Michael Hall additional_search_terms: - arduino @@ -76,4 +77,4 @@ You should see the LED on your Raspberry Pi Pico blink on and off every second. If you have trouble uploading a sketch, unplug the board, press and hold the `BOOTSEL` button on the board, plug it in, and then release the button. {{% /notice %}} -You are ready to start writing your own Arduino sketches for Raspberry Pi Pico. \ No newline at end of file +You are ready to start writing your own Arduino sketches for Raspberry Pi Pico. diff --git a/content/install-guides/armds.md b/content/install-guides/armds.md index dd5f08b388..09f133efc1 100644 --- a/content/install-guides/armds.md +++ b/content/install-guides/armds.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Development Studio +description: Install Arm Development Studio on Windows or Linux and configure licensing for embedded C and C++ development, debug, and SoC validation. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/avh.md b/content/install-guides/avh.md index 521d76330a..3548a0d9a3 100644 --- a/content/install-guides/avh.md +++ b/content/install-guides/avh.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Virtual Hardware +description: Access Arm Virtual Hardware Corstone and third-party platforms so you can develop and test embedded software without physical hardware. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/aws-cdk.md b/content/install-guides/aws-cdk.md new file mode 100644 index 0000000000..64eb1a2772 --- /dev/null +++ b/content/install-guides/aws-cdk.md @@ -0,0 +1,81 @@ +--- +additional_search_terms: +- cloud +- deploy +layout: installtoolsall +minutes_to_complete: 15 +author: Anupras Mohapatra +multi_install: false +multitool_install_part: false +official_docs: https://docs.aws.amazon.com/cdk/v2/guide/home.html +test_images: +- ubuntu:latest +test_maintenance: true +title: AWS CDK CLI +description: Install the AWS CDK CLI on Arm Linux and macOS using npm, then verify the setup with the `cdk` command. +tool_install: true +weight: 1 +--- + +The AWS Cloud Development Kit (AWS CDK) is an open-source infrastructure as code (IaC) software development framework. You can use the AWS CDK to define and deploy applications on Arm-based cloud infrastructure powered by AWS Graviton. + +You can write applications in a supported programming language of your choice. Then, you can use the AWS CDK CLI to translate the code into an AWS CloudFormation template and deploy the application. + +In this guide, you'll learn how to install the CDK CLI and verify that the CLI installation was successful. + +## Before you begin + +Verify that you have the AWS CLI installed: + +```bash +aws --version +``` + +The output is similar to: + +```output +aws-cli/2.34.56 Python/3.14.5 Darwin/25.5.0 exe/arm64 +``` +For instructions to set up AWS credentials and install the AWS CLI, see the [AWS Credentials](/install-guides/aws_access_keys/) and [AWS CLI](/install-guides/aws-cli/) install guides. + +Make sure you have Node.js 22 or later installed: + +```bash +node --version +``` + +The output is similar to: + +```output +v26.2.0 +``` +If you don't have Node.js installed, or if the installed version is earlier than Node.js 22, download a suitable version from the [Node.js website](https://nodejs.org/en/download). + +You'll also need to install prerequisites specific to the programming languages that you want to use. For more information, see [Install Node.js and programming language prerequisites](https://docs.aws.amazon.com/cdk/v2/guide/prerequisites.html#prerequisites-node) in the AWS CDK documentation. + +## Install the AWS CDK CLI + +Use `npm` to install the AWS CDK CLI: + +```bash +npm install -g aws-cdk +``` + +## Verify the installation + +After installing the AWS CDK CLI, check the version of the CLI: + +```bash +cdk --version +``` + +The output is similar to: + +```output +2.1125.0 (build 71fd29e) +``` +## Next steps + +You've now installed the AWS CDK CLI and verified that the installation was successful. + +Next, you can use the AWS CDK to create and deploy applications on Arm-based compute powered by AWS Graviton. To learn how you can use the AWS CDK and Amazon Elastic Container Service (Amazon ECS) to run containers on Arm-based compute, see [Deploy containers on Arm-based compute using Amazon ECS and the AWS CDK](/learning-paths/servers-and-cloud-computing/aws-cdk/). diff --git a/content/install-guides/aws-cli.md b/content/install-guides/aws-cli.md index 81a5b8e98a..42cf85171f 100644 --- a/content/install-guides/aws-cli.md +++ b/content/install-guides/aws-cli.md @@ -14,6 +14,7 @@ test_images: - ubuntu:latest test_maintenance: true title: AWS CLI +description: Install AWS CLI version 2 on Ubuntu for Arm and verify the setup so you can manage AWS services from the command line. tool_install: true weight: 1 --- diff --git a/content/install-guides/aws-copilot.md b/content/install-guides/aws-copilot.md index 60d7f5b1bc..aec277593c 100644 --- a/content/install-guides/aws-copilot.md +++ b/content/install-guides/aws-copilot.md @@ -14,6 +14,7 @@ test_images: - ubuntu:latest test_maintenance: true title: AWS Copilot CLI +description: Install AWS Copilot CLI on Ubuntu for Arm or macOS and verify the setup so you can deploy container applications to AWS services. tool_install: true weight: 1 --- @@ -128,4 +129,4 @@ The installed version is displayed: ```output copilot version: v1.34.0 -``` \ No newline at end of file +``` diff --git a/content/install-guides/aws-greengrass-v2.md b/content/install-guides/aws-greengrass-v2.md index fed83afade..94bdc52a2a 100644 --- a/content/install-guides/aws-greengrass-v2.md +++ b/content/install-guides/aws-greengrass-v2.md @@ -1,5 +1,6 @@ --- title: AWS IoT Greengrass +description: Install AWS IoT Greengrass on an Arm device and register it with AWS so you can build and manage IoT edge applications. author: Michael Hall additional_search_terms: - iot @@ -213,4 +214,4 @@ Click on the device name to see more device details. ![Greengrass Devices #center](/install-guides/_images/greengrass-devices.png) -You are now ready to use AWS IoT Greengrass v2 on your device. \ No newline at end of file +You are now ready to use AWS IoT Greengrass v2 on your device. diff --git a/content/install-guides/aws-sam-cli.md b/content/install-guides/aws-sam-cli.md index 9556e7fa69..4705da6b01 100644 --- a/content/install-guides/aws-sam-cli.md +++ b/content/install-guides/aws-sam-cli.md @@ -1,5 +1,6 @@ --- title: AWS SAM CLI +description: Install AWS SAM CLI on Ubuntu for Arm and test the setup so you can build, test, and deploy serverless applications locally. author: Jason Andrews minutes_to_complete: 15 @@ -174,4 +175,3 @@ REPORT RequestId: 513dbd6f-7fc0-4212-ae13-a9a4ce2f21f4 Init Duration: 0.26 ms Du ``` You are ready to use the AWS SAM CLI to build more complex functions and deploy them into AWS. Make sure to select `arm64` as the architecture for your Lambda functions. - diff --git a/content/install-guides/aws_access_keys.md b/content/install-guides/aws_access_keys.md index add12ade79..69b43160fc 100644 --- a/content/install-guides/aws_access_keys.md +++ b/content/install-guides/aws_access_keys.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: AWS Credentials +description: Generate AWS access keys and configure them for AWS CLI so command-line tools can sign programmatic requests to AWS services. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/azure-cli.md b/content/install-guides/azure-cli.md index 20e2b53a6e..a495cb7458 100644 --- a/content/install-guides/azure-cli.md +++ b/content/install-guides/azure-cli.md @@ -13,6 +13,7 @@ test_images: - ubuntu:latest test_maintenance: true title: Azure CLI +description: Install Azure CLI on Ubuntu for Arm using a script or pip so you can manage Azure resources from an Arm Linux system. tool_install: true weight: 1 --- diff --git a/content/install-guides/azure_login.md b/content/install-guides/azure_login.md index 4b129b2298..ce26f7781d 100644 --- a/content/install-guides/azure_login.md +++ b/content/install-guides/azure_login.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Azure Authentication +description: Sign in to Azure with Azure CLI and select a subscription so you can query and manage Azure cloud resources from the command line. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/bedrust.md b/content/install-guides/bedrust.md index c309029f00..46f652ad83 100644 --- a/content/install-guides/bedrust.md +++ b/content/install-guides/bedrust.md @@ -1,5 +1,6 @@ --- title: Bedrust - invoke models on Amazon Bedrock +description: Build and install Bedrust on Arm Linux so you can invoke Amazon Bedrock foundation models from the command line. minutes_to_complete: 10 author: Jason Andrews @@ -204,4 +205,3 @@ The output shows the model strings you can use. Make sure to enable the models y You are now ready to use Bedrust as a quick way to explore many Bedrock models and compare them. - diff --git a/content/install-guides/browsers/_index.md b/content/install-guides/browsers/_index.md index 2e4851cd70..136dd8cbc0 100644 --- a/content/install-guides/browsers/_index.md +++ b/content/install-guides/browsers/_index.md @@ -1,5 +1,6 @@ --- title: Browsers on Arm +description: Review browser availability on Arm Linux and Windows on Arm so you can choose and install a browser for development workflows. author: Jason Andrews additional_search_terms: - browser @@ -53,4 +54,3 @@ Edge and Firefox are good native browsers with DRM support for Windows on Arm. T Please share your experiences with browsers on Arm by submitting a [GitHub issue](https://github.com/ArmDeveloperEcosystem/arm-learning-paths/issues/new) or a GitHub Pull Request to add additional browsers. - diff --git a/content/install-guides/browsers/brave.md b/content/install-guides/browsers/brave.md index e98528d170..57956c4111 100644 --- a/content/install-guides/browsers/brave.md +++ b/content/install-guides/browsers/brave.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Brave +description: Install Brave on Arm Linux or Windows on Arm and use a native browser for development and web testing on Arm platforms. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -81,4 +82,3 @@ If you want the smaller, online installer download the file `BraveBrowserSetupAr - diff --git a/content/install-guides/browsers/chrome.md b/content/install-guides/browsers/chrome.md index 0edd82c4d9..a378601ea7 100644 --- a/content/install-guides/browsers/chrome.md +++ b/content/install-guides/browsers/chrome.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Chrome +description: Install Chrome on Windows on Arm and understand its Arm Linux availability so you can choose a supported browser for Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/browsers/chromium.md b/content/install-guides/browsers/chromium.md index acfb3b6f29..0f15b2178b 100644 --- a/content/install-guides/browsers/chromium.md +++ b/content/install-guides/browsers/chromium.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Chromium +description: Install Chromium on Arm Linux or Windows on Arm and use a native open-source browser for development and testing. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -74,4 +75,3 @@ Chromium on Windows on Arm does not update itself so you need to update manually {{% notice Note3%}} Certain types of videos don't play with Chromium. Video support is less than other browsers without DRM. {{% /notice %}} - diff --git a/content/install-guides/browsers/edge.md b/content/install-guides/browsers/edge.md index 179661ed2c..841825bbc3 100644 --- a/content/install-guides/browsers/edge.md +++ b/content/install-guides/browsers/edge.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Edge +description: Use Microsoft Edge on Windows on Arm and review install options so you can work with the default native browser on Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -37,4 +38,3 @@ The Linux downloads are not for the Arm architecture. - diff --git a/content/install-guides/browsers/firefox.md b/content/install-guides/browsers/firefox.md index e3e4285e48..e3fac8ac6a 100644 --- a/content/install-guides/browsers/firefox.md +++ b/content/install-guides/browsers/firefox.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Firefox +description: Install Firefox on Arm Linux or Windows on Arm and use a native browser for development and testing on Arm platforms. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -65,4 +66,3 @@ To install Firefox on Windows on Arm: 4. Find and start Firefox from the applications menu - diff --git a/content/install-guides/browsers/vivaldi.md b/content/install-guides/browsers/vivaldi.md index 640214ba88..ccd534d7ca 100644 --- a/content/install-guides/browsers/vivaldi.md +++ b/content/install-guides/browsers/vivaldi.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Vivaldi +description: Install Vivaldi on Arm Linux or Windows on Arm and use a native browser for development and web workflows. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/claude-code.md b/content/install-guides/claude-code.md index 4931a9eaff..45a6450d2e 100644 --- a/content/install-guides/claude-code.md +++ b/content/install-guides/claude-code.md @@ -1,5 +1,6 @@ --- title: Claude Code +description: Install Claude Code on Arm Linux, Apple Silicon macOS, or Windows on Arm so you can use terminal-based AI coding assistance. author: Pareena Verma minutes_to_complete: 10 diff --git a/content/install-guides/container.md b/content/install-guides/container.md index 29e3d26293..56b00a202a 100644 --- a/content/install-guides/container.md +++ b/content/install-guides/container.md @@ -1,5 +1,6 @@ --- title: Container CLI for macOS +description: Install Apple Container CLI on Apple Silicon macOS and verify it by building and running Arm Linux containers in lightweight virtual machines. author: Rani Chowdary Mandepudi minutes_to_complete: 10 official_docs: https://github.com/apple/container diff --git a/content/install-guides/cyclonedds.md b/content/install-guides/cyclonedds.md index df3464bbf5..77008e66e1 100644 --- a/content/install-guides/cyclonedds.md +++ b/content/install-guides/cyclonedds.md @@ -1,5 +1,6 @@ --- title: Cyclone DDS +description: Build and install Eclipse Cyclone DDS on Arm Linux and test the setup for real-time publish-subscribe communication in robotics and IoT applications. author: Odin Shen minutes_to_complete: 20 official_docs: https://cyclonedds.io/ @@ -119,4 +120,4 @@ If you observe the following output from each of the terminals, Cyclone DDS is r {{< /tab >}} {{< /tabpane >}} -You are now ready to use Cyclone DDS. \ No newline at end of file +You are now ready to use Cyclone DDS. diff --git a/content/install-guides/dcperf.md b/content/install-guides/dcperf.md index 3e20afa4d2..0960b59cdc 100644 --- a/content/install-guides/dcperf.md +++ b/content/install-guides/dcperf.md @@ -1,5 +1,6 @@ --- title: DCPerf +description: Install and run DCPerf on Arm-based servers to benchmark data center workloads and collect performance data for analysis or regression testing. author: Kieran Hejmadi minutes_to_complete: 20 official_docs: https://github.com/facebookresearch/DCPerf?tab=readme-ov-file#install-and-run-benchmarks diff --git a/content/install-guides/docker/_index.md b/content/install-guides/docker/_index.md index 14a27bfb2e..7097451eed 100644 --- a/content/install-guides/docker/_index.md +++ b/content/install-guides/docker/_index.md @@ -1,5 +1,6 @@ --- title: Docker +description: Choose the right Docker installation path for Arm Linux, ChromeOS, Windows, or macOS so you can build and run containers on Arm systems. author: Jason Andrews additional_search_terms: - containers diff --git a/content/install-guides/docker/docker-desktop-arm-linux.md b/content/install-guides/docker/docker-desktop-arm-linux.md index 7ee0e3009b..1774c61ad2 100644 --- a/content/install-guides/docker/docker-desktop-arm-linux.md +++ b/content/install-guides/docker/docker-desktop-arm-linux.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Docker Desktop for Arm Linux +description: Install Docker Desktop on Arm Linux and verify the setup so you can run container workflows with the Docker Desktop environment. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/docker/docker-desktop.md b/content/install-guides/docker/docker-desktop.md index 13650215dc..d0ce8201d4 100644 --- a/content/install-guides/docker/docker-desktop.md +++ b/content/install-guides/docker/docker-desktop.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Docker Desktop +description: Install Docker Desktop on Windows or macOS and test container execution so you can build and run Docker workloads on Arm-capable systems. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/docker/docker-engine.md b/content/install-guides/docker/docker-engine.md index f4ffdfb984..b8d7c5898d 100644 --- a/content/install-guides/docker/docker-engine.md +++ b/content/install-guides/docker/docker-engine.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Docker Engine +description: Install Docker Engine on Linux, WSL 2, or ChromeOS and verify the setup so you can run containers from the command line. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -157,4 +158,3 @@ sudo systemctl stop docker.socket You can now use Docker Engine and explore [Docker related Learning Paths](/tag/docker/). You can also create an account on [Docker Hub](https://hub.docker.com) to share images and automate workflows. - diff --git a/content/install-guides/dotnet.md b/content/install-guides/dotnet.md index e97b0d0732..244696a58b 100644 --- a/content/install-guides/dotnet.md +++ b/content/install-guides/dotnet.md @@ -13,6 +13,7 @@ test_images: test_link: null test_maintenance: true title: .NET SDK +description: Install the .NET SDK on Arm Linux and choose an SDK version so you can build and run .NET applications on Arm-based systems. tool_install: true weight: 1 --- diff --git a/content/install-guides/finch.md b/content/install-guides/finch.md index 126c895cc3..298eae899a 100644 --- a/content/install-guides/finch.md +++ b/content/install-guides/finch.md @@ -1,5 +1,6 @@ --- title: Finch on Arm Linux +description: Install Finch on Amazon Linux 2023 or Ubuntu 24.04 for Arm and verify Docker-compatible container workflows with containerd and nerdctl. author: Jason Andrews minutes_to_complete: 10 diff --git a/content/install-guides/fm_fvp/_index.md b/content/install-guides/fm_fvp/_index.md index a9dd18564e..aa672c6c7b 100644 --- a/content/install-guides/fm_fvp/_index.md +++ b/content/install-guides/fm_fvp/_index.md @@ -1,5 +1,6 @@ --- title: Arm Fast Models and FVPs +description: Install Arm Fast Models and Fixed Virtual Platforms so you can create and run virtual Arm platforms for software development and verification. author: Ronan Synnott additional_search_terms: diff --git a/content/install-guides/fm_fvp/eco_fvp.md b/content/install-guides/fm_fvp/eco_fvp.md index c9d6173bb1..54de28bdc4 100644 --- a/content/install-guides/fm_fvp/eco_fvp.md +++ b/content/install-guides/fm_fvp/eco_fvp.md @@ -1,5 +1,6 @@ --- title: Arm Ecosystem FVPs and Architecture Envelope Models +description: Download and install Arm Ecosystem FVPs or Architecture Envelope Models on supported hosts to explore Arm systems before hardware is available. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/100966 author: Ronan Synnott diff --git a/content/install-guides/fm_fvp/fm.md b/content/install-guides/fm_fvp/fm.md index b5f8cad5b4..539a883061 100644 --- a/content/install-guides/fm_fvp/fm.md +++ b/content/install-guides/fm_fvp/fm.md @@ -1,5 +1,6 @@ --- title: Arm Fast Models +description: Install Arm Fast Models on Linux or Windows and prepare host toolchains so you can build executable virtual platforms for Arm software development. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/107572 author: Ronan Synnott diff --git a/content/install-guides/fm_fvp/fvp.md b/content/install-guides/fm_fvp/fvp.md index 71c666e4ff..f5c139888d 100644 --- a/content/install-guides/fm_fvp/fvp.md +++ b/content/install-guides/fm_fvp/fvp.md @@ -1,5 +1,6 @@ --- title: Fixed Virtual Platforms (FVP) +description: Install the legacy Arm Fixed Virtual Platform library on Windows or Linux so you can run ready-to-use virtual Arm platforms. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/100966/ author: Ronan Synnott @@ -82,4 +83,3 @@ You can a workaround this error using `execstack` on each of the runtime binarie execstack -c ``` {{% /notice %}} - diff --git a/content/install-guides/fvps-on-macos.md b/content/install-guides/fvps-on-macos.md index 363d72a3b3..51af51187b 100644 --- a/content/install-guides/fvps-on-macos.md +++ b/content/install-guides/fvps-on-macos.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: AVH FVPs on macOS +description: Run Arm Virtual Hardware Fixed Virtual Platforms on macOS with Docker containers so you can use FVP models from an Apple development machine. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/gcc/_index.md b/content/install-guides/gcc/_index.md index 4095258c89..d33d999b96 100644 --- a/content/install-guides/gcc/_index.md +++ b/content/install-guides/gcc/_index.md @@ -1,5 +1,6 @@ --- title: GNU Compiler +description: Choose and install the right GCC toolchain for native Arm Linux development, Arm Linux cross-compilation, or bare-metal Arm targets. author: Jason Andrews additional_search_terms: - compiler diff --git a/content/install-guides/gcc/cross.md b/content/install-guides/gcc/cross.md index ce4cb06bca..69d6359672 100644 --- a/content/install-guides/gcc/cross.md +++ b/content/install-guides/gcc/cross.md @@ -13,6 +13,7 @@ test_images: test_link: null test_maintenance: true title: Cross-compiler +description: Install GCC cross-compilers on Linux so you can build 32-bit or 64-bit Arm Linux applications from a non-target host. tool_install: false weight: 3 --- diff --git a/content/install-guides/gcc/native.md b/content/install-guides/gcc/native.md index 42d22afa35..3904989b2a 100644 --- a/content/install-guides/gcc/native.md +++ b/content/install-guides/gcc/native.md @@ -14,6 +14,7 @@ test_images: test_link: null test_maintenance: true title: Native compiler +description: Install native GCC and G++ packages on Arm Linux so you can compile C and C++ applications directly on an Arm machine. tool_install: false weight: 2 --- diff --git a/content/install-guides/gcloud.md b/content/install-guides/gcloud.md index ae4a4eb05b..e57d39fc30 100644 --- a/content/install-guides/gcloud.md +++ b/content/install-guides/gcloud.md @@ -16,6 +16,7 @@ test_images: - ubuntu:latest test_maintenance: true title: Google Cloud Platform (GCP) CLI +description: Install the Google Cloud CLI on Ubuntu for Arm and verify the setup so you can manage Google Cloud resources with gcloud. tool_install: true weight: 1 --- diff --git a/content/install-guides/gemini.md b/content/install-guides/gemini.md index 24896dc1c2..7a36072cde 100644 --- a/content/install-guides/gemini.md +++ b/content/install-guides/gemini.md @@ -1,5 +1,6 @@ --- title: Gemini CLI +description: Install Gemini CLI on macOS or Arm Linux and configure authentication so you can use Google's command-line AI assistant for development tasks. author: Jason Andrews minutes_to_complete: 15 diff --git a/content/install-guides/gfortran.md b/content/install-guides/gfortran.md index 0215327664..074e89c368 100644 --- a/content/install-guides/gfortran.md +++ b/content/install-guides/gfortran.md @@ -19,6 +19,7 @@ test_images: test_link: null test_maintenance: true title: GFortran +description: Install GNU Fortran on Arm Linux and compile a test program so you can build Fortran applications with GCC tooling. tool_install: true weight: 1 --- diff --git a/content/install-guides/git-woa.md b/content/install-guides/git-woa.md index ad46e29786..b84624fe6f 100644 --- a/content/install-guides/git-woa.md +++ b/content/install-guides/git-woa.md @@ -1,5 +1,6 @@ --- title: Git for Windows on Arm +description: Install native Git for Windows on Arm and verify Git commands in Command Prompt, PowerShell, or Git Bash. additional_search_terms: - git diff --git a/content/install-guides/github-copilot.md b/content/install-guides/github-copilot.md index b509fbb8df..dd552f5c38 100644 --- a/content/install-guides/github-copilot.md +++ b/content/install-guides/github-copilot.md @@ -1,5 +1,6 @@ --- title: GitHub Copilot +description: Install GitHub Copilot in Visual Studio Code on Arm systems and connect it with the Arm MCP Server for Arm-focused development assistance. author: Pareena Verma minutes_to_complete: 10 diff --git a/content/install-guides/helm.md b/content/install-guides/helm.md index f591ac39e5..ce286e212b 100644 --- a/content/install-guides/helm.md +++ b/content/install-guides/helm.md @@ -1,5 +1,6 @@ --- title: Helm +description: Install Helm on Ubuntu for Arm and verify the setup so you can manage Kubernetes applications with charts. author: Jason Andrews minutes_to_complete: 10 diff --git a/content/install-guides/hyper-v.md b/content/install-guides/hyper-v.md index 5be508b262..7cfc356de0 100644 --- a/content/install-guides/hyper-v.md +++ b/content/install-guides/hyper-v.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Hyper-V on Arm +description: Enable Hyper-V on Windows 11 on Arm so you can create and run virtual machines on supported Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/ipexplorer.md b/content/install-guides/ipexplorer.md index 31a84c9d07..0325c8b485 100644 --- a/content/install-guides/ipexplorer.md +++ b/content/install-guides/ipexplorer.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm IP Explorer +description: Access Arm IP Explorer in the browser and use it to explore Arm IP, simulate processors, and create SoC concepts. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/java.md b/content/install-guides/java.md index c5d0185654..66e3a0523f 100644 --- a/content/install-guides/java.md +++ b/content/install-guides/java.md @@ -1,5 +1,6 @@ --- title: Java +description: Install Java runtimes and development kits on Arm Linux using package managers, Snap, or vendor distributions for Java application development. author: Jason Andrews minutes_to_complete: 15 official_docs: https://docs.oracle.com/en/java/ diff --git a/content/install-guides/keilstudio_vs.md b/content/install-guides/keilstudio_vs.md index a43a1b7e5d..dd471f8d51 100644 --- a/content/install-guides/keilstudio_vs.md +++ b/content/install-guides/keilstudio_vs.md @@ -1,5 +1,6 @@ --- title: Arm Keil Studio for VS Code +description: Install Arm Keil Studio extensions for Visual Studio Code and verify the setup for Cortex-M embedded development on desktop hosts. additional_search_terms: - cortex-m diff --git a/content/install-guides/keilstudiocloud.md b/content/install-guides/keilstudiocloud.md index 0078e566c7..7dad434647 100644 --- a/content/install-guides/keilstudiocloud.md +++ b/content/install-guides/keilstudiocloud.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Keil Studio Cloud +description: Open Arm Keil Studio Cloud in a Chromium-based browser and start browser-based Cortex-M, IoT, and embedded development without local installation. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -40,4 +41,4 @@ Keil Studio Cloud does not require any installation. To run the browser-based ID ## How do I get started with Keil Studio Cloud? -[Get started with an Mbed OS Blinky example](https://developer.arm.com/documentation/102497/latest/Tutorials/Get-started-with-an-Mbed-OS-Blinky-example) is a great way to start. \ No newline at end of file +[Get started with an Mbed OS Blinky example](https://developer.arm.com/documentation/102497/latest/Tutorials/Get-started-with-an-Mbed-OS-Blinky-example) is a great way to start. diff --git a/content/install-guides/kiro-cli.md b/content/install-guides/kiro-cli.md index 58f2d4d1ee..e096852a62 100644 --- a/content/install-guides/kiro-cli.md +++ b/content/install-guides/kiro-cli.md @@ -1,5 +1,6 @@ --- title: Kiro CLI +description: Install Kiro CLI on macOS or Arm Linux and verify authentication so you can use AWS-focused AI assistance from the command line. author: Jason Andrews minutes_to_complete: 10 diff --git a/content/install-guides/kubectl.md b/content/install-guides/kubectl.md index 670a72fe12..467baf1c7b 100644 --- a/content/install-guides/kubectl.md +++ b/content/install-guides/kubectl.md @@ -18,6 +18,7 @@ test_images: test_link: null test_maintenance: true title: Kubectl +description: Install kubectl on Ubuntu for Arm and verify the Kubernetes CLI so you can run commands against Kubernetes clusters. tool_install: true weight: 1 --- @@ -78,4 +79,4 @@ Confirm the executable is available and get the version of the client: kubectl version -o json --client ``` -You are ready to use the Kubernetes command-line tool, `kubectl` \ No newline at end of file +You are ready to use the Kubernetes command-line tool, `kubectl` diff --git a/content/install-guides/license/_index.md b/content/install-guides/license/_index.md index e28f4ab5e8..cc31181736 100644 --- a/content/install-guides/license/_index.md +++ b/content/install-guides/license/_index.md @@ -1,5 +1,6 @@ --- title: Arm Software Licensing +description: Configure Arm software licensing with user-based, cloud, local, or FlexNet license servers so Arm commercial tools can check out licenses. author: Ronan Synnott additional_search_terms: - success kits diff --git a/content/install-guides/license/cloud.md b/content/install-guides/license/cloud.md index 8fec579a24..13c8f6a2ee 100644 --- a/content/install-guides/license/cloud.md +++ b/content/install-guides/license/cloud.md @@ -1,5 +1,6 @@ --- title: UBL Cloud server setup +description: Generate and activate Arm user-based licenses with the Cloud License Server so end users can check out commercial Arm tool licenses. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/107573 author: Ronan Synnott diff --git a/content/install-guides/license/flexnet.md b/content/install-guides/license/flexnet.md index 3e00ed96cb..81ac530261 100644 --- a/content/install-guides/license/flexnet.md +++ b/content/install-guides/license/flexnet.md @@ -1,5 +1,6 @@ --- title: FlexNet Publisher Floating license setup +description: Set up a FlexNet Publisher floating license server and configure end-user machines for older Arm products that do not support user-based licensing. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/dui0209 author: Ronan Synnott diff --git a/content/install-guides/license/ubl_license_admin.md b/content/install-guides/license/ubl_license_admin.md index d19e42829c..f32b2acf4f 100644 --- a/content/install-guides/license/ubl_license_admin.md +++ b/content/install-guides/license/ubl_license_admin.md @@ -1,5 +1,6 @@ --- title: UBL Local License Server (LLS) setup +description: Install and configure an Arm user-based Local License Server so administrators can host and manage commercial Arm tool licenses. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/107573 author: Ronan Synnott diff --git a/content/install-guides/license/ubl_license_enduser.md b/content/install-guides/license/ubl_license_enduser.md index cbd641cab8..18280f945e 100644 --- a/content/install-guides/license/ubl_license_enduser.md +++ b/content/install-guides/license/ubl_license_enduser.md @@ -1,5 +1,6 @@ --- title: UBL LLS End-user setup +description: Activate Arm user-based licenses from a Local License Server on an end-user machine using environment variables, tool IDEs, or manual activation. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/102516 author: Ronan Synnott diff --git a/content/install-guides/linux-migration-tools.md b/content/install-guides/linux-migration-tools.md index 4162b6d992..ff5df883db 100644 --- a/content/install-guides/linux-migration-tools.md +++ b/content/install-guides/linux-migration-tools.md @@ -1,5 +1,6 @@ --- title: Arm Linux Migration Tools +description: Install Arm Linux Migration Tools on Arm Linux to access utilities for code analysis, performance profiling, containers, and migration assessment. additional_search_terms: - migration diff --git a/content/install-guides/llvm-embedded.md b/content/install-guides/llvm-embedded.md index 540ca15693..a562536779 100644 --- a/content/install-guides/llvm-embedded.md +++ b/content/install-guides/llvm-embedded.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: LLVM Embedded Toolchain for Arm +description: Install the LLVM Embedded Toolchain for Arm on Windows, macOS, or Linux and verify clang for Cortex-M embedded development. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -182,4 +183,4 @@ telnetterminal0: Listening for serial connection on port 5001 hello Info: /OSCI/SystemC: Simulation stopped by user. ``` -You're now ready to use LLVM Embedded Toolchain for Arm. \ No newline at end of file +You're now ready to use LLVM Embedded Toolchain for Arm. diff --git a/content/install-guides/llvm-woa.md b/content/install-guides/llvm-woa.md index 2d2011986d..bea8f2d9d8 100644 --- a/content/install-guides/llvm-woa.md +++ b/content/install-guides/llvm-woa.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: LLVM toolchain for Windows on Arm +description: Install the native LLVM toolchain for Windows on Arm and verify clang so you can build software directly on Windows Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/mcuxpresso_vs.md b/content/install-guides/mcuxpresso_vs.md index 3b9b16731c..9a429af747 100644 --- a/content/install-guides/mcuxpresso_vs.md +++ b/content/install-guides/mcuxpresso_vs.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: NXP MCUXpresso for VS Code +description: Install the NXP MCUXpresso extension for Visual Studio Code and required dependencies for embedded development on supported desktop hosts. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -72,4 +73,3 @@ Select one or more packages and click `Install`. [Keil Studio for VS Code](https://www.keil.arm.com/) is also available. Refer to the [Arm Keil Studio for VS Code install guide](/install-guides/keilstudio_vs/) for more information. - diff --git a/content/install-guides/mdk.md b/content/install-guides/mdk.md index 1cc6220e28..1da22f23da 100644 --- a/content/install-guides/mdk.md +++ b/content/install-guides/mdk.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Keil μVision +description: Install Arm Keil MDK on Windows and configure licensing so you can develop and debug Cortex-M microcontroller applications with uVision. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/multipass.md b/content/install-guides/multipass.md index 46ca191408..df9ee23d01 100644 --- a/content/install-guides/multipass.md +++ b/content/install-guides/multipass.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Multipass +description: Install Multipass on Apple Silicon macOS or Arm Linux and create Ubuntu virtual machine instances for local Arm cloud-style development. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -313,4 +314,4 @@ multipass purge Purged instances are no longer recoverable. {{% /notice %}} -You're now ready to use Multipass. \ No newline at end of file +You're now ready to use Multipass. diff --git a/content/install-guides/nerdctl.md b/content/install-guides/nerdctl.md index b09ae7e11b..161168b17b 100644 --- a/content/install-guides/nerdctl.md +++ b/content/install-guides/nerdctl.md @@ -1,5 +1,6 @@ --- title: Nerdctl +description: Install containerd, nerdctl, CNI plugins, and BuildKit on Arm Linux so you can run Docker-compatible container workflows without Docker Engine. author: Jason Andrews minutes_to_complete: 10 diff --git a/content/install-guides/nomachine.md b/content/install-guides/nomachine.md index 63216d274b..7d28906dbb 100644 --- a/content/install-guides/nomachine.md +++ b/content/install-guides/nomachine.md @@ -15,6 +15,7 @@ test_images: test_link: null test_maintenance: false title: NoMachine +description: Install NoMachine and an xfce desktop on remote Arm Linux so you can connect to a graphical development environment. tool_install: true weight: 1 --- @@ -146,4 +147,4 @@ Start NoMachine on the client computer by following these steps: ![Linux xfce4 remote desktop rendered in the NoMachine client window, confirming the remote desktop session is active and ready to use#center](/install-guides/_images/nx-desktop.png "NoMachine remote desktop session") -You're now ready to use NoMachine. \ No newline at end of file +You're now ready to use NoMachine. diff --git a/content/install-guides/oc.md b/content/install-guides/oc.md index ffb324ac1f..4eaf42f0ce 100644 --- a/content/install-guides/oc.md +++ b/content/install-guides/oc.md @@ -1,5 +1,6 @@ --- title: OpenShift CLI (oc) +description: Install the OpenShift CLI on Ubuntu for Arm or Apple Silicon macOS so you can manage OpenShift and Kubernetes resources from a terminal. author: Jason Andrews diff --git a/content/install-guides/oci-cli.md b/content/install-guides/oci-cli.md index 10534159ac..ce5610725f 100644 --- a/content/install-guides/oci-cli.md +++ b/content/install-guides/oci-cli.md @@ -15,6 +15,7 @@ test_images: - ubuntu:latest test_maintenance: true title: Oracle Cloud Infrastructure (OCI) CLI +description: Install OCI CLI on Ubuntu for Arm, verify the installation, and configure access so you can manage Oracle Cloud Infrastructure resources. tool_install: true weight: 1 --- diff --git a/content/install-guides/openvscode-server.md b/content/install-guides/openvscode-server.md index efa44fba6b..a58f0e6b61 100644 --- a/content/install-guides/openvscode-server.md +++ b/content/install-guides/openvscode-server.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: OpenVSCode Server +description: Install OpenVSCode Server on Arm Linux and start a browser-accessible VS Code environment for remote or headless development. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/papi.md b/content/install-guides/papi.md index 7893255ce1..0f1f7f74fa 100644 --- a/content/install-guides/papi.md +++ b/content/install-guides/papi.md @@ -1,5 +1,6 @@ --- title: Performance API (PAPI) +description: Build and install PAPI on Arm Linux so applications can access hardware performance counters for profiling specific code sections. minutes_to_complete: 15 official_docs: https://github.com/icl-utk-edu/papi/wiki/Downloading-and-Installing-PAPI author: Jason Andrews diff --git a/content/install-guides/pdh/_index.md b/content/install-guides/pdh/_index.md index ef61540974..d42bc7f010 100644 --- a/content/install-guides/pdh/_index.md +++ b/content/install-guides/pdh/_index.md @@ -1,5 +1,6 @@ --- title: Arm Product Download Hub +description: Access Arm Product Download Hub through a browser or API so you can find and download entitled Arm IP and software product packages. author: Ronan Synnott additional_search_terms: diff --git a/content/install-guides/pdh/api.md b/content/install-guides/pdh/api.md index f4fd8c07a3..65aab1777b 100644 --- a/content/install-guides/pdh/api.md +++ b/content/install-guides/pdh/api.md @@ -1,5 +1,6 @@ --- title: Access via API +description: Install and use the Entitlements and Download Manager on Linux to automate Arm Product Download Hub authentication and package downloads. minutes_to_complete: 15 official_docs: https://anypoint.mulesoft.com/exchange/portals/arm-3/f5af04c7-2f93-4d1e-8355-a60625973e1f/product-entitlement-customer-experience-api/ author: Ronan Synnott diff --git a/content/install-guides/pdh/browser.md b/content/install-guides/pdh/browser.md index ea5fcd5577..07929bddc9 100644 --- a/content/install-guides/pdh/browser.md +++ b/content/install-guides/pdh/browser.md @@ -1,5 +1,6 @@ --- title: Access via Internet Browser +description: Search and download Arm products from Arm Product Download Hub in a browser, including entitled packages, updates, and product-code lookups. minutes_to_complete: 15 official_docs: https://developer.arm.com/documentation/107572 author: Ronan Synnott diff --git a/content/install-guides/perf.md b/content/install-guides/perf.md index a21a841f55..7490b9f8f6 100644 --- a/content/install-guides/perf.md +++ b/content/install-guides/perf.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Perf for Linux on Arm (LinuxPerf) +description: Install Linux Perf on Arm Linux with a package manager or from source so you can collect hardware and software performance data. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/performix.md b/content/install-guides/performix.md index 3d9b7c8325..027eec48a4 100644 --- a/content/install-guides/performix.md +++ b/content/install-guides/performix.md @@ -1,5 +1,6 @@ --- title: Arm Performix +description: Install Arm Performix on a desktop host and connect to remote Arm Linux targets for graphical performance profiling with hardware counters. additional_search_terms: - performix diff --git a/content/install-guides/porting-advisor.md b/content/install-guides/porting-advisor.md index 1314e21f34..6fd49e8ccd 100644 --- a/content/install-guides/porting-advisor.md +++ b/content/install-guides/porting-advisor.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Porting Advisor for Graviton +description: Install Porting Advisor for Graviton on Ubuntu or Amazon Linux 2023 and scan application source code for portability issues on AWS Graviton. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -200,4 +201,3 @@ Report generated successfully. Hint: you can use --output FILENAME.html to gener Try out the other sample projects. You are now ready to use Porting Advisor for Graviton on your own projects. - diff --git a/content/install-guides/powershell.md b/content/install-guides/powershell.md index fc92c690b3..9f262f179d 100644 --- a/content/install-guides/powershell.md +++ b/content/install-guides/powershell.md @@ -1,5 +1,6 @@ --- title: PowerShell +description: Install PowerShell on Arm Linux and verify the shell so you can run cross-platform automation commands and scripts. minutes_to_complete: 10 official_docs: https://learn.microsoft.com/en-us/powershell/ ecosystem_dashboard: https://developer.arm.com/ecosystem-dashboard/linux?package=powershell @@ -107,4 +108,4 @@ The output is similar to: ```output Hello Arm Linux world! ``` -You are now ready to use PowerShell on your Arm Linux computer. \ No newline at end of file +You are now ready to use PowerShell on your Arm Linux computer. diff --git a/content/install-guides/pulumi.md b/content/install-guides/pulumi.md index 642d24d11b..f8639129b1 100644 --- a/content/install-guides/pulumi.md +++ b/content/install-guides/pulumi.md @@ -1,5 +1,6 @@ --- title: Pulumi +description: Install Pulumi on Linux and verify the setup with a container registry example so you can deploy infrastructure as code from Arm systems. minutes_to_complete: 5 official_docs: https://www.pulumi.com/docs/ ecosystem_dashboard: https://developer.arm.com/ecosystem-dashboard/linux?package=pulumi diff --git a/content/install-guides/py-woa.md b/content/install-guides/py-woa.md index 7486127c9e..283f1c4753 100644 --- a/content/install-guides/py-woa.md +++ b/content/install-guides/py-woa.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Python for Windows on Arm +description: Install native Python on Windows on Arm, run a test program, and install packages for Python development on Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/pytorch-woa.md b/content/install-guides/pytorch-woa.md index 1b2ebf97af..3579273a1b 100644 --- a/content/install-guides/pytorch-woa.md +++ b/content/install-guides/pytorch-woa.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: PyTorch for Windows on Arm +description: Install native PyTorch for Windows on Arm and run a Python example to verify machine learning workflows on Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/pytorch.md b/content/install-guides/pytorch.md index a4179a40ca..7a226d94dc 100644 --- a/content/install-guides/pytorch.md +++ b/content/install-guides/pytorch.md @@ -16,6 +16,7 @@ test_images: test_link: null test_maintenance: false title: PyTorch +description: Install PyTorch on Arm Linux and run a starter example so you can build and test machine learning applications with Python. tool_install: true weight: 1 --- diff --git a/content/install-guides/ros2.md b/content/install-guides/ros2.md index e6583effed..1832efe6fe 100644 --- a/content/install-guides/ros2.md +++ b/content/install-guides/ros2.md @@ -1,5 +1,6 @@ --- title: ROS - Robot Operating System +description: Install ROS 2 on Ubuntu for Arm and configure dependencies so you can build and run robotics applications on Arm Linux. author: Odin Shen minutes_to_complete: 30 official_docs: https://www.ros.org/blog/getting-started/ diff --git a/content/install-guides/rust.md b/content/install-guides/rust.md index 759ba66f82..a3addb0dac 100644 --- a/content/install-guides/rust.md +++ b/content/install-guides/rust.md @@ -1,5 +1,6 @@ --- title: Rust for Linux Applications +description: Install Rust on Arm Linux and compile a sample project so you can build Linux applications with the Rust toolchain. minutes_to_complete: 10 official_docs: https://www.rust-lang.org/tools/install ecosystem_dashboard: https://developer.arm.com/ecosystem-dashboard/linux?package=rust diff --git a/content/install-guides/rust_embedded.md b/content/install-guides/rust_embedded.md index 4afc3f8402..ed34c298de 100644 --- a/content/install-guides/rust_embedded.md +++ b/content/install-guides/rust_embedded.md @@ -1,5 +1,6 @@ --- title: Rust for Embedded Applications +description: Install Rust and Arm cross-compilation support on Ubuntu so you can build embedded applications for Arm targets. minutes_to_complete: 10 official_docs: https://docs.rust-embedded.org/ author: Ronan Synnott diff --git a/content/install-guides/sbt.md b/content/install-guides/sbt.md index 0740cabb92..d0ce1b86f2 100644 --- a/content/install-guides/sbt.md +++ b/content/install-guides/sbt.md @@ -1,5 +1,6 @@ --- title: sbt +description: Install sbt on Ubuntu for Arm so you can build Scala and Java projects with the standard sbt command-line tool. author: Jason Andrews minutes_to_complete: 10 diff --git a/content/install-guides/skopeo.md b/content/install-guides/skopeo.md index dff5c2aa88..7c8e3699f8 100644 --- a/content/install-guides/skopeo.md +++ b/content/install-guides/skopeo.md @@ -1,5 +1,6 @@ --- title: Skopeo +description: Install Skopeo on Ubuntu for Arm and inspect container images so you can work with registries without a local container daemon. author: Jason Andrews minutes_to_complete: 10 official_docs: https://github.com/containers/skopeo diff --git a/content/install-guides/socrates.md b/content/install-guides/socrates.md index 5d38951884..cc4f2f8a64 100644 --- a/content/install-guides/socrates.md +++ b/content/install-guides/socrates.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Socrates +description: Install Arm Socrates from Arm Product Download Hub, configure licensing, and update the IP catalog for Arm IP selection and SoC creation. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -93,4 +94,3 @@ They are available on the [Arm YouTube channel](https://www.youtube.com/c/arm): * [Getting Started](https://youtube.com/playlist?list=PLgyFKd2HIZlY_y7b5OTtyrso45q-eCM_s) * [NIC-400 Configuration](https://youtube.com/playlist?list=PLgyFKd2HIZlaQBfd8YEMwSQX_cWIxODgG) * [NI-700 Configuration](https://youtube.com/playlist?list=PLgyFKd2HIZlahIsHSSw7ViwiFxeBYc36b) - diff --git a/content/install-guides/ssh.md b/content/install-guides/ssh.md index a4ce4b0711..ef24238f17 100644 --- a/content/install-guides/ssh.md +++ b/content/install-guides/ssh.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: SSH +description: Install and configure SSH on Arm Linux so you can securely connect to remote servers for cloud and server development. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -177,4 +178,4 @@ ssh -i -L 3000:localhost:3000 ubuntu@ Once you SSH, you can access `localhost:3000` and the traffic is forwarded to the remote computer. -Search for additional tutorials to learn more about port forwarding. \ No newline at end of file +Search for additional tutorials to learn more about port forwarding. diff --git a/content/install-guides/stm32_vs.md b/content/install-guides/stm32_vs.md index cef286b71b..0643b9869c 100644 --- a/content/install-guides/stm32_vs.md +++ b/content/install-guides/stm32_vs.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: STM32 extensions for VS Code +description: Install STM32 extensions and dependencies for Visual Studio Code so you can configure and develop STM32 projects on desktop hosts. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/streamline-cli.md b/content/install-guides/streamline-cli.md index e507955011..afae3cb909 100644 --- a/content/install-guides/streamline-cli.md +++ b/content/install-guides/streamline-cli.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Streamline CLI Tools +description: Install Streamline CLI tools on Arm Linux and prepare applications for command-line performance profiling on Arm servers. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -273,4 +274,3 @@ Follow these steps to integrate these patches into an RPM-based distribution's k ``` You are now ready to use Streamline CLI Tools. Refer to [Profiling for Neoverse with Streamline CLI Tools](/learning-paths/servers-and-cloud-computing/profiling-for-neoverse/) to get started. - diff --git a/content/install-guides/streamline.md b/content/install-guides/streamline.md index 9d26fbffd4..9cd86785f0 100644 --- a/content/install-guides/streamline.md +++ b/content/install-guides/streamline.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Streamline +description: Install Arm Streamline from Arm Performance Studio or Arm Development Studio to profile Android, Linux, or bare-metal applications. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/successkits.md b/content/install-guides/successkits.md index 41966ddf9a..4c3ecd35ac 100644 --- a/content/install-guides/successkits.md +++ b/content/install-guides/successkits.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Arm Success Kits +description: Download and install Arm Success Kit components from Arm Product Download Hub so licensed development tools are available on your workstation. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -58,4 +59,3 @@ Bundles are provided for Windows, Linux, or Mac OS. Not all components are suppo [Install Arm Socrates](/install-guides/socrates/) [Install Arm AMBA Viz](/install-guides/ambaviz/) - diff --git a/content/install-guides/swift.md b/content/install-guides/swift.md index a3d7e2fdb5..360a8def53 100644 --- a/content/install-guides/swift.md +++ b/content/install-guides/swift.md @@ -1,6 +1,7 @@ --- title: Swift +description: Install Swift on Ubuntu for Arm and verify the toolchain so you can build and run Swift applications on Arm Linux. author: Jason Andrews minutes_to_complete: 10 @@ -139,4 +140,3 @@ Hello from Swift on Arm Linux! ``` You are now ready to use the Swift programming language on your Arm Linux computer. - diff --git a/content/install-guides/sysbox.md b/content/install-guides/sysbox.md index c418511964..62f791298b 100644 --- a/content/install-guides/sysbox.md +++ b/content/install-guides/sysbox.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Sysbox +description: Install Sysbox on Arm Linux and verify Docker workloads that need system-level container behavior without running a full virtual machine. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: @@ -207,4 +208,4 @@ sudo halt Sysbox behaves like a virtual machine that you can use to run applications that require system services normally not available in containers. It is useful for testing and development tasks because the container changes are not saved, meaning that you can create a clean testing environment simply by restarting the Sysbox container. -You're now ready to use Sysbox. \ No newline at end of file +You're now ready to use Sysbox. diff --git a/content/install-guides/terraform.md b/content/install-guides/terraform.md index da0666fc87..b50f65a407 100644 --- a/content/install-guides/terraform.md +++ b/content/install-guides/terraform.md @@ -18,6 +18,7 @@ test_images: test_link: false test_maintenance: true title: Terraform +description: Install Terraform on Ubuntu for Arm or Apple Silicon macOS and verify the CLI so you can manage cloud infrastructure as code. tool_install: true weight: 1 --- diff --git a/content/install-guides/tkn.md b/content/install-guides/tkn.md index c9420ff7e9..bb96a74b28 100644 --- a/content/install-guides/tkn.md +++ b/content/install-guides/tkn.md @@ -1,5 +1,6 @@ --- title: Tekton CLI (tkn) +description: Install Tekton CLI on Ubuntu for Arm or Apple Silicon macOS so you can create and manage Tekton Pipelines resources from a terminal. author: Jason Andrews official_docs: https://tekton.dev/docs/cli/ diff --git a/content/install-guides/topdown-tool.md b/content/install-guides/topdown-tool.md index 98a4cd5323..c562be51ce 100644 --- a/content/install-guides/topdown-tool.md +++ b/content/install-guides/topdown-tool.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Telemetry Solution (Topdown Methodology) +description: Install the Arm Telemetry Solution on Arm Linux and test top-down performance methodology tools that work with Linux Perf. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/vnc.md b/content/install-guides/vnc.md index b16479a920..3b00079065 100644 --- a/content/install-guides/vnc.md +++ b/content/install-guides/vnc.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: VNC on Arm Linux +description: Install and configure VNC with an xfce desktop on Arm Linux so you can connect to a remote graphical development environment. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/vs-woa.md b/content/install-guides/vs-woa.md index 4510fae878..a50b7be794 100644 --- a/content/install-guides/vs-woa.md +++ b/content/install-guides/vs-woa.md @@ -1,5 +1,6 @@ --- -title: Visual Studio for Windows on Arm +title: Visual Studio for Windows on Arm +description: Install Visual Studio on Windows on Arm with C, C++, and LLVM support so you can develop applications directly on Arm hardware. additional_search_terms: - clang diff --git a/content/install-guides/vscode-tunnels.md b/content/install-guides/vscode-tunnels.md index ec65f5eef3..bf23153813 100644 --- a/content/install-guides/vscode-tunnels.md +++ b/content/install-guides/vscode-tunnels.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: VS Code Tunnels +description: Install the VS Code CLI on Arm systems and configure Remote Tunnels for browser-based access to non-desktop Arm development environments. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/windows-perf-vs-extension.md b/content/install-guides/windows-perf-vs-extension.md index c3d1296aa6..5530a699ed 100644 --- a/content/install-guides/windows-perf-vs-extension.md +++ b/content/install-guides/windows-perf-vs-extension.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Visual Studio Extension for WindowsPerf +description: Install the WindowsPerf Visual Studio extension on Windows on Arm so you can capture and visualize performance data inside Visual Studio. minutes_to_complete: 10 diff --git a/content/install-guides/windows-perf-wpa-plugin.md b/content/install-guides/windows-perf-wpa-plugin.md index 584abcce17..b05a085429 100644 --- a/content/install-guides/windows-perf-wpa-plugin.md +++ b/content/install-guides/windows-perf-wpa-plugin.md @@ -1,5 +1,6 @@ --- title: Windows Performance Analyzer (WPA) plugin +description: Install the WindowsPerf WPA plugin on Windows on Arm so Windows Performance Analyzer can display WindowsPerf telemetry and timeline data. minutes_to_complete: 15 diff --git a/content/install-guides/windows-sandbox-woa.md b/content/install-guides/windows-sandbox-woa.md index e7336ea5c9..33c81fc2e3 100644 --- a/content/install-guides/windows-sandbox-woa.md +++ b/content/install-guides/windows-sandbox-woa.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: Windows Sandbox for Windows on Arm +description: Enable and install Windows Sandbox on Windows on Arm so you can run isolated desktop test environments on supported Arm devices. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/install-guides/wperf.md b/content/install-guides/wperf.md index b5d24753db..5f7fcb1959 100644 --- a/content/install-guides/wperf.md +++ b/content/install-guides/wperf.md @@ -2,6 +2,7 @@ ### Title the install tools article with the name of the tool to be installed ### Include vendor name where appropriate title: WindowsPerf (wperf) +description: Install WindowsPerf on Windows on Arm and verify PMU-based profiling so you can analyze application performance with command-line and IDE tools. ### Optional additional search terms (one per line) to assist in finding the article additional_search_terms: diff --git a/content/learning-paths/automotive/_index.md b/content/learning-paths/automotive/_index.md index 4acb578a94..3fa9776e04 100644 --- a/content/learning-paths/automotive/_index.md +++ b/content/learning-paths/automotive/_index.md @@ -30,9 +30,11 @@ tools_software_languages_filter: - Clang: 3 - CPP: 1 - DDS: 1 -- Docker: 2 +- Docker: 3 - FVP: 1 - GCC: 3 +- Git: 1 +- Multipass: 1 - Perf: 1 - Python: 2 - Raspberry Pi: 1 @@ -41,6 +43,7 @@ tools_software_languages_filter: - SME2: 1 - Tinkerblox: 1 - topdown-tool: 1 +- Yocto: 1 - Zenoh: 1 # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit @@ -65,7 +68,4 @@ tools_software_languages_filter: # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit --- diff --git a/content/learning-paths/automotive/openadkit1_container/_index.md b/content/learning-paths/automotive/openadkit1_container/_index.md index dd2af119e6..65e4e6ccc5 100644 --- a/content/learning-paths/automotive/openadkit1_container/_index.md +++ b/content/learning-paths/automotive/openadkit1_container/_index.md @@ -15,9 +15,50 @@ prerequisites: - An Arm Neoverse cloud instance, or a local Arm Neoverse Linux computer with at least 16 CPUs and 32GB of RAM - Familiarity with Docker and Docker Compose +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-24T15:35:34Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 37913b2c4aed914d32dbdad054ebdd2b1d4587da3ede1a33ba81e3e68bf504a3 + summary_generated_at: '2026-06-24T15:35:34Z' + summary_source_hash: 37913b2c4aed914d32dbdad054ebdd2b1d4587da3ede1a33ba81e3e68bf504a3 + faq_generated_at: '2026-06-24T15:35:34Z' + faq_source_hash: 37913b2c4aed914d32dbdad054ebdd2b1d4587da3ede1a33ba81e3e68bf504a3 + summary: >- + You'll deploy a containerized Autoware + Open AD Kit simulation on Arm Neoverse using Docker and Docker Compose, within a SOAFEE-aligned Shift-Left workflow. First, you'll learn about software-defined vehicles (SDVs), SOAFEE, ROS 2, and the Open AD Kit components used in the demo. Then, you'll prepare an Arm Neoverse Linux system and use Docker Compose to start the Open AD Kit visualizer, planning, and simulation services. By the end, you'll review a running simulation. The workflow has been tested on both cloud (Amazon EC2) and on-premise Arm Neoverse platforms. + faqs: + - question: What result should I expect after launching the Docker Compose stack? + answer: >- + The visualizer service starts in detached mode, followed by continuously running planning + and simulation services. Active containers for these components indicate the demo is operating + as intended. + - question: Where are the ROS 2 commands and service configurations defined? + answer: >- + They are defined in the docker/docker-compose.yml file. Reviewing that file shows the launch + order, container settings, and ROS 2 commands used by the demo. + - question: Can I run the same workflow on cloud and on-prem Arm Neoverse systems? + answer: >- + Yes. The workflow has been tested on Amazon EC2 and an Ampere Altra workstation, so you can + choose either a cloud instance or an on-premise Arm Neoverse system. + - question: What should I check before starting the demo to avoid resource-related failures? + answer: >- + Verify the Arm Neoverse system provides at least 16 CPUs and 32 GB of RAM. Ensure Docker + and Docker Compose are installed and available. + - question: If I stop and restart the demo, do I need to reconfigure anything? + answer: >- + No. Docker Compose allows you to start with the previous session’s settings without modifications, + so the configuration persists between runs. +# END generated_summary_faq + author: Odin Shen -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false diff --git a/content/learning-paths/automotive/openadkit2_safetyisolation/_index.md b/content/learning-paths/automotive/openadkit2_safetyisolation/_index.md index 0bbae6a5c4..3bfb072554 100644 --- a/content/learning-paths/automotive/openadkit2_safetyisolation/_index.md +++ b/content/learning-paths/automotive/openadkit2_safetyisolation/_index.md @@ -16,11 +16,66 @@ prerequisites: - Completion of the [Deploy Open AD Kit containerized autonomous driving simulation on Arm Neoverse](/learning-paths/automotive/openadkit1_container/) Learning Path - Basic familiarity with Docker +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-24T15:35:59Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 92a6dac2b1674a44cd623a0c8c3189b38438124a6067ed7ca776999ff1d8b5bf + summary_generated_at: '2026-06-24T15:35:59Z' + summary_source_hash: 92a6dac2b1674a44cd623a0c8c3189b38438124a6067ed7ca776999ff1d8b5bf + faq_generated_at: '2026-06-24T15:35:59Z' + faq_source_hash: 92a6dac2b1674a44cd623a0c8c3189b38438124a6067ed7ca776999ff1d8b5bf + summary: >- + You'll learn about prototyping safety‑critical isolation for autonomous + driving workloads on Arm Neoverse by applying functional safety concepts, ISO 26262 and ASIL + guidance, and a safety‑island architecture. First, you'll understand how to separate safety‑critical control + logic from non‑safety functions. Then, you'll connect components using a publish‑subscribe model (DDS/ROS + 2) within containerized deployments or across Arm‑based instances. You'll explore lifecycle + practices aligned with the V‑model, including clear requirements, version control, impact + analysis, and regression testing. By the end, you'll organize simulation components into + isolated units with defined interfaces and documentation suitable for advancing ISO 26262‑oriented + development on Arm Neoverse. + faqs: + - question: How do I decide which components belong on the safety island versus the general + ECU? + answer: >- + Place time‑critical, safety‑relevant control logic (for example, braking or steering) on + the safety island, and keep non‑critical features (such as infotainment) on the general + ECU. The goal is strong isolation, determinism, and minimized coupling for safety‑critical + paths. + - question: What should I verify to confirm the isolation boundaries are defined correctly? + answer: >- + Check that safety‑critical components run independently from non‑critical services and communicate + only through defined publish‑subscribe interfaces. Ensure data exchanged is minimal and + purpose‑specific so that safety logic is not impacted by unrelated functions. + - question: How do ISO 26262 ASIL levels influence my development workflow in this prototype? + answer: >- + Higher ASIL targets require more rigorous processes and evidence across the V‑model. For + example, ASIL‑D changes go through full impact analysis and regression testing to prevent + introducing new risks. + - question: Should I separate components using containers on one host or across multiple Arm + Neoverse instances? + answer: >- + Both approaches support prototyping: containers model software isolation on one system, + while multiple instances model stronger physical separation. Choose the option that best + matches the isolation assumptions you want to evaluate. + - question: What artifacts should I capture to support ISO 26262 traceability in this prototype? + answer: >- + Maintain clear safety requirements, rationale for the safety‑island split, defined DDS/ROS + 2 interfaces, and mapped tests to requirements. Record versioned changes, impact analyses, + and verification results aligned to the V‑model stages. +# END generated_summary_faq + author: - Odin Shen - Julien Jayat -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false diff --git a/content/learning-paths/automotive/system76-auto/_index.md b/content/learning-paths/automotive/system76-auto/_index.md index 6985d98f30..e6cffd4b3d 100644 --- a/content/learning-paths/automotive/system76-auto/_index.md +++ b/content/learning-paths/automotive/system76-auto/_index.md @@ -12,11 +12,54 @@ learning_objectives: - Build and run the Arm Automotive Solutions Software Reference Stack locally. prerequisites: - - A System76 Thelio Astra desktop computer running Ubuntu 24.04. + - A System76 Thelio Astra desktop computer running Ubuntu 24.04. + +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-24T15:36:29Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 2b758d2dcf28a683ab164e28578a736d6d730b81dfbc01a6765619052fcdebd0 + summary_generated_at: '2026-06-24T15:36:29Z' + summary_source_hash: 2b758d2dcf28a683ab164e28578a736d6d730b81dfbc01a6765619052fcdebd0 + faq_generated_at: '2026-06-24T15:36:29Z' + faq_source_hash: 2b758d2dcf28a683ab164e28578a736d6d730b81dfbc01a6765619052fcdebd0 + summary: >- + You'll use a System76 Thelio Astra Arm desktop to build and run the + Arm Automotive Solutions Software Reference Stack in a local Multipass virtual machine. You'll start by + creating an Ubuntu 20.04 guest, isolating builds, and compiling Yocto-based + components targeting a Fixed Virtual Platform that models the Arm Reference Design-1 AE. You'll review the Thelio Astra platform and the software stack context, then run a Parsec-enabled TLS demo that establishes an HTTPS session to transfer a web page. + faqs: + - question: Which Multipass install guide should I follow before creating the virtual machine? + answer: >- + Use the Multipass install guide for Arm Linux before starting the steps. This ensures Multipass + is set up correctly on the Thelio Astra running Ubuntu. + - question: Which Ubuntu release runs inside the Multipass virtual machine for this build? + answer: >- + The build is performed from the command line of an Ubuntu 20.04 Multipass virtual machine. + - question: Why use a Multipass virtual machine on the Thelio Astra instead of building directly on the host? + answer: >- + A Multipass VM creates an isolated automotive development environment and lets you split + the resources of the Thelio Astra between development tasks. It keeps the build and test + process contained. + - question: What target platform is used when running the software stack examples? + answer: >- + The examples run on a Fixed Virtual Platform that models the Arm Reference Design‑1 AE (RD‑1 + AE) hardware system. + - question: What result should I expect from the Parsec-enabled TLS demo? + answer: >- + The demo establishes an HTTPS session and transfers a simple web page over a TLS connection. + Parsec provides the common API to the underlying security and cryptographic services used + by the demo. +# END generated_summary_faq author: Jason Andrews -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false diff --git a/content/learning-paths/automotive/zenacssdebug/_index.md b/content/learning-paths/automotive/zenacssdebug/_index.md index 84d35f8ca3..745a3f8ca0 100644 --- a/content/learning-paths/automotive/zenacssdebug/_index.md +++ b/content/learning-paths/automotive/zenacssdebug/_index.md @@ -18,9 +18,54 @@ prerequisites: - Arm Development Studio 2024.1 or later with a valid license - for support see the [Install Guide for Arm DS](/install-guides/armds/) - Basic understanding of the Arm Zena CSS software stack, Armv8-A/Armv9-A cores, and Linux +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-24T15:37:11Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 74740788edbfe7ea09bf955455b4aeaed00e667fa8c9d68467353c1f64528b08 + summary_generated_at: '2026-06-24T15:37:11Z' + summary_source_hash: 74740788edbfe7ea09bf955455b4aeaed00e667fa8c9d68467353c1f64528b08 + faq_generated_at: '2026-06-24T15:37:11Z' + faq_source_hash: 74740788edbfe7ea09bf955455b4aeaed00e667fa8c9d68467353c1f64528b08 + summary: >- + You'll debug the Arm Zena Compute Subsystem (CSS) reference + software stack on a Fixed Virtual Platform using Arm Development Studio. First, you'll launch the + FVP with the Iris debug server enabled, then create and save a custom Arm DS configuration. You'll establish connections + to each heterogeneous component within Zena CSS to debug the Linux kernel and user processes. By the end, you'll create reusable `.launch` + files, step through early RSE boot, and attach to Safety Island and Linux targets to inspect + execution across the system. + faqs: + - question: Which FVP launch method should I use for debugging? + answer: >- + Use the launch invocation that enables the Iris debug server. The default build-environment + command runs the stack but does not enable Iris, so Arm Development Studio cannot connect. + - question: How should I organize and save my debug connections in Arm Development Studio? + answer: >- + Create a General Project to store the connection files and save each connection as a `.launch` + file. This makes it easy to reuse and enhance configurations for each subsystem. + - question: What is the expected workflow to debug the RSE from reset? + answer: >- + Start the FVP with Iris enabled and hold the model at reset, then connect from Arm Development + Studio. Load Trusted Firmware‑M symbols and step through the early boot code. + - question: Can I connect to all Zena CSS processors at the same time? + answer: >- + Yes. Arm Development Studio supports heterogeneous systems, so you can connect to the RSE, + Safety Island, and primary compute cores simultaneously, though you might prefer to set up + one connection fully before adding others. + - question: Why isn’t there a predefined Zena CSS target in Arm Development Studio? + answer: >- + As of Arm Development Studio 2025.0, there is no out-of-the-box configuration for the Zena + CSS FVP. Create one using the Iris interface as shown in the Learning Path. +# END generated_summary_faq + author: Ronan Synnott -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/build-the-template.md b/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/build-the-template.md deleted file mode 100644 index b2c662e0ce..0000000000 --- a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/build-the-template.md +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Build the Topo Template from scratch -weight: 4 - -### FIXED, DO NOT MODIFY -layout: learningpathall ---- - -## Start from the application pieces - -The `topo-imx93-npu-deployment` repository is a Compose project with Topo metadata at the root. The Topo-specific part is not a replacement for Compose. The services still describe container builds, dependencies, ports, volumes, and runtime settings. The `x-topo` block adds the metadata Topo uses to identify the Template, check target requirements, and prompt for configuration. - -The project has three implementation areas: - -- `executorch-runner/`: builds the ExecuTorch `.pte` program and the Cortex-M33 firmware ELF. -- `webapp/`: builds the Flask application that stages memory and sends `RUN` commands over `RPMsg`. -- `compose.yaml`: connects the build artifacts, runtime services, Remoteproc Runtime settings, and Topo metadata. - -When bootstrapping this Template from scratch, first make the project work as a normal Compose build. Then add the `x-topo` metadata that lets Topo deploy it consistently to an Arm64 target. - -## Install the Topo Template authoring skills - -The [Topo Template Format](https://github.com/arm/Topo-Template-Format) repository includes public authoring skills for agents that support skill installation: - -- `topo-template-context`: provides Topo and Topo Template reference context for `x-topo` metadata, schema, docs, and CLI Template behavior. -- `topo-template-bootstrap`: converts a Compose repository into a Topo Template by adding or improving `compose.yaml` and `x-topo` metadata. -- `topo-template-lint`: reviews a Topo Template for schema correctness, metadata consistency, deployment success messages, and build argument wiring. - -Install the skills with `npx skills`: - -```bash -npx skills add arm/topo-template-format -``` - -If your agent does not use `npx skills`, clone the Template Format repository and manually copy or symlink the directories under `skills/` into your agent's skills directory: - -```bash -git clone https://github.com/arm/Topo-Template-Format.git -``` - -Restart your agent after installing or updating the skills. - -You can then use the skills as part of the Template authoring flow. From the root of any Compose project, ask your agent to use `topo-template-bootstrap`: - -```output -Use topo-template-bootstrap on this repository. -Treat the root compose.yaml as the Template root. -Preserve plain docker compose behavior. -Add x-topo metadata only where it reflects the actual services, hardware requirements, and build arguments. -``` - -After bootstrap, ask the agent to use `topo-template-lint`: - -```output -Use topo-template-lint on topo-imx93-npu-deployment. -Validate compose.yaml against the Topo Template Format schema. -Check README alignment, deployment_success_message, Remoteproc Runtime metadata, and x-topo.args wiring. -``` - -The lint pass should confirm that the Template has a root-level `x-topo.name`, that non-remoteproc services use `platform: linux/arm64`, that `cm33-runner` uses the Remoteproc Runtime annotation, and that every `x-topo.args` entry is carried into Compose or Docker build arguments where appropriate. - -## Create the runner build pipeline - -The `executorch-runner/Dockerfile` is a multi-stage Dockerfile. It builds two artifacts from one build context: - -- `mv2_ethosu65_256.pte`: the MobileNetV2 ExecuTorch program lowered for `ethos-u65-256`. -- `executorch_runner_cm33.elf`: the Cortex-M33 firmware image loaded by Linux `remoteproc`. - -The first half of the Dockerfile builds the model artifact: - -```Dockerfile -FROM build-base AS executorch-base -... -FROM executorch-base AS pte-builder -... -RUN source /workspace/executorch/examples/arm/arm-scratch/setup_path.sh && \ - python /usr/local/bin/export_mv2_imx93.py - -FROM busybox:1.36 AS pte-artifacts -COPY --from=pte-builder /workspace/build/mv2-imx93/mv2_ethosu65_256.pte /artifacts/mv2_ethosu65_256.pte -``` - -The second half builds and packages the firmware: - -```Dockerfile -FROM build-base AS runner-base -ARG MCUXSDK_MANIFEST_URL=https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git -ARG MCUXSDK_MANIFEST_REV=v25.09.00 -... -FROM runner-base AS runner-builder -RUN /usr/local/bin/build-runner.sh /artifacts - -FROM scratch AS runner-runtime -COPY --from=runner-builder /artifacts/executorch_runner_cm33.elf /executorch_runner_cm33.elf -ENTRYPOINT ["/executorch_runner_cm33.elf"] -``` - -The `runner-runtime` stage is intentionally a `scratch` image. The only payload is the ELF file. When the service starts with `runtime: io.containerd.remoteproc.v1`, containerd uses Remoteproc Runtime instead of a normal Linux process runtime. Remoteproc Runtime passes the ELF entrypoint to the Linux `remoteproc` driver, and the `imx-rproc` driver loads and releases the Cortex-M33. - -The project also applies patches before building the runner. One patch changes the MCUX SDK RAM linker and startup behavior so initialized data is loaded in-place by `remoteproc` rather than copied from a flash-style load address. The runner patches add RPMsg stability fixes and trace output used by the web application. - -## Add artifact-only Compose services - -At the root of the Template, create normal Compose services for the build outputs: - -```yaml -services: - pte-artifacts: - platform: linux/arm64 - scale: 0 - build: - context: executorch-runner - dockerfile: Dockerfile - target: pte-artifacts - - runner-artifacts: - platform: linux/arm64 - scale: 0 - build: - context: executorch-runner - dockerfile: Dockerfile - target: runner-artifacts -``` - -These services are not runtime application containers. `scale: 0` keeps them out of the running deployment while still making their build targets available to the rest of the Compose project. - -The web application imports the PTE artifact as a BuildKit additional context: - -```yaml -services: - webapp: - platform: linux/arm64 - build: - context: . - dockerfile: Dockerfile - additional_contexts: - pte_artifacts: service:pte-artifacts -``` - -The webapp Dockerfile then copies from that context: - -```Dockerfile -COPY --from=pte_artifacts /artifacts/mv2_ethosu65_256.pte /opt/mv2-imx93/mv2_ethosu65_256.pte -``` - -This keeps the model export pipeline separate from the Flask app while still producing one deployable webapp image. - -## Add the remote processor service - -The Cortex-M33 firmware is represented as another Compose service: - -```yaml -services: - cm33-runner: - platform: linux/arm64 - build: - context: executorch-runner - dockerfile: Dockerfile - target: runner-runtime - runtime: io.containerd.remoteproc.v1 - annotations: - remoteproc.name: imx-rproc -``` - -This is the key heterogeneous deployment hook. The service is still built by Docker, but it is not launched as a Linux userspace process. The `runtime` selects the containerd Remoteproc Runtime shim, and `remoteproc.name: imx-rproc` selects the i.MX 93 remote processor driver. - -After this service starts, Linux exposes the RPMsg device used by the Cortex-A web app. The Flask code waits for `/dev/ttyRPMSG*`, writes the `.pte` file to `0xC0000000`, writes the input tensor to `0xC036D000`, sends `RUN\n` over RPMsg, and parses the `CM33:` response lines into top-1 and top-5 ImageNet results. - -## Add the web application service - -The web application service extends `webapp/compose.yaml` from the root Compose file: - -```yaml -services: - webapp: - platform: linux/arm64 - extends: - file: webapp/compose.yaml - service: webapp - depends_on: - - cm33-runner -``` - -The extended service is privileged and mounts `/sys` and `/dev`: - -```yaml -services: - webapp: - privileged: true - ports: - - "${WEBAPP_PORT:-3001}:3000" - volumes: - - /sys:/sys - - /dev:/dev -``` - -Those mounts are required because the app checks `/proc/device-tree`, reads remoteproc state through `/sys/class/remoteproc`, talks to `/dev/ttyRPMSG*`, writes model and tensor data through `/dev/mem`, and checks for `/dev/ethosu0`. - -## Add Topo metadata - -After the Compose services are in place, add the root-level `x-topo` block: - -```yaml -x-topo: - name: "i.MX93 ExecuTorch runner" - description: "Runs a Cortex-A web application that sends image inference commands to a resident CM33 ExecuTorch runner over RPMsg." - features: - - "remoteproc-runtime" -``` - -Keep `x-topo` at the root of `compose.yaml`, not under `services`. The `features` entry is what tells Topo this Template needs a target with Remoteproc Runtime support. That is why `topo health` checks for: - -```output -Remoteproc Runtime: ✅ (remoteproc-runtime) -Remoteproc Shim: ✅ (containerd-shim-remoteproc-v1) -Subsystem Driver (remoteproc): ✅ (imx-rproc) -``` - -You can also add a deployment success message so users know exactly what to do after deployment: - -```yaml -x-topo: - deployment_success_message: | - The i.MX93 ExecuTorch runner is deployed. - Open http://:3001 and classify an ImageNet image. -``` - -## Expose project configuration - -Topo arguments are metadata for project parameters. Compose still carries the values into the build. - -The current Template exposes optional cache image parameters: - -```yaml -x-topo: - args: - EXECUTORCH_BASE_CACHE_IMAGE: - description: Optional GHCR image used as a BuildKit cache source for the ExecuTorch PTE build. - required: false - default: ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04 - IMX93_RUNNER_BUILD_CACHE_IMAGE: - description: Optional GHCR image used as a BuildKit cache source for the CM33 runner build. - required: false - default: ghcr.io/arm-examples/topo-imx93-npu-deployment/imx93-runner-build:mcux-v25.09.00-armgcc14.2-ubuntu24.04 -``` - -Those values are used by Compose interpolation in `build.cache_from`: - -```yaml -cache_from: - - ${EXECUTORCH_BASE_CACHE_IMAGE:-ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04} -``` - -For build-time configuration, wire Topo arguments into standard Compose `build.args`. The runner Dockerfile already declares project-specific arguments for the MCUX SDK manifest: - -```Dockerfile -ARG MCUXSDK_MANIFEST_URL=https://github.com/nxp-mcuxpresso/mcuxsdk-manifests.git -ARG MCUXSDK_MANIFEST_REV=v25.09.00 -``` - -To expose the SDK revision through Topo, add matching Compose build args to the services that build `runner-base` descendants: - -```yaml -services: - runner-artifacts: - build: - args: - MCUXSDK_MANIFEST_REV: ${MCUXSDK_MANIFEST_REV:-v25.09.00} - - cm33-runner: - build: - args: - MCUXSDK_MANIFEST_REV: ${MCUXSDK_MANIFEST_REV:-v25.09.00} - -x-topo: - args: - MCUXSDK_MANIFEST_REV: - description: MCUX SDK manifest revision used to build the Cortex-M33 runner. - required: false - default: v25.09.00 -``` - -With that wiring, Topo can prompt for the value when the Template is cloned or extended, Compose passes the value into Docker BuildKit, and the Dockerfile consumes it through `ARG MCUXSDK_MANIFEST_REV`. - -Use this only for configuration that should be chosen at Template setup time. Runtime-only settings, such as `WEBAPP_PORT`, should remain normal Compose environment interpolation unless you intentionally want Topo to collect them as build-time parameters. - -## Lint the Template - -Before publishing the Template, validate the root Compose file: - -```bash -check-jsonschema \ - --schemafile ../topo-template-format/schema/topo-template-format.json \ - compose.yaml -``` - -Then review the Template the same way Topo Template linting does: - -- The Template root contains `compose.yaml`. -- `compose.yaml` contains a root-level `x-topo.name`. -- Non-remoteproc services set `platform: linux/arm64`. -- The `cm33-runner` service uses `runtime: io.containerd.remoteproc.v1` and `remoteproc.name: imx-rproc`. -- `x-topo.description` matches the README and the actual Cortex-A to Cortex-M33 RPMsg flow. -- `x-topo.features` includes `remoteproc-runtime`. -- `x-topo.args` entries are either consumed through Compose interpolation, such as the cache image values, or wired into `services..build.args` and declared as Dockerfile `ARG` instructions. -- `deployment_success_message` tells the user to open the web app on the configured target port. - -## What you've accomplished - -You now understand how the `topo-imx93-npu-deployment` Template is built from ordinary Compose services plus Topo metadata: artifact-only build stages produce the model and firmware, Remoteproc Runtime starts the Cortex-M33 ELF, RPMsg connects the processors at runtime, and `x-topo.args` provides a path for setup-time configuration without replacing Docker or Compose. diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/overview.md b/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/overview.md deleted file mode 100644 index 1baa3282ca..0000000000 --- a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/overview.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Deploy ExecuTorch firmware on NXP FRDM i.MX 93 for Ethos-U65 acceleration using Topo -weight: 2 - -### FIXED, DO NOT MODIFY -layout: learningpathall ---- - -## Get started - -Before getting started, complete the Learning Path [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) to learn how to install Topo, run host and target health checks, inspect a target, list compatible Templates, and deploy a containerized workload. - -For more background on the underlying NPU example, read [Deploy ExecuTorch firmware on NXP FRDM i.MX 93 for Ethos-U65 acceleration](/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/). You do not need to complete that Learning Path before using this one, but it helps explain the model, firmware, and [Ethos-U65](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u65) execution flow. - -## What is Topo? - -[Topo](https://github.com/arm/topo) is an open-source command-line tool developed by Arm used to deploy projects to an Arm-based Linux target over SSH. Topo builds container images on the host, transfers them to the target, and starts the services on the target. Topo can also build and deploy directly on the target. - -## What you'll learn - -In this Learning Path, you will deploy the [topo-imx93-npu-deployment](https://github.com/Arm-Examples/topo-imx93-npu-deployment) Topo Template to an NXP FRDM i.MX 93 board. - -The Template builds and deploys a browser-based MobileNetV2 image classifier. The user interface runs on the Cortex-A Linux side of the SoC. The inference runner is packaged as Cortex-M33 firmware and is started by [remoteproc-runtime](https://github.com/arm/remoteproc-runtime). The model is exported to an [ExecuTorch](https://docs.pytorch.org/executorch/stable/index.html) `.pte` [file](https://docs.pytorch.org/executorch/stable/pte-file-format.html) for Ethos-U65 NPU acceleration. - -### What does deploying the topo-imx93-npu-deployment Template do? - -Deploying the Template starts two runtime services on the target: - -- `webapp`: Web application running on the Cortex-A Linux host. It receives an image to run a classification on. -- `cm33-runner`: Cortex-M33 firmware, receives the image to classify from the web application and runs the classification Machine Learning model on it. - -When you select an image in the browser and click **Classify**, the web application: - -1. Resizes and normalizes the image to classify into an input tensor compatible with the [MobileNetV2](https://arxiv.org/abs/1801.04381) model. -2. Writes the ExecuTorch program and input tensor into reserved physical memory. -3. Sends a `RUN` command to the Cortex-M33 runner over `RPMsg`. -4. Waits for the Cortex-M33 firmware to run inference using Ethos-U65 acceleration. -5. Displays the top-1 and top-5 ImageNet classification results in the browser. - -## System Architecture - -The deployed application spans three processing domains on the i.MX 93: - -- **Cortex-A Linux host**: runs Docker, Topo-deployed containers, the Flask web app, and the Linux `remoteproc` and `RPMsg` interfaces. -- **Cortex-M33 firmware domain**: runs the ExecuTorch runner firmware loaded by `remoteproc-runtime`. -- **Ethos-U65 NPU**: accelerates delegated neural network operators from the ExecuTorch MobileNetV2 program. - -The high-level data flow is: - -```output -Browser - | - v -Flask web application on Cortex-A Linux - | - | writes .pte and input tensor to reserved memory - | sends RUN over RPMsg - v -Cortex-M33 ExecuTorch runner firmware - | - | delegates supported operators - v -Ethos-U65 NPU - | - v -Cortex-M33 returns classification results over RPMsg - | - v -Browser displays ImageNet top-1 and top-5 results -``` - -## What you've accomplished and what's next - -You now understand what the Topo Template deploys and how the Cortex-A, Cortex-M33, and Ethos-U65 parts work together. Next, you will prepare the i.MX 93 target and deploy the Template with Topo. diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.webp b/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.webp deleted file mode 100644 index 2393184074..0000000000 Binary files a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.webp and /dev/null differ diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md b/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md deleted file mode 100644 index 0ffefc32f7..0000000000 --- a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Understand the toolchains -weight: 5 - -### FIXED, DO NOT MODIFY -layout: learningpathall ---- - -## Understand the build and runtime pieces - -The `topo-imx93-npu-deployment` Template combines several toolchains. Topo hides much of the deployment plumbing, but it is useful to understand what is being built and where each component runs. - -## ExecuTorch - -[ExecuTorch](https://docs.pytorch.org/executorch/stable/index.html) is the PyTorch Edge runtime for deploying PyTorch models to edge devices, using any acceleration hardware that is available on the target device. In this Template, ExecuTorch is used in two places: - -- At build time, the Template exports a MobileNetV2 model to an ExecuTorch `.pte` program. -- At run time, the Cortex-M33 firmware loads and executes that `.pte` program. - -The export pipeline uses the ExecuTorch Arm backend and targets `ethos-u65-256`. The model is quantized and lowered so supported neural network operators can be delegated to the Ethos-U65 NPU. The generated file is: - -```output -mv2_ethosu65_256.pte -``` - -The web application includes this `.pte` file in its container image. During inference, it writes the file into the reserved physical memory range starting at `0xC0000000`, where the Cortex-M33 runner can read it. - -## Cortex-M33 firmware runner - -The firmware runner is built as: - -```output -executorch_runner_cm33.elf -``` - -This firmware runs on the Cortex-M33 core. It waits for commands coming from the Linux web application over `RPMsg`, reads the input image tensors from reserved memory, executes inference through ExecuTorch, and writes classification output back over `RPMsg`. - -The Template packages the firmware as the entrypoint of the `cm33-runner` image: - -```yaml -cm33-runner: - runtime: io.containerd.remoteproc.v1 - annotations: - remoteproc.name: imx-rproc -``` - -The `runtime: io.containerd.remoteproc.v1` setting tells containerd to use the remote processor runtime instead of the normal Linux container runtime. The `remoteproc.name` annotation identifies the target remote processor driver, `imx-rproc`. - -## remoteproc-runtime - -Linux includes a `remoteproc` framework for loading and controlling auxiliary processors such as the Cortex-M33 on the i.MX 93. `remoteproc-runtime` adds an Open Container Initiative interface on top of this framework, allowing firmware to be packaged and launched using container tooling. - -Topo uses `remoteproc-runtime` when deploying the `cm33-runner` service. The deployment flow is: - -1. Topo builds the `runner-runtime` image containing `executorch_runner_cm33.elf`. -2. Topo starts the image on the target. -3. containerd uses `io.containerd.remoteproc.v1`. -4. `remoteproc-runtime` passes the ELF file to the Linux `remoteproc` driver. -5. The kernel loads the ELF segments and releases the Cortex-M33. - -This is why the target must pass the `Remoteproc Runtime`, `Remoteproc Shim`, and `Subsystem Driver (remoteproc)` checks in `topo health`. - -## RPMsg - -`RPMsg` is the communication channel between the Cortex-A Linux application and the Cortex-M33 firmware. The web application sends a `RUN` command over a `/dev/ttyRPMSG*` device. The firmware replies with status and classification output. - -If the deployment succeeds but classification times out, inspect the web app's board checks and the target's `RPMsg` devices. The application expects an `RPMsg` TTY to appear after the Cortex-M33 firmware starts. - -## Shared reserved memory - -The web application and firmware exchange model and input data through reserved physical memory. The Template expects the target device tree to reserve: - -- `model@c0000000`: 4 MiB for the ExecuTorch `.pte` file and input tensor. -- `ethosu_region@A8000000`: 128 MiB for Ethos-U65 use. - -The web application checks these ranges at startup through `/proc/device-tree`. It also checks for `/dev/mem`, `/dev/ethosu0`, the `imx-rproc` remote processor, the `.pte` file, and ImageNet labels. - -## Web application - -The `webapp` service is a Python Flask application. It serves the browser UI, preprocesses selected images, stages memory for the images sent to the Cortex-M33 runner, sends inference commands over `RPMsg`, and renders the ImageNet top-1 and top-5 results. - -By default, the service maps target port `3001` to container port `3000`. - -## What you've accomplished - -You now understand the major toolchains and runtime interfaces used by the Template: ExecuTorch, the Cortex-M33 firmware runner, remoteproc-runtime, RPMsg, reserved memory, and the Flask web application. diff --git a/content/learning-paths/embedded-and-microcontrollers/_index.md b/content/learning-paths/embedded-and-microcontrollers/_index.md index 6783d9efba..c75d57e46e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/_index.md +++ b/content/learning-paths/embedded-and-microcontrollers/_index.md @@ -15,19 +15,19 @@ pinned_learning_paths: operatingsystems_filter: - Android: 1 - Baremetal: 30 -- Linux: 39 -- macOS: 11 -- RTOS: 11 -- Windows: 5 +- Linux: 48 +- macOS: 18 +- RTOS: 12 +- Windows: 10 subjects_filter: - CI-CD: 7 -- Containers and Virtualization: 6 +- Containers and Virtualization: 9 - Embedded Linux: 6 -- Libraries: 3 -- ML: 22 -- Performance and Architecture: 20 -- RTOS Fundamentals: 5 -- Security: 2 +- Libraries: 5 +- ML: 23 +- Performance and Architecture: 21 +- RTOS Fundamentals: 7 +- Security: 3 - Virtual Hardware: 2 subtitle: Learn best practices for IoT, embedded, and microcontroller development. title: Embedded and Microcontrollers @@ -43,13 +43,13 @@ tools_software_languages_filter: - Arm Streamline: 1 - Arm Virtual Hardware: 16 - Assembly: 1 -- AWS IoT Greengrass: 2 +- AWS IoT Greengrass: 3 - Azure: 1 - balenaCloud: 1 - BalenaOS: 1 - Baremetal: 1 - Bash: 1 -- C: 7 +- C: 10 - ChatGPT: 1 - Clang: 1 - CMSIS: 4 @@ -61,15 +61,15 @@ tools_software_languages_filter: - Containerd: 1 - CPP: 1 - DetectNet: 1 -- Docker: 12 +- Docker: 16 - DSTREAM: 2 - Edge AI: 2 - Edge Impulse: 2 -- ExecuTorch: 6 -- FastAPI: 1 +- ExecuTorch: 7 +- FastAPI: 2 - Fusion 360: 1 - FVP: 10 -- GCC: 10 +- GCC: 12 - Generative AI: 2 - GitHub: 4 - GitLab: 2 @@ -77,6 +77,7 @@ tools_software_languages_filter: - Himax SDK: 1 - Hugging Face: 3 - IP Explorer: 2 +- Java: 1 - Jupyter Notebook: 1 - K3s: 1 - Keil MDK: 7 @@ -86,7 +87,10 @@ tools_software_languages_filter: - LLM: 2 - Matter: 1 - MCP: 1 +- MediaPipe: 1 - MPS3: 1 +- MQTT: 1 +- MuJoCo: 1 - MXNet: 1 - Neon: 1 - NumPy: 1 @@ -96,28 +100,30 @@ tools_software_languages_filter: - Performance analysis: 1 - picocom: 1 - Porcupine: 1 -- Python: 12 +- Python: 17 - PyTorch: 5 -- QEMU: 1 -- Raspberry Pi: 9 +- QEMU: 2 +- Raspberry Pi: 10 +- Reachy Mini: 1 - Remote.It: 1 +- remoteproc-runtime: 1 - Runbook: 4 +- SSH: 3 +- stlink: 1 - STM32: 2 - strands-agents: 1 - systemd: 1 - TensorFlow: 3 - TensorRT: 1 - tinyML: 2 +- Topo: 3 - Trusted Firmware: 2 - TrustZone: 2 - TVMC: 1 - vcpkg: 1 -- Visual Studio Code: 1 +- Visual Studio Code: 2 +- YAML: 1 - Yocto Project: 1 -- Zephyr: 2 +- Zephyr: 4 weight: 5 -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit --- diff --git a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/connecting_peripheral.md b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/connecting_peripheral.md index 1e49ac2838..9e4d13f19f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/connecting_peripheral.md +++ b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/connecting_peripheral.md @@ -1,6 +1,7 @@ --- # User change title: "Connect AXI4 Peripheral to ZYNQ Processing System" +description: Connect the custom AXI4 peripheral to the Zynq processing system in Vivado so switch inputs can drive LED outputs on the Zybo Z7-10 board. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/creating_peripheral.md b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/creating_peripheral.md index e5843af71c..08aad4d118 100644 --- a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/creating_peripheral.md +++ b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/creating_peripheral.md @@ -1,6 +1,7 @@ --- # User change title: "Create a custom AXI4 Peripheral" +description: Create an AXI4-Lite peripheral in Vivado and define the registers and IP package used by the custom Zynq design. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/generating_bitstream.md b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/generating_bitstream.md index b22fc8febd..c2f4095277 100644 --- a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/generating_bitstream.md +++ b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/generating_bitstream.md @@ -1,6 +1,7 @@ --- # User change title: "Generate the bitstream and write your application using Vitis IDE" +description: Generate the Vivado bitstream, export the hardware design, and write a Vitis application to test the custom AXI4 peripheral. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/setup.md b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/setup.md index ce962fc650..e5f4bb96a7 100644 --- a/content/learning-paths/embedded-and-microcontrollers/advanced_soc/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/advanced_soc/setup.md @@ -1,6 +1,7 @@ --- # User change title: "Setup a Workspace in Xilinx Vivado" +description: Create a Vivado workspace for the Zybo Z7-10 board and configure the base Zynq processing system for a custom peripheral design. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/application-code.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/application-code.md index 9c30163c23..795cbb3093 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/application-code.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/application-code.md @@ -1,5 +1,6 @@ --- title: Add the application code +description: Add firmware code for camera input, image preprocessing, and Ethos-U85 inference in the Alif Ensemble image classification project. weight: 5 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/aws-ec2-setup.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/aws-ec2-setup.md index 1ceb3c6e1c..24935b3cab 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/aws-ec2-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/aws-ec2-setup.md @@ -1,5 +1,6 @@ --- title: Compile the model on an Arm cloud instance +description: Set up an Arm-based Amazon EC2 instance to compile the neural network model used by the Alif Ensemble image classification firmware. weight: 3 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/board-setup.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/board-setup.md index 8e5a028fc6..43f491bf5c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/board-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/board-setup.md @@ -1,5 +1,6 @@ --- title: Set up the Alif Ensemble E8 DevKit +description: Connect and configure the Alif Ensemble E8 DevKit so it is ready for firmware flashing and image classification inference. weight: 2 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/build-flash-verify.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/build-flash-verify.md index 528c8f1ccf..6f6220d623 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/build-flash-verify.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/build-flash-verify.md @@ -1,5 +1,6 @@ --- title: Build, flash, and verify inference +description: Build the Alif Ensemble firmware, flash it to the E8 DevKit, and verify image classification output over the serial console. weight: 8 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/create-project.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/create-project.md index 6660c8029a..7bc513dda1 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/create-project.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/create-project.md @@ -1,5 +1,6 @@ --- title: Create the image classification firmware project +description: Create the Alif Ensemble firmware project in VS Code and add the files needed for the image classification application. weight: 4 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/image-preparation.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/image-preparation.md index 3887046ae7..b961bd59d3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/image-preparation.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/image-preparation.md @@ -1,5 +1,6 @@ --- title: Prepare a test image +description: Prepare a test image with the expected size and format so the Alif Ensemble firmware can run image classification inference. weight: 7 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/memory-configuration.md b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/memory-configuration.md index 2c85b2027e..394cb4f491 100644 --- a/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/memory-configuration.md +++ b/content/learning-paths/embedded-and-microcontrollers/alif-image-classification/memory-configuration.md @@ -1,5 +1,6 @@ --- title: Configure memory layout and flash settings +description: Configure SRAM, flash, and scatter file settings so the Alif Ensemble application can load the model and run on the target hardware. weight: 6 layout: "learningpathall" diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/app_stack.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/app_stack.md index 57ad3acdc4..8ef1ef1809 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/app_stack.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/app_stack.md @@ -1,6 +1,7 @@ --- # User change title: "Application Programming" +description: Understand the application stack for the Raspberry Pi Pico motion detector before connecting sensors and implementing the firmware. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arduino_sketch.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arduino_sketch.md index ca96d7a348..2a8adabf19 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arduino_sketch.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arduino_sketch.md @@ -1,6 +1,7 @@ --- # User change title: "Program your smart device prototype" +description: Write and upload the Arduino sketch for the Raspberry Pi Pico so the smart device prototype can react to motion events. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arm_embedded.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arm_embedded.md index 9bc3c68cb1..7a6f531cf6 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arm_embedded.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/arm_embedded.md @@ -1,6 +1,7 @@ --- # User change title: "Embedded Programming on Arm" +description: Review Arm embedded development concepts and tool options used when programming Cortex-M based microcontroller projects. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/background.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/background.md index 49149c92a7..453c508f33 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/background.md @@ -1,6 +1,7 @@ --- # User change title: "About Embedded Programming" +description: Review embedded programming fundamentals and the hardware and software constraints that shape microcontroller applications. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/embedded_stack.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/embedded_stack.md index 69e21be9bf..f4107e9f5d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/embedded_stack.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/embedded_stack.md @@ -1,6 +1,7 @@ --- # User change title: "Embedded Programming" +description: Understand the layers of an embedded software stack and how firmware, runtime libraries, and hardware interact on microcontrollers. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-background.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-background.md index 4ce38ee383..d2ea99459a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-background.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-background.md @@ -1,5 +1,6 @@ --- title: Learn about interrupts +description: Learn why interrupt-driven programming improves responsiveness compared with polling in the Raspberry Pi Pico prototype. weight: 8 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-setup.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-setup.md index 52314d92d0..29399cd282 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/int-setup.md @@ -1,5 +1,6 @@ --- title: Add the interrupt code +description: Add interrupt handling code to the Raspberry Pi Pico application so the device responds to sensor changes without constant polling. weight: 9 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/raspberrypi_pico.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/raspberrypi_pico.md index 317374d3f9..fa01a7871c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/raspberrypi_pico.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/raspberrypi_pico.md @@ -1,6 +1,7 @@ --- # User change title: "Build a smart device prototype" +description: Build the first Raspberry Pi Pico motion detection prototype by wiring the PIR sensor and LED and uploading the initial Arduino sketch. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/refactoring.md b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/refactoring.md index d02d8d1372..ba1892dca3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/arduino-pico/refactoring.md +++ b/content/learning-paths/embedded-and-microcontrollers/arduino-pico/refactoring.md @@ -1,5 +1,6 @@ --- title: Refactor the application +description: Refactor the Raspberry Pi Pico application to separate state handling from hardware control and improve the device workflow. weight: 10 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/armds/build.md b/content/learning-paths/embedded-and-microcontrollers/armds/build.md index 1e74d1a54c..11427a9e30 100644 --- a/content/learning-paths/embedded-and-microcontrollers/armds/build.md +++ b/content/learning-paths/embedded-and-microcontrollers/armds/build.md @@ -1,6 +1,7 @@ --- # User change title: "Import and build example project" +description: Import an embedded example project into Arm Development Studio and build it for the selected compiler and target platform. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/armds/debug.md b/content/learning-paths/embedded-and-microcontrollers/armds/debug.md index 75be711189..4f82f7c30d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/armds/debug.md +++ b/content/learning-paths/embedded-and-microcontrollers/armds/debug.md @@ -1,6 +1,7 @@ --- # User change title: Debug the example +description: Debug the example project in Arm Development Studio using an FVP target and inspect execution with breakpoints and registers. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/armds/misc.md b/content/learning-paths/embedded-and-microcontrollers/armds/misc.md index 127612ede4..7be15baaae 100644 --- a/content/learning-paths/embedded-and-microcontrollers/armds/misc.md +++ b/content/learning-paths/embedded-and-microcontrollers/armds/misc.md @@ -1,6 +1,7 @@ --- # User change title: Other compilers and project types +description: Adjust Arm Development Studio projects for alternate compiler versions and project types when the default setup does not match your environment. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/asm/coding.md b/content/learning-paths/embedded-and-microcontrollers/asm/coding.md index 49a7391850..6342d9db65 100644 --- a/content/learning-paths/embedded-and-microcontrollers/asm/coding.md +++ b/content/learning-paths/embedded-and-microcontrollers/asm/coding.md @@ -1,6 +1,7 @@ --- # User change title: Writing assembly functions +description: Create C and Arm assembly source files that work together under the Arm Procedure Call Standard for a Cortex-M project. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/asm/intro.md b/content/learning-paths/embedded-and-microcontrollers/asm/intro.md index eb10c5f1f5..7c7636814d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/asm/intro.md +++ b/content/learning-paths/embedded-and-microcontrollers/asm/intro.md @@ -1,6 +1,7 @@ --- # User change title: Keil MDK versions +description: Compare Keil MDK versions and choose the development environment used for the embedded assembly programming examples. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk5.md b/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk5.md index 5b4ef44aa0..a8851231bb 100644 --- a/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk5.md +++ b/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk5.md @@ -1,6 +1,7 @@ --- # User change title: "Setting up a Project in Keil MDK (μVision)" +description: Create and configure a Keil MDK uVision project for the Cortex-M assembly examples. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk6.md b/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk6.md index e8be73ecc7..70fb85c803 100644 --- a/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk6.md +++ b/content/learning-paths/embedded-and-microcontrollers/asm/setup_mdk6.md @@ -1,6 +1,7 @@ --- # User change title: "Setting up a Project in Keil Studio (VS Code)" +description: Create a Keil Studio csolution project for the Cortex-M assembly examples and prepare it for mixed C and assembly code. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_balena/2setup.md b/content/learning-paths/embedded-and-microcontrollers/avh_balena/2setup.md index f631682f5a..6484569c14 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_balena/2setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_balena/2setup.md @@ -1,5 +1,6 @@ --- title: "Prepare a custom Balena OS image" +description: Create a Balena Cloud application and prepare a custom Balena OS image for a virtual Raspberry Pi 4 device. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_balena/3install.md b/content/learning-paths/embedded-and-microcontrollers/avh_balena/3install.md index 7057f1010f..49d2115fa2 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_balena/3install.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_balena/3install.md @@ -1,5 +1,6 @@ --- title: "Install Balena OS on AVH" +description: Provision a Raspberry Pi 4 instance in Arm Virtual Hardware and install the custom Balena OS image on the virtual device. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_balena/4deploy.md b/content/learning-paths/embedded-and-microcontrollers/avh_balena/4deploy.md index 1027e9eb9c..f91aa6d924 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_balena/4deploy.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_balena/4deploy.md @@ -1,5 +1,6 @@ --- title: "Deploy an application to your device" +description: Deploy an application from Balena Hub to the Arm Virtual Hardware device and verify that it runs in Balena Cloud. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/2setup.md b/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/2setup.md index 25ba03db8e..58ee6d77a3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/2setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/2setup.md @@ -1,5 +1,6 @@ --- title: Set up your accounts and create a virtual device +description: Configure AWS and Arm Virtual Hardware accounts and create the virtual Raspberry Pi 4 device used as a Greengrass core. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/3deploy.md b/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/3deploy.md index e86f02dd38..6beddf7b49 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/3deploy.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_greengrass/3deploy.md @@ -1,5 +1,6 @@ --- title: Deploy an AWS IoT Greengrass component to your device +description: Create an AWS IoT Greengrass deployment and run a Greengrass component on the virtual Raspberry Pi 4 device. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_matter/2setup.md b/content/learning-paths/embedded-and-microcontrollers/avh_matter/2setup.md index de6a688164..e6f66f7dd5 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_matter/2setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_matter/2setup.md @@ -1,6 +1,7 @@ --- # User change title: "Prepare AVH instances of Raspberry Pi 4" +description: Prepare two Raspberry Pi 4 instances in Arm Virtual Hardware for building and testing Matter examples. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_matter/3build.md b/content/learning-paths/embedded-and-microcontrollers/avh_matter/3build.md index b8913808f0..ab9879cdf8 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_matter/3build.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_matter/3build.md @@ -1,6 +1,7 @@ --- # User change title: "Build and run Matter examples on Arm Virtual Hardware" +description: Build Matter reference examples on Arm Virtual Hardware and run device communication between the virtual Raspberry Pi instances. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_matter/4cicdsh.md b/content/learning-paths/embedded-and-microcontrollers/avh_matter/4cicdsh.md index 7dc233db44..d6d571d40f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_matter/4cicdsh.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_matter/4cicdsh.md @@ -1,6 +1,7 @@ --- # User change title: "Manage development in a CI/CD workflow with Self-Hosted Runner" +description: Configure a GitHub Actions self-hosted runner on Arm Virtual Hardware to automate Matter example builds and tests. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_matter/5cicdapi.md b/content/learning-paths/embedded-and-microcontrollers/avh_matter/5cicdapi.md index c9f53a00a5..12acac0686 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_matter/5cicdapi.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_matter/5cicdapi.md @@ -1,6 +1,7 @@ --- # User change title: "Control Arm Virtual Hardware with API" +description: Use the Arm Virtual Hardware API from GitHub Actions to create, control, and clean up virtual devices during Matter CI workflows. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/end-to-end_workflow.md b/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/end-to-end_workflow.md index e8b6ff45ba..118b2226f4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/end-to-end_workflow.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/end-to-end_workflow.md @@ -1,6 +1,7 @@ --- # User change title: "Deploy the PaddleOCR model" +description: Compile and deploy the PaddleOCR model to the Corstone-300 FVP and run the end-to-end optical character recognition workflow. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/overview.md b/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/overview.md index 1503ba0440..9f811fc5ae 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_ppocr/overview.md @@ -1,6 +1,7 @@ --- # User change title: "Overview of OCR" +description: Review optical character recognition concepts and the PaddleOCR model workflow before deploying it on Arm Virtual Hardware. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/avh_vio/vio.md b/content/learning-paths/embedded-and-microcontrollers/avh_vio/vio.md index 1fae9a85c5..b2242bf3e2 100644 --- a/content/learning-paths/embedded-and-microcontrollers/avh_vio/vio.md +++ b/content/learning-paths/embedded-and-microcontrollers/avh_vio/vio.md @@ -1,6 +1,7 @@ --- # User change title: "Create a peripheral using Virtual Input/Output (VIO)" +description: Create a virtual LED peripheral with Arm Virtual Hardware VIO and connect it to firmware running on the simulated platform. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/aggregation.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/aggregation.md index f2e76d0435..6e3c422b20 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/aggregation.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/aggregation.md @@ -1,6 +1,7 @@ --- # User change title: "Sensor Data Aggregation Using Azure Functions" +description: Aggregate IoT telemetry with Azure Functions so sensor data from Arm devices can be summarized for downstream services. weight: 8 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/device_registration.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/device_registration.md index b812331919..93f4421789 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/device_registration.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/device_registration.md @@ -1,6 +1,7 @@ --- # User change title: "Build a Python-based IoT telemetry simulator" +description: Build a Python telemetry simulator and register it as an Azure IoT device for sending sample sensor readings. weight: 4 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/intro.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/intro.md index f4497199f1..300dc8252f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/intro.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/intro.md @@ -1,6 +1,7 @@ --- # User change title: "Overview" +description: Review the Azure IoT services and telemetry flow used to build an end-to-end cloud pipeline for Arm devices. weight: 2 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/iot-hub.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/iot-hub.md index 2d052628c2..3ade6bc7b3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/iot-hub.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/iot-hub.md @@ -1,6 +1,7 @@ --- # User change title: "Create Azure IoT Hub" +description: Create an Azure IoT Hub and configure the device connection details needed for streaming telemetry from Arm devices. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/monitoring.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/monitoring.md index 184ead66b3..2d4b2db26e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/monitoring.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/monitoring.md @@ -1,6 +1,7 @@ --- # User change title: "Set up data monitoring and alerts with Azure Functions" +description: Set up Azure Functions based monitoring and alerts so incoming IoT telemetry can trigger automated responses. weight: 7 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/portal.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/portal.md index 26dc8215d3..760a6a4a3a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/portal.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/portal.md @@ -1,6 +1,7 @@ --- # User change title: "IoT Portal" +description: Create an IoT portal that visualizes telemetry from Azure services and gives users a dashboard for device data. weight: 9 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics-dynamo-db.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics-dynamo-db.md index 455cf82cef..58f42c8660 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics-dynamo-db.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics-dynamo-db.md @@ -1,6 +1,7 @@ --- # User change title: "Store data in Azure Cosmos DB with Azure Stream Analytics" +description: Store processed telemetry in Azure Cosmos DB by configuring an Azure Stream Analytics job for the IoT pipeline. weight: 6 diff --git a/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics.md b/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics.md index a385a6e459..6ec29d69f1 100644 --- a/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics.md +++ b/content/learning-paths/embedded-and-microcontrollers/azure-iot/stream-analytics.md @@ -1,6 +1,7 @@ --- # User change title: "Process IoT telemetry in real time with Azure Stream Analytics" +description: Configure Azure Stream Analytics to process IoT Hub telemetry in real time and route results to downstream services. weight: 5 diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven1.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven1.md index b54a88589a..004530e24a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven1.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven1.md @@ -1,6 +1,7 @@ --- # User change title: Create event-driven application (1) +description: Configure exception routing and the first interrupt handling pieces for an event-driven bare-metal Armv8-A application. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven2.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven2.md index f79cd565d3..3da6cc054d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven2.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/event-driven2.md @@ -1,6 +1,7 @@ --- # User change title: Create event-driven application (2) +description: Set up the Generic Interrupt Controller and complete the event-driven Armv8-A application on the FVP. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/exception-levels.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/exception-levels.md index 6e84efabed..04038ddcb4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/exception-levels.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/exception-levels.md @@ -1,6 +1,7 @@ --- # User change title: Switching Exception Levels +description: Modify the bare-metal example to switch Armv8-A exception levels and observe how execution changes on the FVP. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/hello.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/hello.md index ddd5b4bc95..c664289e35 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/hello.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/hello.md @@ -1,6 +1,7 @@ --- # User change title: Create and build a Hello World example project +description: Create and build a bare-metal Hello World project with Arm tools and run it on an Arm Fixed Virtual Platform. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/reset.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/reset.md index 5c7067e942..f4f376b1d1 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/reset.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/reset.md @@ -1,6 +1,7 @@ --- # User change title: Write a reset handler +description: Write the reset handler for the bare-metal Armv8-A example so execution reaches the application entry point correctly. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/bare-metal/retarget.md b/content/learning-paths/embedded-and-microcontrollers/bare-metal/retarget.md index a180c1d2ca..3b58989be9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/bare-metal/retarget.md +++ b/content/learning-paths/embedded-and-microcontrollers/bare-metal/retarget.md @@ -1,6 +1,7 @@ --- # User change title: "Modify the example to use the UART for printf output" +description: Retarget printf output to the UART so the bare-metal Armv8-A application can print messages from the FVP. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/avh-setup.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/avh-setup.md index 8f1141285b..0e3d129d70 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/avh-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/avh-setup.md @@ -1,5 +1,6 @@ --- title: AVH device setup +description: Set up the i.MX 8M Plus model in Arm Virtual Hardware for testing hybrid edge application deployment. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/build-runtime.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/build-runtime.md index c394a0c509..9a492e006f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/build-runtime.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/build-runtime.md @@ -1,5 +1,6 @@ --- title: Building the hybrid-runtime and container image (optional) +description: Build the hybrid-runtime and firmware container image used to run Cortex-M workloads from a Cortex-A Linux environment. weight: 7 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/containerd.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/containerd.md index edf26062a1..a6702452db 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/containerd.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/containerd.md @@ -1,5 +1,6 @@ --- title: Deploy firmware container using `containerd` +description: Deploy a firmware container with containerd and verify a Hello World workload on the hybrid edge runtime. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/k3s.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/k3s.md index 18e3b0f3c2..3f283cd9ef 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/k3s.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/k3s.md @@ -1,5 +1,6 @@ --- title: Deploy SMARTER Demo using K3s +description: Deploy the SMARTER demo with K3s on Arm Virtual Hardware and verify container orchestration for the hybrid edge system. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/motivation.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/motivation.md index 694bdc736c..fc9fa98e62 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/motivation.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/motivation.md @@ -1,5 +1,6 @@ --- title: Motivation +description: Understand why hybrid-runtime enables cloud-native deployment of embedded workloads across Cortex-A and Cortex-M cores. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/runtime-overview.md b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/runtime-overview.md index 75776dd8f3..5712b5ef20 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/runtime-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/cloud-native-deployment-on-hybrid-edge-systems/runtime-overview.md @@ -1,5 +1,6 @@ --- title: Hybrid container runtime +description: Review the hybrid container runtime architecture and how it maps firmware containers to Arm edge hardware. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/build_and_run.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/build_and_run.md index 8f6b946842..0f6fa5ee08 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/build_and_run.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/build_and_run.md @@ -1,6 +1,7 @@ --- # User change title: "Build and run the application" +description: Build and run the CMSIS-RTOS2 RTX application in Keil MDK and verify the thread behavior on the target. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/create.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/create.md index d89912b054..b95edcf145 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/create.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/create.md @@ -1,6 +1,7 @@ --- # User change title: "Create and setup Keil MDK project" +description: Create a Keil MDK project, install CMSIS packs, and configure the components needed for an RTX5 application. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/eventrecorder.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/eventrecorder.md index 10075d2ca0..791a6c2b41 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/eventrecorder.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/eventrecorder.md @@ -1,6 +1,7 @@ --- # User change title: "Using Event Recorder" +description: Enable Event Recorder for the RTX5 application so thread scheduling and runtime behavior can be inspected during debug. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/initialize.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/initialize.md index 2cdb6f52a7..7e20042236 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/initialize.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/initialize.md @@ -1,6 +1,7 @@ --- # User change title: "Initialize the operating system" +description: Initialize the CMSIS-RTOS2 kernel in the example application and start the main RTOS entry point. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/threads.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/threads.md index 108e3aa12b..bd2879287b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/threads.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx/threads.md @@ -1,6 +1,7 @@ --- # User change title: "Create RTOS threads" +description: Create RTX5 threads with CMSIS-RTOS2 APIs and coordinate them in the embedded example application. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/build_and_run.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/build_and_run.md index 5747edb3f9..c6976008ad 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/build_and_run.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/build_and_run.md @@ -1,6 +1,7 @@ --- # User change title: "Build and run the application" +description: Build and run the CMSIS-RTOS2 RTX application from Keil Studio for VS Code and verify the generated firmware. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/create.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/create.md index 67a29a6b48..0a544b5b61 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/create.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/create.md @@ -1,6 +1,7 @@ --- # User change title: "Create csolution project" +description: Create a csolution project in Keil Studio for VS Code and configure CMSIS components for an RTX5 application. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/initialize.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/initialize.md index 041c7fbb01..6659f7c6e3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/initialize.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/initialize.md @@ -1,6 +1,7 @@ --- # User change title: "Initialize the Operating System" +description: Initialize the CMSIS-RTOS2 kernel in the Keil Studio project and prepare the application startup code. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/threads.md b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/threads.md index 4138c2b068..40c3a81d52 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/threads.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsis_rtx_vs/threads.md @@ -1,6 +1,7 @@ --- # User change title: "Create RTOS Threads" +description: Add RTX5 threads to the Keil Studio project using CMSIS-RTOS2 APIs and verify the multitasking flow. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-1.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-1.md index 7bffd2a23f..bef9ac3ee2 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-1.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-1.md @@ -1,5 +1,6 @@ --- title: CMSIS-DSP Python package +description: Install and explore the CMSIS-DSP Python package so you can prototype signal processing algorithms before porting to C. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-2.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-2.md index 118b85c81c..6210006571 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-2.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-2.md @@ -1,5 +1,6 @@ --- title: Set up environment +description: Create the Python environment and install the packages needed to develop and test CMSIS-DSP signal processing code. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-3.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-3.md index b83f0d6c66..ab5bca4c05 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-3.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-3.md @@ -1,5 +1,6 @@ --- title: Load an audio file +description: Load and inspect an audio file in Python so it can be used as input for the CMSIS-DSP voice activity workflow. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-4.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-4.md index 824d40fe1b..25d5031520 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-4.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-4.md @@ -1,5 +1,6 @@ --- title: Write a simple VAD +description: Implement a simple voice activity detector in Python and validate the signal processing behavior before optimization. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-5.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-5.md index 3fe9f5be65..e862af3162 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-5.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-5.md @@ -1,5 +1,6 @@ --- title: Write a noise suppression algorithm +description: Build a noise suppression algorithm in Python and understand the math that prepares it for embedded DSP implementation. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-6.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-6.md index f963a4eb73..10ac331ba2 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-6.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-6.md @@ -1,5 +1,6 @@ --- title: Write the CMSIS-DSP Q15 implementation +description: Implement the voice activity detector with CMSIS-DSP Q15 functions and compare it with the Python prototype. weight: 7 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-7.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-7.md index 7fca5f38ab..7b0bdfe82a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-7.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-7.md @@ -1,5 +1,6 @@ --- title: Convert the CMSIS-DSP Python to C +description: Convert the CMSIS-DSP Python prototype to C so the algorithm can run efficiently on Arm embedded targets. weight: 8 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-8.md b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-8.md index fb229f1dd2..9050c091fe 100644 --- a/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-8.md +++ b/content/learning-paths/embedded-and-microcontrollers/cmsisdsp-dev-with-python/how-to-8.md @@ -1,5 +1,6 @@ --- title: Develop your knowledge +description: Explore additional CMSIS-DSP resources and example projects to continue developing embedded signal processing skills. weight: 9 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/context-switch-cortex-m/example.md b/content/learning-paths/embedded-and-microcontrollers/context-switch-cortex-m/example.md index 331ea20510..15736b233a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/context-switch-cortex-m/example.md +++ b/content/learning-paths/embedded-and-microcontrollers/context-switch-cortex-m/example.md @@ -1,6 +1,7 @@ --- # User change title: Example Arm DS project to demonstrate context switching operations +description: Explore the Arm Development Studio example project that demonstrates Cortex-M context switching with the MPU and SysTick exception. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/cc.md b/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/cc.md index b94697e44c..c75d640369 100644 --- a/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/cc.md +++ b/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/cc.md @@ -1,6 +1,7 @@ --- # User change title: "What is Code Coverage?" +description: Understand code coverage concepts for embedded software testing and how they apply to Keil MDK projects. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/mdk.md b/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/mdk.md index 9828e41e7d..679f5b9263 100644 --- a/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/mdk.md +++ b/content/learning-paths/embedded-and-microcontrollers/coverage_mdk/mdk.md @@ -1,6 +1,7 @@ --- # User change title: "Set up Code Coverage" +description: Enable code coverage in Keil MDK, run the embedded example, and review the coverage results from the FVP. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/_index.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/_index.md similarity index 58% rename from content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/_index.md rename to content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/_index.md index d60d1c3340..ed372cc867 100644 --- a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/_index.md +++ b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/_index.md @@ -1,30 +1,32 @@ --- -title: Deploy a machine learning model to an NPU-capable system with Topo +title: Deploy a machine learning application to the Arm Ethos-U65 NPU on NXP FRDM i.MX 93 with Topo draft: true cascade: draft: true -description: Use Topo to deploy a web application on Cortex-A that triggers a MobileNetV2 image classifier running as Cortex-M firmware with Ethos-U65 NPU acceleration. +description: Use Topo to build and deploy a Cortex-A web application that sends MobileNetV2 image classification requests to Cortex-M33 firmware accelerated by the Ethos-U65 NPU. minutes_to_complete: 60 -who_is_this_for: This is an introductory topic for embedded, edge, and cloud software developers who want to deploy machine learning workloads to heterogeneous Arm-based Linux targets using Topo. +who_is_this_for: This is an introductory topic for embedded/edge software developers who want to deploy machine learning workloads to heterogeneous Arm-based Linux targets using Topo, including leveraging Arm Ethos-U NPUs. learning_objectives: - Explain how Topo deploys an application that spans Cortex-A, Cortex-M, and Ethos-U - - Prepare an NXP FRDM i.MX 93 board for remoteproc-runtime and shared-memory inference - - Clone and deploy the topo-imx93-npu-deployment template - - Describe how the Template is bootstrapped from Compose services, Remoteproc Runtime metadata, and Topo arguments - - Run image classification from a browser and verify that inference is executed by the Cortex-M33 firmware + - Deploy the topo-imx93-npu-deployment Template, which operates across Cortex-A, Cortex-M, and Ethos-U, to perform image classification using an ExecuTorch MobileNetV2 model + - Describe how the Template is bootstrapped from Compose services, Remoteproc Runtime metadata, and Topo arguments and follow this process yourself + - Understand how to take similar projects and create Topo Templates, including using Agent Skills prerequisites: - A host machine (x86 or Arm) with Linux, macOS, or Windows - - An NXP FRDM i.MX 93 target board accessible over SSH with root access - - Docker installed on the host and target. For installation steps, see [Install Docker](/install-guides/docker/). + - An NXP FRDM i.MX 93 target board with Linux setup, accessible over SSH with root access. To do this, see [Use Linux on the NXP FRDM i.MX 93 board](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/linux-nxp-board/). + - Docker installed on the host and target. For installation steps, see [Install Docker](https://learn.arm.com/install-guides/docker/). + - At least 25 GB of free disk space on the host if you're building without cache images. + - The Device Tree Compiler (`dtc`) installed on the host. - lscpu installed on the target (pre-installed on most Linux distributions) - - Topo installed on the host. For installation steps, see [Deploy containerized workloads to Arm-based Linux targets with Topo](/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/). + - Topo installed on the host. For installation steps, see [Deploy containerized workloads to Arm-based Linux targets with Topo](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/). - Basic familiarity with containers, SSH, and CLI tools + - (Optional) Access to an agent, such as Codex or Claude Code author: Tomas Agustin Gonzalez Orlando @@ -50,13 +52,6 @@ operatingsystems: - macOS - Windows -### Cross-platform metadata only -shared_path: true -shared_between: - - servers-and-cloud-computing - - laptops-and-desktops - - embedded-and-microcontrollers - further_reading: - resource: title: Topo repository diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/_next-steps.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/_next-steps.md similarity index 100% rename from content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/_next-steps.md rename to content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/_next-steps.md diff --git a/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/build-the-template.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/build-the-template.md new file mode 100644 index 0000000000..2649551d4f --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/build-the-template.md @@ -0,0 +1,419 @@ +--- +title: Build the Topo Template from scratch +description: Create a Topo Template from the web application and Cortex-M33 firmware sources by adding Compose services, build artifacts, remoteproc-runtime metadata, and Topo arguments. +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## What you will build + +In this section, you'll build the `topo-imx93-npu-deployment` Topo Template starting from two non-Topo, non-Compose projects: + +- a Cortex-A web application that prepares images, writes model and tensor data into shared memory, and sends inference commands over `RPMsg` +- a Cortex-M33 ExecuTorch runner firmware project for the FRDM i.MX 93 + +You'll combine those sources into one repository, then make the repository a normal Compose project. Then, you'll add the Topo metadata and Remoteproc Runtime services. + +## Create the repository from the base projects + +Start by copying the original base projects from the Topo Template. + +Clone the Topo Template Format repository for the validation schema, clone the original Topo Template for the source files, and start a new empty repository: + +```bash +git clone https://github.com/arm/topo-template-format.git +git clone https://github.com/Arm-Examples/topo-imx93-npu-deployment.git +mkdir new-topo-npu-template +cd new-topo-npu-template +``` + +Create the project layout: + +```bash +mkdir -p webapp executorch-runner licenses +``` + +Copy the relevant `webapp` files: + +```bash +cp -R ../topo-imx93-npu-deployment/webapp/src webapp +``` + +Copy the Cortex-M33 runner build inputs from the firmware project: + +```bash +cp ../topo-imx93-npu-deployment/executorch-runner/build-runner.sh executorch-runner/build-runner.sh +cp ../topo-imx93-npu-deployment/executorch-runner/export_mv2_imx93.py executorch-runner/export_mv2_imx93.py +cp ../topo-imx93-npu-deployment/executorch-runner/docker-entrypoint.sh executorch-runner/docker-entrypoint.sh +cp -R ../topo-imx93-npu-deployment/executorch-runner/patches executorch-runner +``` + +Add the licenses and ignore rules used by the source projects: + +```bash +cp ../topo-imx93-npu-deployment/LICENSE.md . +cp -R ../topo-imx93-npu-deployment/licenses . +cp ../topo-imx93-npu-deployment/.gitignore . +``` + +You have two sets of source code combined into one repository. It's not a Compose project and it's not a Topo Template. + +You'll now create a Compose project and Topo Template around the source code. + +The Compose project provides the container build and runtime structure. A Dockerfile describes how to build one image. A Compose file describes the services that use those images, their build contexts, ports, volumes, dependencies, and runtime settings. In this Template: + +- `webapp/Dockerfile` builds the Flask image. +- `webapp/compose.yaml` keeps the web app's build context and Linux runtime settings close to the web app source. +- `executorch-runner/Dockerfile` builds the ExecuTorch `.pte` model and Cortex-M33 runner ELF through multi-stage Docker builds. +- the root `compose.yaml` is the Topo Template entry point. It combines the web app, artifact build services, the Remoteproc Runtime service, and the root-level `x-topo` metadata. + +For a general introduction to Compose projects, services, and the `compose.yaml` file, see Docker's [How Compose works](https://docs.docker.com/compose/intro/compose-application-model/) documentation. + +{{% notice Note %}} +When you creating a file for any of the following steps, paste the complete file contents as shown. + +When you update part of an existing Compose file for a step, merge the YAML into the existing top-level key shown by the snippet. For example, if a snippet starts with `services:`, add the named service under the existing top-level `services:` map. Don't create a second `services:` block in the same file. +{{% /notice %}} + +## Turn the sources into a Compose project + +Before adding Topo metadata, make the project work as ordinary Compose. Start by containerizing the Cortex-A web application. + +Create `webapp/Dockerfile` with the following complete contents: + +```Dockerfile +FROM python:3.12-slim + +WORKDIR /app + +ENV PYTHONUNBUFFERED=1 + +RUN python -m pip install --no-cache-dir flask==3.0.3 + +COPY src/data/imagenet_classes.txt /opt/mv2-imx93/imagenet_classes.txt +COPY src/app.py . +COPY src/templates/ templates/ +COPY src/static/ static/ + +EXPOSE 3000 + +CMD ["python", "app.py"] +``` + +Create `webapp/compose.yaml` with the following complete contents: + +```yaml +services: + webapp: + platform: linux/arm64 + build: + context: . + dockerfile: Dockerfile + privileged: true + ports: + - "${WEBAPP_PORT:-3001}:3000" + volumes: + - /sys:/sys + - /dev:/dev + restart: unless-stopped +``` + +Create the root `compose.yaml` with the following complete contents: + +```yaml +services: + webapp: + platform: linux/arm64 + extends: + file: webapp/compose.yaml + service: webapp +``` + +Check that Compose can read the project: + +```bash +docker compose config +``` + +The output includes the resolved `webapp` service, and is similar to: + +```output +services: + webapp: + build: + context: /path/to/new-topo-npu-template/webapp + dockerfile: Dockerfile + ports: + - mode: ingress + target: 3000 + published: "3001" +``` + +At this point, Compose can build and run the Cortex-A web application as a normal Linux container. The image runs `webapp/src/app.py`. It packages the Jinja templates from `webapp/src/templates/`, the static assets from `webapp/src/static/`, and the ImageNet labels from `webapp/src/data/imagenet_classes.txt`. The container listens on port `3000`, and Compose publishes it on host port `3001` unless you set `WEBAPP_PORT` to another value. + +## Add the ExecuTorch artifact pipeline + +The web application needs an ExecuTorch `.pte` model, and the target needs a Cortex-M33 ELF image. Both artifacts are built by `executorch-runner/Dockerfile`. + +Copy the Dockerfile into the runner build context: + +```bash +cp ../topo-imx93-npu-deployment/executorch-runner/Dockerfile executorch-runner/ +``` + +For this multi-stage Dockerfile: + +- `build-base`: installs the common Ubuntu build tools. +- `executorch-base`: clones ExecuTorch, installs the Arm backend dependencies, and copies `export_mv2_imx93.py` and `docker-entrypoint.sh`. +- `pte-builder`: exports `mv2_ethosu65_256.pte`. +- `pte-artifacts`: packages the `.pte` file as a BuildKit artifact context. +- `runner-base`: installs the Arm GNU toolchain, MCUX SDK, RPMsg-Lite dependencies, runner sources, and local patches. +- `runner-builder`: builds `executorch_runner_cm33.elf`. +- `runner-artifacts`: packages the ELF for inspection or reuse. +- `runner-runtime`: produces a `scratch` image whose entrypoint is the ELF file. + +The important artifact stages look like this: + +```Dockerfile +FROM busybox:1.36 AS pte-artifacts +COPY --from=pte-builder /workspace/build/mv2-imx93/mv2_ethosu65_256.pte /artifacts/mv2_ethosu65_256.pte + +FROM busybox:1.36 AS runner-artifacts +COPY --from=runner-builder /artifacts/executorch_runner_cm33.elf /artifacts/executorch_runner_cm33.elf + +FROM scratch AS runner-runtime +COPY --from=runner-builder /artifacts/executorch_runner_cm33.elf /executorch_runner_cm33.elf +ENTRYPOINT ["/executorch_runner_cm33.elf"] +``` + +## Connect the artifact services + +Add `pte-artifacts` and `runner-artifacts` as siblings of the existing `webapp` service in the root `compose.yaml`: + +```yaml +services: + pte-artifacts: + platform: linux/arm64 + scale: 0 + build: + context: executorch-runner + dockerfile: Dockerfile + target: pte-artifacts + cache_from: + - ${EXECUTORCH_BASE_CACHE_IMAGE:-ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04} + + runner-artifacts: + platform: linux/arm64 + scale: 0 + build: + context: executorch-runner + dockerfile: Dockerfile + target: runner-artifacts + cache_from: + - ${IMX93_RUNNER_BUILD_CACHE_IMAGE:-ghcr.io/arm-examples/topo-imx93-npu-deployment/imx93-runner-build:mcux-v25.09.00-armgcc14.2-ubuntu24.04} +``` + +Don't replace the existing root `webapp` service with this snippet. The root file should now have three service names under the same top-level `services:` map: `webapp`, `pte-artifacts`, and `runner-artifacts`. + +These services are used only to build artifacts. They don't run as part of the deployed application. `scale: 0` tells Compose not to start containers for them, while still allowing other services to copy files from their build outputs. + +Replace `webapp/compose.yaml` with the following version so the Flask image imports the `.pte` artifact: + +```yaml +services: + webapp: + platform: linux/arm64 + build: + context: . + dockerfile: Dockerfile + additional_contexts: + pte_artifacts: service:pte-artifacts + privileged: true + ports: + - "${WEBAPP_PORT:-3001}:3000" + volumes: + - /sys:/sys + - /dev:/dev + restart: unless-stopped +``` + +Then add the `.pte` copy line to `webapp/Dockerfile` with the other `COPY` commands: + +```Dockerfile +COPY --from=pte_artifacts /artifacts/mv2_ethosu65_256.pte /opt/mv2-imx93/mv2_ethosu65_256.pte +``` + +The `/opt/mv2-imx93/` path is the location the Flask application expects for its MobileNetV2 support files. At run time, the app reads the `.pte` file from this path before copying it into reserved memory for the Cortex-M33 runner. + +## Add the Remoteproc Runtime service + +Add the Cortex-M33 runner as another sibling under the top-level `services:` map in the root `compose.yaml`: + +```yaml +services: + cm33-runner: + platform: linux/arm64 + build: + context: executorch-runner + dockerfile: Dockerfile + target: runner-runtime + cache_from: + - ${IMX93_RUNNER_BUILD_CACHE_IMAGE:-ghcr.io/arm-examples/topo-imx93-npu-deployment/imx93-runner-build:mcux-v25.09.00-armgcc14.2-ubuntu24.04} + runtime: io.containerd.remoteproc.v1 + annotations: + remoteproc.name: imx-rproc +``` + +Keep the existing `webapp`, `pte-artifacts`, and `runner-artifacts` services in the same file. This step adds one more service and doesn't replace any of the previous services. + +This is the heterogeneous deployment hook. Docker still builds an image, but the service doesn't start as a Linux userspace process. The runtime `io.containerd.remoteproc.v1` selects Remoteproc Runtime, and the `remoteproc.name` annotation tells the shim to use the i.MX remote processor driver. + +Update the existing root `webapp` service so it depends on the CM33 runner and passes the cache image values into the build. Keep the existing `extends` block, then add `depends_on` and `build.args` as shown: + +```yaml +services: + webapp: + platform: linux/arm64 + extends: + file: webapp/compose.yaml + service: webapp + depends_on: + - cm33-runner + build: + args: + EXECUTORCH_BASE_CACHE_IMAGE: ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04 + IMX93_RUNNER_BUILD_CACHE_IMAGE: ghcr.io/arm-examples/topo-imx93-npu-deployment/imx93-runner-build:mcux-v25.09.00-armgcc14.2-ubuntu24.04 +``` + +The web app is privileged and mounts `/sys` and `/dev` because it checks the device tree, reads remoteproc state through `/sys/class/remoteproc`, talks to `/dev/ttyRPMSG*`, writes shared memory through `/dev/mem`, and checks for `/dev/ethosu0`. + +Keep the web app build context in `webapp/compose.yaml`. The root `webapp.build.args` block supplies only Topo-collected build arguments. It shouldn't replace the extended build context and Dockerfile from `webapp/compose.yaml`. + +## Add Topo metadata and arguments + +After the Compose services are complete, add the root-level `x-topo` block. +Keep it at the root of `compose.yaml`, as a sibling of `services`, not under `services`. + +If you want to use an agent skill to perform this step, skip to the optional step. + +```yaml +x-topo: + name: "i.MX93 ExecuTorch runner" + description: "Runs a Cortex-A web application that sends image inference commands to a resident CM33 ExecuTorch runner over RPMsg." + features: + - "remoteproc-runtime" + args: + EXECUTORCH_BASE_CACHE_IMAGE: + description: Optional GHCR image used as a BuildKit cache source for the ExecuTorch PTE build. + required: false + default: ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04 + IMX93_RUNNER_BUILD_CACHE_IMAGE: + description: Optional GHCR image used as a BuildKit cache source for the CM33 runner build. + required: false + default: ghcr.io/arm-examples/topo-imx93-npu-deployment/imx93-runner-build:mcux-v25.09.00-armgcc14.2-ubuntu24.04 +``` + +The `features` value tells Topo that this template requires `remoteproc-runtime` support on the target. This is useful when checking for project compatibility with the `topo templates --target ` command. + +The `args` entries describe configurable build inputs. Compose consumes those values through the `cache_from` interpolation that you added earlier: + +```output +cache_from: + - ${EXECUTORCH_BASE_CACHE_IMAGE:-ghcr.io/arm-examples/topo-imx93-npu-deployment/executorch-base:et-v1.2.0-ubuntu24.04} +``` + +The root `webapp.build.args` block also makes the Topo-provided values visible in the Compose build model while preserving the `webapp/` build context inherited through `extends`. + +Keep runtime settings such as `WEBAPP_PORT` as normal Compose interpolation unless you intentionally want Topo to collect them as Topo Template setup arguments. + +## (Optional) Use an Agent Skill to add the Topo metadata + +The [Topo Template Format](https://github.com/arm/topo-template-format) repository includes public authoring skills for agents that support skill installation: + +- `topo-template-context`: provides Topo and Topo Template reference context for `x-topo` metadata, schema, docs, and CLI template behavior. +- `topo-template-bootstrap`: converts a Compose repository into a Topo Template by adding or improving `compose.yaml` and `x-topo` metadata. +- `topo-template-lint`: reviews a Topo Template for schema correctness, metadata consistency, deployment success messages, and build argument wiring. + +Install the skills with `npx skills`: + +```bash +npx skills add arm/topo-template-format +``` + +If your agent doesn't use `npx skills`, manually copy or symlink the directories under `../topo-template-format/skills/` into your agent's skills directory. + +Restart your agent after installing or updating the skills. + +From the root of the Compose project, ask your agent to use `topo-template-bootstrap`: + +``` +Use topo-template-bootstrap on this repository. +Treat the root compose.yaml as the Template root. +Preserve plain docker compose behavior. +Add x-topo metadata only where it reflects the actual services, hardware requirements, and build arguments. +``` + +After bootstrap, ask the agent to use `topo-template-lint`: + +``` +Use topo-template-lint on this repository. +Validate compose.yaml against the Topo Template Format schema. +Check README alignment, Remoteproc Runtime metadata, and x-topo.args wiring. +``` + +## Validate the final Topo Template + +Check the Compose model and check that the Topo metadata is present: + +```bash +docker compose config +``` + +In the `docker compose config` output, check that the resolved `webapp` service has: + +- `build.context` ending in `/webapp` +- `build.dockerfile` set to `Dockerfile` +- `build.additional_contexts.pte_artifacts` set to `service:pte-artifacts` + +Install `check-jsonschema` if it's not already available: + +{{< tabpane code=true >}} + {{< tab header="macOS" language="shell" >}} +brew install check-jsonschema + {{< /tab >}} + {{< tab header="Linux / WSL" language="shell" >}} +sudo apt update +sudo apt install -y pipx +pipx ensurepath +pipx install check-jsonschema +export PATH="$HOME/.local/bin:$PATH" + {{< /tab >}} +{{< /tabpane >}} + +Validate the root Compose file with the schema in the Topo Template Format: + +```bash +check-jsonschema \ + --schemafile ../topo-template-format/schema/topo-template-format.json \ + compose.yaml +``` + +Review these points: + +- `compose.yaml` contains root-level `x-topo` metadata. +- `x-topo.features` includes `remoteproc-runtime`. +- non-remoteproc services set `platform: linux/arm64`. +- `pte-artifacts` and `runner-artifacts` use `scale: 0`. +- `cm33-runner` uses `runtime: io.containerd.remoteproc.v1`. +- `cm33-runner` has `remoteproc.name: imx-rproc`. +- `webapp` depends on `cm33-runner`. +- `webapp` imports the `.pte` file through `additional_contexts`. +- every `x-topo.args` entry is consumed by Compose interpolation. + +## What you've accomplished and what's next + +You started with two non-Topo, non-Compose projects, made them a standard Compose project, and then converted that Compose project into a Topo Template. You created the web app image, added artifact builds for the ExecuTorch `.pte` model and Cortex-M33 ELF, packaged the firmware as a Remoteproc Runtime service, and exposed the build cache inputs as Topo arguments. + +Next, you'll prepare the FRDM i.MX 93 target, deploy the template with Topo, and run the image classification application. diff --git a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/deploy.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/deploy.md similarity index 52% rename from content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/deploy.md rename to content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/deploy.md index 659e2aa797..2ec4d19baa 100644 --- a/content/learning-paths/cross-platform/deploy-ml-model-to-npu-with-topo/deploy.md +++ b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/deploy.md @@ -1,6 +1,7 @@ --- -title: Deploy the project -weight: 3 +title: Clone and deploy the application with Topo +description: Prepare the NXP FRDM i.MX 93 target, deploy the image classification Topo Template, and validate MobileNetV2 inference through the browser application. +weight: 5 ### FIXED, DO NOT MODIFY layout: learningpathall @@ -8,7 +9,7 @@ layout: learningpathall ## Prepare the target -Before deploying the Template, confirm that the FRDM i.MX 93 board is reachable from your host and that it's ready for deployment: +Before deploying the Topo Template, confirm that the FRDM i.MX 93 board is reachable from your host and that it's ready for deployment: ```bash topo health --target @ @@ -17,7 +18,7 @@ Replace `` with the IP address or hostname of your board. Resolve any errors before continuing. -The target section should include successful checks similar to: +The target section includes successful checks similar to: ```output Host @@ -38,6 +39,7 @@ Hardware Info: ✅ (lscpu) Subsystem Driver (remoteproc): ✅ (imx-rproc) ``` +{{% notice Note %}} If `remoteproc-runtime` is missing, install it with Topo: ```bash @@ -49,14 +51,17 @@ Run the health check again: ```bash topo health --target @ ``` +{{% /notice %}} ## Reserve memory in the device tree -The web application and Cortex-M33 firmware exchange data through reserved physical memory. The target device tree must reserve memory for the model/input buffer and for Ethos-U65. You are now going to modify the device tree and reboot the target so that these modifications take effect. +The web application and Cortex-M33 firmware exchange data through reserved physical memory. The target device tree must reserve memory for the model/input buffer and for the Ethos-U65. This prevents Linux from allocating memory that the firmware and Ethos-U65 need to access by physical address. + +You'll now modify the device tree and reboot the target so that these modifications take effect. {{% notice Warning %}} Back up the board's original device tree before modifying it. The exact boot partition can differ between Linux images, so check the paths on your board before copying files. -{{< /notice >}} +{{% /notice %}} On your host, create a working directory and dump the live device tree from the target: @@ -66,9 +71,7 @@ ssh @ 'cat /sys/firmware/fdt' > devicetree/live.dtb dtc -I dtb -O dts -o devicetree/live.dts devicetree/live.dtb ``` -Open `devicetree/live.dts` in an editor. - -Under `remoteproc-cm33`, add the CM33 power domain if it is not already present: +Open `devicetree/live.dts` in a text editor of your choice. Then, under `remoteproc-cm33`, add the CM33 power domain if it's not already present: ```dts power-domains = <0x61>; @@ -83,7 +86,7 @@ model@c0000000 { }; ``` -Update the Ethos-U reserved-memory node so it is reserved and not reusable: +Update the Ethos-U reserved-memory node so it's reserved and not reusable: ```dts ethosu_region@A8000000 { @@ -100,7 +103,7 @@ Add `iomem=relaxed` to `chosen.bootargs`. For example: bootargs = "clk-imx93.mcore_booted console=ttyLP0,115200 earlycon root=/dev/mmcblk1p2 rootwait rw iomem=relaxed"; ``` -Build the patched device tree: +Return to your host machine terminal and build the patched device tree: ```bash dtc -I dts -O dtb -o devicetree/patched.dtb devicetree/live.dts @@ -124,36 +127,37 @@ sync reboot ``` -After the board reboots, run the Topo health check again from the host: +After the board reboots, run the Topo health check again from the host and verify everything is still correct: ```bash topo health --target @ ``` -## Clone the Template +## Deploy to the board -Clone the Template onto your host: +You can choose to deploy from the original Topo Template, or from the template you built from scratch. If you haven't already cloned the original template, clone it now: ```bash topo clone https://github.com/Arm-Examples/topo-imx93-npu-deployment.git ``` -Topo prompts for optional build cache image arguments: +Topo prompts for optional build cache image arguments. Accept the defaults unless you have your own cache images. -```output -EXECUTORCH_BASE_CACHE_IMAGE -IMX93_RUNNER_BUILD_CACHE_IMAGE -``` +{{% notice Note %}} +If you build without cache images, the first build can take a long time and requires about 25 GB of free disk space. The first build involves downloading and building ExecuTorch, the Arm GNU toolchain, MCUX SDK components, RPMsg-Lite, and the Cortex-M33 runner sources. Later builds are faster when Docker can reuse local cache layers or import the configured GHCR cache layers. +{{% /notice %}} -Accept the defaults unless you have your own cache images. - -Enter the project directory: +Then `cd` into the correct directory: ```bash cd topo-imx93-npu-deployment ``` -## Deploy to the board +Or: + +```bash +cd new-topo-npu-template +``` Deploy the project to your target: @@ -161,8 +165,6 @@ Deploy the project to your target: topo deploy --target @ ``` -If not pulling from the cache, the first build can take a long time and requires about 25 GB of free disk space. It downloads and builds ExecuTorch, the Arm GNU toolchain, MCUX SDK components, RPMsg-Lite, and the Cortex-M33 runner sources. Later builds are faster when Docker can reuse local cache layers or import the configured GHCR cache layers. - During deployment, Topo builds the required images, transfers them to the target, starts the Cortex-M33 firmware through `remoteproc-runtime`, and starts the web application. When deployment succeeds, the output includes a successful service startup. You can also check the deployed services: @@ -171,25 +173,24 @@ When deployment succeeds, the output includes a successful service startup. You topo ps --target @ ``` -## Open the web application - -Open the web application in a browser: +The output shows a process on both the Cortex-M33 and the Linux Host, and is similar to: ```output -http://:3001 +Image Status Processing Domain Address +topo-imx93-npu-deployment-cm33-runner Up 50 minutes imx-rproc +topo-imx93-npu-deployment-webapp Up 50 minutes Linux Host imx93-scorpio.cambridge.arm.com:3001, [::]:3001% ``` -The application shows: +## Open the web application -- an image selector -- a **Classify** button -- board prerequisite checks -- classification results -- an expandable analysis section with runtime details +Open the web application in a browser: -Select an image from an ImageNet-supported class, then click **Classify**. A successful run returns top-1 and top-5 ImageNet classifications. +``` +http://:3001 +``` -If you need to use a different target port, set `WEBAPP_PORT` when deploying: +{{% notice Note %}} +If you need to use a different target port, set `WEBAPP_PORT` when deploying. For example: ```bash WEBAPP_PORT=3002 topo deploy --target @ @@ -200,13 +201,30 @@ Then open: ```output http://:3002 ``` +{{% /notice %}} + +The application shows: -You should see something similar to: +- an image selector +- a **Classify** button +- board prerequisite checks +- classification results +- an expandable analysis section with runtime details + +![Screenshot of the web interface running on an Arm-based target, showing an image and the model response. This confirms successful deployment and provides a visual reference for the expected result.#center](topo_npu_classifier.png "Image classification web app showing correctly classified German Shepherd") +When you choose an image in the browser and select **Classify**, the web application: -![Screenshot of the web interface running on an Arm-based target, showing an image and the model response. This confirms successful deployment and provides a visual reference for the expected result.#center](topo_npu_classifier.webp "Image classification as seen in the web app") +1. Resizes and normalizes the image to classify into an input tensor compatible with the [MobileNetV2](https://arxiv.org/abs/1801.04381) model. +2. Writes the ExecuTorch `.pte` program and input tensor into reserved physical memory. +3. Sends a `RUN` command to the Cortex-M33 runner over `RPMsg`. +4. Waits for the Cortex-M33 firmware to run inference using Ethos-U65 acceleration. +5. Displays the top-1 and top-5 ImageNet classification results in the browser. + +Try this out with an image from an ImageNet-supported class. ## What you've accomplished -You have prepared an FRDM i.MX 93 board for shared-memory NPU inference, deployed the `topo-imx93-npu-deployment` Template with Topo, started Cortex-M33 firmware through `remoteproc-runtime`, and used a browser-based application to run MobileNetV2 classification with Ethos-U65 acceleration. -Next, you will review how this project is structured as a Topo Template. +You've prepared an FRDM i.MX 93 board for shared-memory NPU inference, deployed the `topo-imx93-npu-deployment` template with Topo, and started Cortex-M33 firmware through `remoteproc-runtime`. You used a browser-based application to stage the ExecuTorch `.pte` program and input tensor for MobileNetV2 classification with Ethos-U65 acceleration. + +You can now use the deployed application as a reference for your own heterogeneous Arm applications, or adapt the model, firmware runner, web interface, or Topo metadata for another target. diff --git a/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/overview.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/overview.md new file mode 100644 index 0000000000..d9c9467c65 --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/overview.md @@ -0,0 +1,74 @@ +--- +title: Understand the architecture of the machine learning application +description: Review how the Topo Template deploys a Cortex-A web application, Cortex-M33 firmware, and Ethos-U65 NPU acceleration for image classification on NXP FRDM i.MX 93. +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## What you'll deploy + +[Topo](https://github.com/arm/topo) is an open-source command-line tool developed by Arm that you can use to deploy projects to an Arm-based Linux target over SSH. Topo builds container images on the host, transfers them to the target, and starts the services on the target. Topo Templates are the standardized format for deploying projects with Topo. + +In this Learning Path, you'll deploy the [topo-imx93-npu-deployment](https://github.com/Arm-Examples/topo-imx93-npu-deployment) Topo Template to an NXP FRDM i.MX 93 board, and understand how this Topo Template was created. + +The Topo Template builds and deploys a browser-based MobileNetV2 image classifier. The user interface runs on the Cortex-A (Linux) side of the SoC. The inference runner is packaged as Cortex-M33 firmware and is started by [remoteproc-runtime](https://github.com/arm/remoteproc-runtime). The model is exported to an [ExecuTorch](https://docs.pytorch.org/executorch/stable/index.html) `.pte` [file](https://docs.pytorch.org/executorch/stable/pte-file-format.html) for Ethos-U65 NPU acceleration. + +## Prerequisites + +Before getting started, ensure that your i.MX 93 board is set up with Linux and accessible over SSH. Use the Learning Path [Use Linux on the NXP FRDM i.MX 93 board](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/linux-nxp-board/) as a guide. + +Complete the Learning Path [Deploy containerized workloads to Arm-based Linux targets with Topo](https://learn.arm.com/learning-paths/cross-platform/deploy-containerized-workloads-with-topo/) to learn how to install Topo, run host and target health checks, inspect a target, list compatible Topo Templates, and deploy a containerized workload. + +## (Optional) Background reading + +To learn more about Topo Templates, and how to create a basic Topo Template for a web application, complete the introductory [Create and deploy a custom Topo Template](https://learn.arm.com/learning-paths/cross-platform/create-your-own-topo-templates/) Learning Path. + +To learn more about the model, firmware, and [Ethos-U65](https://www.arm.com/products/silicon-ip-cpu/ethos/ethos-u65) execution flow behind this NPU example, see the [Deploy ExecuTorch firmware on NXP FRDM i.MX 93 for Ethos-U65 acceleration](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/) Learning Path. + +## What the template does + +Deploying the Topo Template starts two runtime services on the target: + +- `webapp`: Web application running on the Cortex-A Linux host. It receives an image input from the user and outputs the results of the ML image classification. +- `cm33-runner`: Cortex-M33 firmware that receives the image tensor from the web application, runs the compiled MobileNetV2 ExecuTorch `.pte` program, delegates supported operators to the Ethos-U65 NPU, and runs non-delegated operators on the Cortex-M33 CPU. + +## System architecture + +The deployed application spans three processing domains on the i.MX 93: + +- Cortex-A Linux host: runs Docker, Topo-deployed containers, the Flask web app, and the Linux `remoteproc` and `RPMsg` interfaces. +- Cortex-M33 firmware domain: runs the ExecuTorch runner firmware loaded by `remoteproc-runtime`. +- Ethos-U65 NPU: accelerates delegated neural network operators from the ExecuTorch MobileNetV2 program. + +The high-level data flow is: + +```output +Browser + | + v +Flask web application on Cortex-A Linux + | + | writes .pte file and input tensor to reserved memory + | sends RUN over RPMsg + v +Cortex-M33 ExecuTorch runner firmware + | + | loads the .pte program from reserved memory + | delegates supported operators + v +Ethos-U65 NPU + | + v +Cortex-M33 returns classification results over RPMsg + | + v +Browser displays ImageNet top-1 and top-5 results +``` + +## What you've learned and what's next + +You now understand that the Topo Template deploys a Cortex-A web application, a Cortex-M33 ExecuTorch runner, and Ethos-U65 NPU acceleration as one heterogeneous application. You've also seen how inference uses reserved memory for the `.pte` program and input tensor, with `RPMsg` carrying commands and results between Cortex-A and Cortex-M33. + +Next, you'll review the toolchains and runtime interfaces used by the Topo Template. diff --git a/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.png b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.png new file mode 100644 index 0000000000..f744e12c64 Binary files /dev/null and b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/topo_npu_classifier.png differ diff --git a/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md new file mode 100644 index 0000000000..aaabebb3da --- /dev/null +++ b/content/learning-paths/embedded-and-microcontrollers/deploy-ml-model-to-npu-with-topo/what-are-the-toolchains.md @@ -0,0 +1,87 @@ +--- +title: Understand the toolchains used in the Topo Template +description: Identify the build and runtime components that connect ExecuTorch, remoteproc-runtime, RPMsg, reserved memory, and the Flask web application in the Topo Template. +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Understand the build and runtime components + +The `topo-imx93-npu-deployment` Topo Template combines several toolchains. Topo hides much of the deployment plumbing, but it's useful to understand what's being built and where each component runs. + +### ExecuTorch + +[ExecuTorch](https://docs.pytorch.org/executorch/stable/index.html) is PyTorch's runtime for deploying PyTorch models to edge devices. By using different backends within ExecuTorch, you can target specific hardware. For example, you can target Ethos-U65 by using the Ethos-U backend. + +To learn more about how the MobileNetV2 model was exported from PyTorch to ExecuTorch and delegated to the Ethos-U, see [Build ExecuTorch models for Ethos-U65](https://learn.arm.com/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/7-build-executorch-pte/). + +In this Topo Template, ExecuTorch is used in two places: + +- At build time, the template exports a MobileNetV2 model to an ExecuTorch `.pte` program. +- At run time, the Cortex-M33 firmware loads and executes that `.pte` program. + +The export pipeline targets `ethos-u65-256`, which means the Ethos-U65 has 256 multiply-accumulate (MAC) units. The model is quantized and lowered so supported neural network operators can be delegated to the Ethos-U65 NPU. + +The generated file is `mv2_ethosu65_256.pte`. + +The web application includes this `.pte` file in its container image. During inference, it writes the file into the reserved physical memory range starting at `0xC0000000`, where the Cortex-M33 runner can read it. + +### Cortex-M33 firmware runner + +The firmware runner is built as `executorch_runner_cm33.elf`. + +This firmware runs on the Cortex-M33 core. It waits for commands coming from the Linux web application over `RPMsg`, reads input image tensors from reserved memory, runs inference through ExecuTorch, and writes classification output back over `RPMsg`. + +The Topo Template packages the firmware as the entrypoint of the `cm33-runner` image: + +```yaml +cm33-runner: + runtime: io.containerd.remoteproc.v1 + annotations: + remoteproc.name: imx-rproc +``` + +The `runtime: io.containerd.remoteproc.v1` setting tells containerd to use the remote processor runtime instead of the normal Linux container runtime. The `remoteproc.name` annotation identifies the target remote processor driver, `imx-rproc`. + +### remoteproc-runtime + +Linux includes a `remoteproc` framework for loading and controlling auxiliary processors such as the Cortex-M33 on the i.MX 93. `remoteproc-runtime` adds an Open Container Initiative (OCI) interface on top of this framework, allowing firmware to be packaged and launched using container tooling. + +Topo uses `remoteproc-runtime` when deploying the `cm33-runner` service. The deployment flow is: + +1. Topo builds the `runner-runtime` image containing `executorch_runner_cm33.elf`. +2. Topo starts the image on the target. +3. containerd uses `io.containerd.remoteproc.v1`. +4. `remoteproc-runtime` passes the ELF file to the Linux `remoteproc` driver. +5. The kernel loads the ELF segments and releases the Cortex-M33. + +The target must pass the `Remoteproc Runtime`, `Remoteproc Shim`, and `Subsystem Driver (remoteproc)` checks in `topo health`. + +### RPMsg + +`RPMsg` is the communication channel between the Cortex-A Linux application and the Cortex-M33 firmware. The web application sends a `RUN` command over a `/dev/ttyRPMSG*` device. The firmware replies with status and classification output. + +If the deployment succeeds but classification times out, inspect the web app's board checks and the target's `RPMsg` devices. The application expects an `RPMsg` TTY to appear after the Cortex-M33 firmware starts. + +### Shared reserved memory + +The web application and firmware exchange model and input data through reserved physical memory. The Topo Template expects the target device tree to reserve: + +- `model@c0000000`: 4 MiB for the ExecuTorch `.pte` file and input tensor. +- `ethosu_region@A8000000`: 128 MiB for Ethos-U65 use. + +The web application checks these ranges at startup through `/proc/device-tree`. It also checks for `/dev/mem`, `/dev/ethosu0`, the `imx-rproc` remote processor, the `.pte` file, and ImageNet labels. + +### Web application + +The `webapp` service is a Python Flask application. The application serves the browser UI and preprocesses selected images. It stages the `.pte` program and input tensor in reserved memory, sends inference commands over `RPMsg`, and renders the ImageNet top-1 and top-5 results. + +By default, the service publishes port `3001` on the target and forwards it to container port `3000`. + +## What you've learned and what's next + +You now understand the major toolchains and runtime interfaces used by the Topo Template: ExecuTorch, the Cortex-M33 firmware runner, remoteproc-runtime, RPMsg, reserved memory, and the Flask web application. You've also seen how the web application stages the `.pte` program and input data in reserved memory before sending inference commands to the Cortex-M33 firmware. + +Next, you'll build the Topo Template from the base projects by adding the Compose services, build artifacts, Remoteproc Runtime metadata, and Topo arguments. diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md index 22bf1be008..ad6fe29e87 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/_index.md @@ -1,5 +1,6 @@ --- title: Device-to-Device communication with Device Connect +description: Learn how to connect simulated edge devices directly with Device Connect and build a sensor-to-monitor workflow without cloud infrastructure. minutes_to_complete: 25 diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md index c0f303ba31..28f6102dd4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/background.md @@ -1,5 +1,6 @@ --- title: Why device-to-device at the edge +description: Understand when device-to-device communication is useful at the edge and how Device Connect supports local device workflows. weight: 2 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md index d75400f68f..b0c9069c71 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/d2d-setup.md @@ -1,5 +1,6 @@ --- title: Set up D2D communication between a sensor and a monitor +description: Set up Device Connect for a simulated sensor and monitor so the devices can discover each other and exchange data locally. weight: 4 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md index b86e614699..83c0a1845e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-d2d/overview.md @@ -1,5 +1,6 @@ --- title: Device Connect developer model +description: Review the Device Connect Edge SDK developer model and how capabilities, devices, and applications interact. weight: 3 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md index ef2cc8c3e5..16381b7569 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/background.md @@ -1,5 +1,6 @@ --- title: Learn when to use Device Connect server for multi-network deployments +description: Understand when Device Connect server is useful for multi-network edge deployments and how it extends device-to-device workflows. weight: 2 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md index 88a8340668..527e055697 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-server/server-setup.md @@ -1,5 +1,6 @@ --- title: Run devices and an orchestrating agent on a Device Connect server +description: Provision Device Connect server credentials, run example devices, and connect an orchestrating agent across networks. weight: 3 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/background.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/background.md index 5d17d94e41..cdf98bcf62 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/background.md @@ -1,5 +1,6 @@ --- title: Learn Device Connect and Strands architecture for edge devices +description: Review the Device Connect and Strands architecture that lets AI agents discover and control edge devices. weight: 2 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-example.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-example.md index 85908694f3..6170af890c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-example.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-example.md @@ -1,5 +1,6 @@ --- title: Run device discovery and agent control examples +description: Run local Device Connect examples that demonstrate device discovery and agent control with simulated edge devices. weight: 4 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-infra-example.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-infra-example.md index 4bc0f8ea70..9239a18c5a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-infra-example.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/run-infra-example.md @@ -1,5 +1,6 @@ --- title: Run with full Device Connect infrastructure (optional) +description: Run the optional Device Connect infrastructure example to connect agents and devices through shared services. weight: 5 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/setup.md b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/setup.md index 6e9c4f9eec..97769ce850 100644 --- a/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/device-connect-strands/setup.md @@ -1,5 +1,6 @@ --- title: Set up the Device Connect and Strands developer environment +description: Install the tools and dependencies needed to run Device Connect and Strands examples for edge device orchestration. weight: 3 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/docker/dockerfile.md b/content/learning-paths/embedded-and-microcontrollers/docker/dockerfile.md index ee5f8cb2f6..3a2aff79ea 100644 --- a/content/learning-paths/embedded-and-microcontrollers/docker/dockerfile.md +++ b/content/learning-paths/embedded-and-microcontrollers/docker/dockerfile.md @@ -1,6 +1,7 @@ --- # User change title: "Create Dockerfile and build docker image" +description: Create a Dockerfile for Arm Compiler for Embedded and FVP tools, build the image, and test the containerized workflow. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/edge/connect-and-set-up-arduino.md b/content/learning-paths/embedded-and-microcontrollers/edge/connect-and-set-up-arduino.md index 1ccc697c5c..122f2b14cb 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge/connect-and-set-up-arduino.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge/connect-and-set-up-arduino.md @@ -1,5 +1,6 @@ --- title: Board connection and IDE setup +description: Connect the Arduino Nano RP2040 board and configure the Arduino IDE so it is ready for TinyML deployment. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge/overview.md b/content/learning-paths/embedded-and-microcontrollers/edge/overview.md index eba2464dc5..287053f21f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge/overview.md @@ -1,5 +1,6 @@ --- title: Overview +description: Review the Edge AI workflow for collecting audio data, training a model, and deploying it to an Arm microcontroller board. weight: 2 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge/program-and-deployment.md b/content/learning-paths/embedded-and-microcontrollers/edge/program-and-deployment.md index a69435988d..e11bb8314f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge/program-and-deployment.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge/program-and-deployment.md @@ -1,5 +1,6 @@ --- title: Program your first TinyML device +description: Flash the TinyML firmware to the Arduino Nano RP2040 and verify that voice commands control the LEDs. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge/software-edge-impulse.md b/content/learning-paths/embedded-and-microcontrollers/edge/software-edge-impulse.md index 64e7fe52b7..165c327ab9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge/software-edge-impulse.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge/software-edge-impulse.md @@ -1,5 +1,6 @@ --- title: Train and deploy a TinyML audio classifier with Edge Impulse +description: Use Edge Impulse to collect audio samples, train a TinyML classifier, and generate deployment code for the board. weight: 3 # FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/cleanup.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/cleanup.md index 0d935b2a47..68a5933e91 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/cleanup.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/cleanup.md @@ -1,5 +1,6 @@ --- title: Clean up AWS resources +description: Remove AWS IoT Greengrass and related cloud resources created for the Edge Impulse deployment when the project is complete. weight: 11 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/customcomponentdeployment.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/customcomponentdeployment.md index 2cd7745e59..73f32ea86e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/customcomponentdeployment.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/customcomponentdeployment.md @@ -1,5 +1,6 @@ --- title: Deploy the component to your edge device +description: Deploy the Edge Impulse Greengrass component to the selected Arm edge device and confirm the component is running. weight: 8 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulsecustomcomponentinstall.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulsecustomcomponentinstall.md index ba9625d5bc..eb62bd18d1 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulsecustomcomponentinstall.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulsecustomcomponentinstall.md @@ -1,5 +1,6 @@ --- title: Create the Edge Impulse Greengrass component +description: Create the AWS IoT Greengrass custom component that installs and runs the Edge Impulse model on the edge device. weight: 7 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulseprojectbuild.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulseprojectbuild.md index dd2d64aad6..216eb5377e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulseprojectbuild.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/edgeimpulseprojectbuild.md @@ -1,5 +1,6 @@ --- title: Set up your Edge Impulse project +description: Create an Edge Impulse project, train the model, and prepare the deployment artifacts for AWS IoT Greengrass. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/greengrassinstallation.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/greengrassinstallation.md index d3c37cbff9..70a7058b98 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/greengrassinstallation.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/greengrassinstallation.md @@ -1,5 +1,6 @@ --- title: Install AWS IoT Greengrass +description: Install AWS IoT Greengrass on the Arm edge device and configure the credentials needed for component deployment. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetup.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetup.md index 459e2eee05..a0632c34b9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetup.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetup.md @@ -1,5 +1,6 @@ --- title: Select and set up your edge device +description: Choose an Arm edge platform and complete the hardware setup required for the Edge Impulse Greengrass workflow. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupec2.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupec2.md index b00941a1df..bc5b56f14a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupec2.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupec2.md @@ -1,5 +1,6 @@ --- hide_from_navpane: true +description: Launch an Ubuntu AWS EC2 Arm instance and install the dependencies needed to simulate an Edge Impulse Greengrass device. ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupnvidiajetson.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupnvidiajetson.md index 4a94766dc9..54494c0871 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupnvidiajetson.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupnvidiajetson.md @@ -1,5 +1,6 @@ --- hide_from_navpane: true +description: Prepare an Nvidia Jetson device with JetPack and the dependencies required for Edge Impulse and AWS IoT Greengrass. ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupqc6490ubuntu.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupqc6490ubuntu.md index 640393f580..1fb3ebb149 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupqc6490ubuntu.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetupqc6490ubuntu.md @@ -1,5 +1,6 @@ --- hide_from_navpane: true +description: Set up a Qualcomm Dragonwing QC6490 board with Ubuntu and install the packages needed for Edge Impulse Greengrass. ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetuprpi5.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetuprpi5.md index 096adfa461..55b1aaf922 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetuprpi5.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/hardwaresetuprpi5.md @@ -1,5 +1,6 @@ --- hide_from_navpane: true +description: Configure a Raspberry Pi 5 with Raspberry Pi OS and install the dependencies needed for Edge Impulse Greengrass deployment. ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/noncameracustomcomponent.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/noncameracustomcomponent.md index fcc24a2f4c..1966ceeb07 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/noncameracustomcomponent.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/noncameracustomcomponent.md @@ -1,5 +1,6 @@ --- hide_from_navpane: true +description: Create a non-camera Greengrass component that provides sample images to the Edge Impulse runner on devices without cameras. ### FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/overview.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/overview.md index 0d7dea64e6..e1ec9a3920 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/overview.md @@ -1,5 +1,6 @@ --- title: Overview of Edge Impulse and AWS IoT Greengrass +description: Understand how Edge Impulse models are packaged as AWS IoT Greengrass components for deployment to Arm-based edge devices. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/running.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/running.md index 3316c505e4..8231549016 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/running.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/running.md @@ -1,5 +1,6 @@ --- title: Verify inference and view results +description: Verify that the deployed Edge Impulse model runs on the edge device and view live inference results in the browser. weight: 9 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/secretmanagersetup.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/secretmanagersetup.md index 2d715f9148..dd8ddf897b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/secretmanagersetup.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/secretmanagersetup.md @@ -1,5 +1,6 @@ --- title: Store your API key in AWS Secrets Manager +description: Store the Edge Impulse API key in AWS Secrets Manager so Greengrass components can access it securely. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/summary.md b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/summary.md index 4dd3cf25ca..c1846f025f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/summary.md +++ b/content/learning-paths/embedded-and-microcontrollers/edge_impulse_greengrass/summary.md @@ -1,5 +1,6 @@ --- title: Command and metrics reference +description: Review the commands, metrics, and configuration values used throughout the Edge Impulse Greengrass deployment. weight: 10 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/build_nn.md b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/build_nn.md index 8296e75c8d..4bb4d2bdfb 100644 --- a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/build_nn.md +++ b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/build_nn.md @@ -1,6 +1,7 @@ --- # User change title: Build an image classification NN model trained with the CIFAR-10 dataset +description: Train an image classification model with the CIFAR-10 dataset and prepare it for deployment with STM32 tools. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/deploy_nn.md b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/deploy_nn.md index d740e10fa1..d1131ba245 100644 --- a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/deploy_nn.md +++ b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/deploy_nn.md @@ -1,6 +1,7 @@ --- # User change title: Deploy the image classification NN model on STM32 +description: Import the trained image classification model into STM32CubeMX and generate code for the STM32 board. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/run_nn.md b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/run_nn.md index 75d94ac8c8..cec4f2ef55 100644 --- a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/run_nn.md +++ b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/run_nn.md @@ -1,6 +1,7 @@ --- # User change title: Run the image classification NN model on STM32 +description: Run the image classification model on the STM32 development board and verify inference results from the deployed firmware. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/setup.md b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/setup.md index b647cdd890..80dd33ee66 100644 --- a/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/img_nn_stcube/setup.md @@ -1,6 +1,7 @@ --- # User change title: Prepare environment +description: Install Anaconda and the required Python packages for building and deploying the STM32 image classification model. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/intro/background.md b/content/learning-paths/embedded-and-microcontrollers/intro/background.md index 3797d7b7ec..8b36cdaa86 100644 --- a/content/learning-paths/embedded-and-microcontrollers/intro/background.md +++ b/content/learning-paths/embedded-and-microcontrollers/intro/background.md @@ -1,6 +1,7 @@ --- layout: learningpathall title: Arm in Microcontrollers +description: Understand how Arm Cortex-M processors are used in microcontrollers and where they fit in embedded system design. weight: 2 --- diff --git a/content/learning-paths/embedded-and-microcontrollers/intro/find-hardware.md b/content/learning-paths/embedded-and-microcontrollers/intro/find-hardware.md index 6cb08bf4fb..2adaab8575 100644 --- a/content/learning-paths/embedded-and-microcontrollers/intro/find-hardware.md +++ b/content/learning-paths/embedded-and-microcontrollers/intro/find-hardware.md @@ -1,6 +1,7 @@ --- layout: learningpathall title: Find Arm hardware +description: Identify Arm-based microcontroller development boards and choose hardware for embedded software projects. weight: 3 --- diff --git a/content/learning-paths/embedded-and-microcontrollers/intro/resources.md b/content/learning-paths/embedded-and-microcontrollers/intro/resources.md index 603b11e864..35aa6bfc97 100644 --- a/content/learning-paths/embedded-and-microcontrollers/intro/resources.md +++ b/content/learning-paths/embedded-and-microcontrollers/intro/resources.md @@ -1,6 +1,7 @@ --- layout: learningpathall title: Other learning resources +description: Find additional Arm microcontroller documentation, courses, and examples to continue embedded software learning. weight: 4 --- ## Reading resources diff --git a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/1-overview.md b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/1-overview.md index 2fa725c9fe..9e505ded4d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/1-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/1-overview.md @@ -1,5 +1,6 @@ --- title: Overview +description: Review TinyML concepts, Arm-based edge devices, and the ExecuTorch workflow used in the rest of the Learning Path. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/2-env-setup.md b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/2-env-setup.md index 0c24e883ad..ea1a5d3f7d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/2-env-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/2-env-setup.md @@ -1,6 +1,7 @@ --- # User change title: "Install ExecuTorch" +description: Install ExecuTorch and its dependencies so you can convert and run PyTorch models for TinyML on Arm targets. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/3-env-setup-fvp.md b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/3-env-setup-fvp.md index 61786ed292..70ed054d00 100644 --- a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/3-env-setup-fvp.md +++ b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/3-env-setup-fvp.md @@ -1,6 +1,7 @@ --- # User change title: "Set up the Corstone-320 FVP" +description: Install and configure the Corstone-320 Fixed Virtual Platform for running TinyML examples without physical hardware. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/4-build-model.md b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/4-build-model.md index a976b0063a..377d40697c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/4-build-model.md +++ b/content/learning-paths/embedded-and-microcontrollers/introduction-to-tinyml-on-arm/4-build-model.md @@ -1,6 +1,7 @@ --- # User change title: "Build a simple PyTorch model" +description: Build a small PyTorch model and prepare it for ExecuTorch deployment on the Corstone-320 FVP. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/iot-sdk/aws.md b/content/learning-paths/embedded-and-microcontrollers/iot-sdk/aws.md index 882bc9c1e6..cd6233348b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/iot-sdk/aws.md +++ b/content/learning-paths/embedded-and-microcontrollers/iot-sdk/aws.md @@ -1,6 +1,7 @@ --- # User change title: Enable AWS connectivity +description: Enable AWS connectivity in the Open-IoT-SDK example so the application can communicate with AWS IoT services. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/iot-sdk/openiot.md b/content/learning-paths/embedded-and-microcontrollers/iot-sdk/openiot.md index 02f2289988..8f7204b6ea 100644 --- a/content/learning-paths/embedded-and-microcontrollers/iot-sdk/openiot.md +++ b/content/learning-paths/embedded-and-microcontrollers/iot-sdk/openiot.md @@ -1,6 +1,7 @@ --- # User change title: Build and run Open-IoT-SDK examples +description: Build Open-IoT-SDK examples and run them on Arm Virtual Hardware to validate the IoT software stack. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/2setup.md b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/2setup.md index 4a57b23819..d9980ff787 100644 --- a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/2setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/2setup.md @@ -1,5 +1,6 @@ --- title: Set up your Jetson Orin Nano +description: Prepare the Jetson Orin Nano hardware, camera, and software environment for image classification and object detection. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/3docker.md b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/3docker.md index 5ce88fdc4e..58da1c3e81 100644 --- a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/3docker.md +++ b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/3docker.md @@ -1,5 +1,6 @@ --- title: Launch the image classification Docker container +description: Download and run the image classification Docker container on Jetson Orin Nano to test the accelerated inference setup. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/4object.md b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/4object.md index 4821299360..60237bfddd 100644 --- a/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/4object.md +++ b/content/learning-paths/embedded-and-microcontrollers/jetson_object_detection/4object.md @@ -1,5 +1,6 @@ --- title: Detect objects in video and images +description: Run object detection on images and live video with Jetson Orin Nano and verify DetectNet output. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/keilstudiocloud/2build.md b/content/learning-paths/embedded-and-microcontrollers/keilstudiocloud/2build.md index 2feedd8109..9c29ff1f07 100644 --- a/content/learning-paths/embedded-and-microcontrollers/keilstudiocloud/2build.md +++ b/content/learning-paths/embedded-and-microcontrollers/keilstudiocloud/2build.md @@ -1,6 +1,7 @@ --- # User change title: "Work with an example project" +description: Import an example project into Keil Studio Cloud, build it, and run a basic debug session in the browser. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/1-overview.md b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/1-overview.md index 8a80672d89..0de840d990 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/1-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/1-overview.md @@ -1,5 +1,6 @@ --- title: Set up the board +description: Boot and inspect the NXP FRDM i.MX 93 board so it is ready for Linux-based ML development on Arm. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/3-create-super-user.md b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/3-create-super-user.md index f3f352dcf1..9a58e47c92 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/3-create-super-user.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/3-create-super-user.md @@ -1,6 +1,7 @@ --- # User change title: "Set up a Linux user and connect to WiFi" +description: Create a non-root Linux user with sudo access and configure WiFi connectivity on the NXP FRDM i.MX 93 board. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/4-enable-wifi.md b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/4-enable-wifi.md index ff190d822b..8161215e44 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/4-enable-wifi.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/4-enable-wifi.md @@ -1,6 +1,7 @@ --- # User change title: "Transfer files to the board" +description: Transfer files to the NXP FRDM i.MX 93 board over the network using WiFi and secure copy. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/7-enable-persistent-wifi.md b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/7-enable-persistent-wifi.md index 98aee667d1..0a44c1cd0a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/7-enable-persistent-wifi.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-nxp-board/7-enable-persistent-wifi.md @@ -1,6 +1,7 @@ --- # User change title: "(Optional) Enable Persistent WiFi" +description: Configure persistent WiFi on the NXP FRDM i.MX 93 board so networking reconnects after reboot. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/debug.md b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/debug.md index 485052e3e7..4974324418 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/debug.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/debug.md @@ -1,5 +1,6 @@ --- title: Debug the software stack +description: Use Arm Development Studio to debug Trusted Firmware-A and the Linux kernel while the software stack runs on an FVP. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/intro.md b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/intro.md index e9590f5331..b79942e7c4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/intro.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/intro.md @@ -1,5 +1,6 @@ --- title: Introduction to Arm Fixed Virtual Platforms (FVPs) +description: Understand Arm Fixed Virtual Platforms and how they support Linux software development before hardware is available. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/modify.md b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/modify.md index 74c2557e78..389c4da53b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/modify.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/modify.md @@ -1,5 +1,6 @@ --- title: Modify the device tree for CPU FVPs +description: Update the device tree so the Linux software stack matches the selected Arm CPU FVP model. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/run.md b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/run.md index 12945e535a..43e9a9f9c3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/run.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/run.md @@ -1,5 +1,6 @@ --- title: Run the Linux software stack on an FVP +description: Launch the Linux software stack on an Arm FVP and verify that the virtual platform boots successfully. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/steps.md b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/steps.md index c7f2e46a82..d29ab178ad 100644 --- a/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/steps.md +++ b/content/learning-paths/embedded-and-microcontrollers/linux-on-fvp/steps.md @@ -1,5 +1,6 @@ --- title: Configure Trusted Firmware-A build flags to include cpu_ops support +description: Configure Trusted Firmware-A build flags for cpu_ops support and rebuild the Linux software stack for the FVP. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/llama-python-cpu/llama-python-chatbot.md b/content/learning-paths/embedded-and-microcontrollers/llama-python-cpu/llama-python-chatbot.md index 5ed148deb5..aa72e49f03 100644 --- a/content/learning-paths/embedded-and-microcontrollers/llama-python-cpu/llama-python-chatbot.md +++ b/content/learning-paths/embedded-and-microcontrollers/llama-python-cpu/llama-python-chatbot.md @@ -1,5 +1,6 @@ --- title: Run a Large Language Model (LLM) chatbot on a Raspberry Pi 5 +description: Install llama.cpp Python bindings on Raspberry Pi 5, download an LLM, and run an interactive chatbot locally. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/2_porting_methodology.md b/content/learning-paths/embedded-and-microcontrollers/migration/2_porting_methodology.md index dfabe1322c..1fb08a8f5c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/2_porting_methodology.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/2_porting_methodology.md @@ -1,6 +1,7 @@ --- # User change title: "Porting methodology" +description: Apply a structured porting methodology for moving Linux applications from x86_64 to Arm AArch64. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/3_porting_analysis.md b/content/learning-paths/embedded-and-microcontrollers/migration/3_porting_analysis.md index 79206f0f00..c8a0f650ec 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/3_porting_analysis.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/3_porting_analysis.md @@ -1,6 +1,7 @@ --- # User change title: "Porting analysis" +description: Analyze source code, dependencies, and build settings to identify issues before porting an application to Arm. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/4_development_environment.md b/content/learning-paths/embedded-and-microcontrollers/migration/4_development_environment.md index 16aeab6e45..c04bd8fc05 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/4_development_environment.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/4_development_environment.md @@ -1,6 +1,7 @@ --- # User change title: "Development environment" +description: Set up the compilers, libraries, and tools needed to build and test the application on Arm Linux. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/5_application_porting.md b/content/learning-paths/embedded-and-microcontrollers/migration/5_application_porting.md index 7200521aca..73edb95f0f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/5_application_porting.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/5_application_porting.md @@ -1,6 +1,7 @@ --- # User change title: "Application porting" +description: Port application code to Arm by addressing architecture assumptions, compiler intrinsics, and build configuration differences. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/6_run_evaluate.md b/content/learning-paths/embedded-and-microcontrollers/migration/6_run_evaluate.md index 256a3ea14c..dc12260923 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/6_run_evaluate.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/6_run_evaluate.md @@ -1,6 +1,7 @@ --- # User change title: "Run and evaluate" +description: Run the ported application on Arm, evaluate behavior and performance, and compare results with the original environment. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/migration/7_alternative.md b/content/learning-paths/embedded-and-microcontrollers/migration/7_alternative.md index c0b37255ff..f14bcda03b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/migration/7_alternative.md +++ b/content/learning-paths/embedded-and-microcontrollers/migration/7_alternative.md @@ -1,6 +1,7 @@ --- # User change title: "Evaluating performance on Arm hardware (Optional)" +description: Optionally evaluate the ported workload on Arm hardware and use the results to guide further optimization. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/mlek/build.md b/content/learning-paths/embedded-and-microcontrollers/mlek/build.md index 4c82e28353..598a2bc69f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/mlek/build.md +++ b/content/learning-paths/embedded-and-microcontrollers/mlek/build.md @@ -1,6 +1,7 @@ --- # User change title: "Build the ML Evaluation Kit examples" +description: Build ML Evaluation Kit examples for the selected target so they are ready to run on Arm virtual hardware. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/mlek/fvp.md b/content/learning-paths/embedded-and-microcontrollers/mlek/fvp.md index 49b5557445..97a20851e8 100644 --- a/content/learning-paths/embedded-and-microcontrollers/mlek/fvp.md +++ b/content/learning-paths/embedded-and-microcontrollers/mlek/fvp.md @@ -1,6 +1,7 @@ --- # User change title: "Install Arm Ecosystem FVP" +description: Install the Arm Ecosystem FVP and configure it as the execution target for ML Evaluation Kit examples. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/mlek/run.md b/content/learning-paths/embedded-and-microcontrollers/mlek/run.md index a0f20db865..2e6d037859 100644 --- a/content/learning-paths/embedded-and-microcontrollers/mlek/run.md +++ b/content/learning-paths/embedded-and-microcontrollers/mlek/run.md @@ -1,6 +1,7 @@ --- # User change title: "Run the examples on the FVP" +description: Run ML Evaluation Kit examples on the Arm Ecosystem FVP and inspect the model output. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/intro.md b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/intro.md index 46e4eb6405..d0137e874f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/intro.md +++ b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/intro.md @@ -1,5 +1,6 @@ --- title: Overview +description: Review ML Evaluation Kit concepts and the Arm hardware options available for embedded machine learning development. weight: 2 diff --git a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/platforms.md b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/platforms.md index 740086950b..f2d4074a0c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/platforms.md +++ b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/platforms.md @@ -1,5 +1,6 @@ --- title: Development platforms +description: Compare physical boards and virtual platforms for developing Cortex-M and Ethos-U machine learning applications. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/sw.md b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/sw.md index 7529fc45dc..fb335d1a3c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/nav-mlek/sw.md +++ b/content/learning-paths/embedded-and-microcontrollers/nav-mlek/sw.md @@ -1,5 +1,6 @@ --- title: Software development considerations +description: Review software development tools, model formats, and example applications used with the ML Evaluation Kit. weight: 4 diff --git a/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/dstream.md b/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/dstream.md index 5985a8b994..326c18913e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/dstream.md +++ b/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/dstream.md @@ -1,6 +1,7 @@ --- # User change title: Debug connection with Arm DSTREAM +description: Create an Arm Development Studio debug connection for a hardware target using a DSTREAM debug probe. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/fastmodels.md b/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/fastmodels.md index a0c5b4a9c1..1c84a0b3db 100644 --- a/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/fastmodels.md +++ b/content/learning-paths/embedded-and-microcontrollers/new_debug_targets_armds/fastmodels.md @@ -1,6 +1,7 @@ --- # User change title: Debug connection to Arm Fast Models +description: Create an Arm Development Studio debug connection for Arm Fast Models and verify the virtual target setup. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/1-overview.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/1-overview.md index 0e87ef1f6f..4dd2df7f70 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/1-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/1-overview.md @@ -1,5 +1,6 @@ --- title: Understand ExecuTorch deployment on NXP with Ethos-U +description: Understand the ExecuTorch and Ethos-U deployment flow used to run accelerated inference on the NXP FRDM i.MX 93 board. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/10-deploy-executorchrunner-nxp-board.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/10-deploy-executorchrunner-nxp-board.md index da44cc3a28..e28fccf585 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/10-deploy-executorchrunner-nxp-board.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/10-deploy-executorchrunner-nxp-board.md @@ -1,5 +1,6 @@ --- title: Deploy and test on FRDM-IMX93 +description: Deploy the ExecuTorch runner to the NXP FRDM i.MX 93 board and test inference on the Cortex-M33 with Ethos-U acceleration. weight: 11 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/2-boot-nxp.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/2-boot-nxp.md index dd5ba0d52f..aa205b399e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/2-boot-nxp.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/2-boot-nxp.md @@ -1,6 +1,7 @@ --- # User change title: "Boot the NXP FRDM i.MX 93 board" +description: Connect to the NXP FRDM i.MX 93 board, boot Linux, and verify the board is ready for ExecuTorch deployment. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/4-environment-setup.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/4-environment-setup.md index 2ff692e783..b1105e8f2e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/4-environment-setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/4-environment-setup.md @@ -1,6 +1,7 @@ --- # User change title: "Set up the ExecuTorch build environment" +description: Set up the ExecuTorch build environment for the NXP workflow using Docker or a native Linux host. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/6-build-executorch.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/6-build-executorch.md index dd20c9a86e..d72ad39312 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/6-build-executorch.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/6-build-executorch.md @@ -1,6 +1,7 @@ --- # User change title: "Build and install ExecuTorch" +description: Build and install ExecuTorch components needed to generate and run models for the NXP FRDM i.MX 93 target. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/7-build-executorch-pte.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/7-build-executorch-pte.md index 0802662121..d7a56b2e52 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/7-build-executorch-pte.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/7-build-executorch-pte.md @@ -1,6 +1,7 @@ --- # User change title: "Build ExecuTorch models for Ethos-U65" +description: Compile ExecuTorch model artifacts for Ethos-U65 so they can run with NPU acceleration on the NXP board. weight: 8 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/9-build-executorch-runner-for-cm33.md b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/9-build-executorch-runner-for-cm33.md index 961e90eecc..fab8b1bf90 100644 --- a/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/9-build-executorch-runner-for-cm33.md +++ b/content/learning-paths/embedded-and-microcontrollers/observing-ethos-u-on-nxp/9-build-executorch-runner-for-cm33.md @@ -1,5 +1,6 @@ --- title: Build Cortex-M33 firmware for ExecuTorch +description: Build Cortex-M33 firmware that runs the ExecuTorch executor runner on the NXP FRDM i.MX 93 board. weight: 10 # FIXED, DO NOT MODIFY layout: learningpathall diff --git a/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/device_support.md b/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/device_support.md index 118a7a5825..bd99514d7a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/device_support.md +++ b/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/device_support.md @@ -1,5 +1,6 @@ --- title: Device support +description: Review CMSIS-Pack device support changes needed when migrating device packs from CMSIS v5 to CMSIS v6. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/example_projects.md b/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/example_projects.md index 89c30cb6de..51db1e59e8 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/example_projects.md +++ b/content/learning-paths/embedded-and-microcontrollers/pack-migration-cmsis-v6/example_projects.md @@ -1,5 +1,6 @@ --- title: Example projects +description: Update CMSIS-Pack example projects so they remain compatible after migrating the pack to CMSIS v6. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/adding-new-schemes.md b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/adding-new-schemes.md index 92ac583f02..5d73b5af04 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/adding-new-schemes.md +++ b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/adding-new-schemes.md @@ -1,5 +1,6 @@ --- title: Add a KEM implementation to pqm4 +description: Add a new key encapsulation mechanism implementation to pqm4 and integrate it with the Cortex-M4 benchmark framework. weight: 5 diff --git a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/introduction.md b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/introduction.md index 32b25a228a..7c56597606 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/introduction.md +++ b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/introduction.md @@ -1,5 +1,6 @@ --- title: Understand pqm4 and post-quantum cryptography +description: Understand pqm4, post-quantum cryptography, and how the library benchmarks algorithms on Arm Cortex-M4. weight: 2 layout: learningpathall --- diff --git a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/running-tests-and-benchmarks.md b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/running-tests-and-benchmarks.md index 3b74c46bb5..736c657d6f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/running-tests-and-benchmarks.md +++ b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/running-tests-and-benchmarks.md @@ -1,5 +1,6 @@ --- title: Run pqm4 tests and benchmarks +description: Build and run pqm4 tests and benchmarks to measure post-quantum cryptography implementations on Cortex-M4. weight: 4 diff --git a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/setup-installation.md b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/setup-installation.md index e483c86dd2..a0d5a5d3ab 100644 --- a/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/setup-installation.md +++ b/content/learning-paths/embedded-and-microcontrollers/pqc_pqm4/setup-installation.md @@ -1,5 +1,6 @@ --- title: Set up the pqm4 development environment +description: Install the dependencies and toolchains needed to build and test pqm4 post-quantum cryptography examples. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/device_mapping.md b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/device_mapping.md index c6d8331c18..e1cd913972 100644 --- a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/device_mapping.md +++ b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/device_mapping.md @@ -1,5 +1,6 @@ --- title: Device mapping +description: Map legacy device identifiers to CMSIS v6 device definitions so migrated projects select the correct target. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/packs.md b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/packs.md index 09c6a0d310..d53172c041 100644 --- a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/packs.md +++ b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/packs.md @@ -1,5 +1,6 @@ --- title: Required CMSIS-Packs +description: Identify and install the CMSIS-Packs required to migrate a CMSIS v5 project to CMSIS v6. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/project_format.md b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/project_format.md index 1f62c5c4ba..0de6ffc072 100644 --- a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/project_format.md +++ b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/project_format.md @@ -1,5 +1,6 @@ --- title: Project format conversion +description: Convert a legacy CMSIS project format to the CMSIS v6 csolution structure used by modern tools. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/toolchains.md b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/toolchains.md index c4e28e5b27..1ef19eb9a3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/toolchains.md +++ b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/toolchains.md @@ -1,5 +1,6 @@ --- title: Supported toolchains +description: Review supported toolchains for CMSIS v6 project migration and select the compiler configuration for the target. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/troubleshooting.md b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/troubleshooting.md index 42a5277aa4..4e42231d79 100644 --- a/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/troubleshooting.md +++ b/content/learning-paths/embedded-and-microcontrollers/project-migration-cmsis-v6/troubleshooting.md @@ -1,5 +1,6 @@ --- title: Troubleshooting +description: Resolve common CMSIS v6 migration issues related to packs, devices, project format, and toolchain settings. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/1-overview.md b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/1-overview.md index befde3ff4f..5eb775aaac 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/1-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/1-overview.md @@ -1,5 +1,6 @@ --- title: Run LLMs locally on Raspberry Pi 5 for Edge AI +description: Review the Raspberry Pi 5 smart home architecture and how local LLMs can control GPIO-connected devices. weight: 2 diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/2-software-dependencies.md b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/2-software-dependencies.md index a054f233f3..4e88b10360 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/2-software-dependencies.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/2-software-dependencies.md @@ -1,5 +1,6 @@ --- title: Set up software dependencies on Raspberry Pi 5 for Ollama and LLMs +description: Install Ollama, Python dependencies, and supporting software for running local LLM smart home workloads on Raspberry Pi 5. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/3-test-gpio.md b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/3-test-gpio.md index e94b73229a..15f0b7fe7a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/3-test-gpio.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/3-test-gpio.md @@ -1,5 +1,6 @@ --- title: Test Raspberry Pi 5 GPIO pins for smart home devices +description: Test Raspberry Pi 5 GPIO outputs with connected devices so the smart home assistant can control hardware reliably. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/4-smart-home-assistant.md b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/4-smart-home-assistant.md index 45c88a4d11..2f3e5986d9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/4-smart-home-assistant.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry-pi-smart-home/4-smart-home-assistant.md @@ -1,5 +1,6 @@ --- title: Build and Run a Smart Home Assistant on Raspberry Pi 5 with LLMs +description: Build and run the web-based Raspberry Pi 5 smart home assistant that uses a local LLM to control GPIO devices. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/2setup.md b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/2setup.md index 5798237d9f..bed940b0ec 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/2setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/2setup.md @@ -1,5 +1,6 @@ --- title: Initial setup +description: Install Raspberry Pi OS and configure the packages needed to build the voice-controlled ChatGPT bot. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/3audio.md b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/3audio.md index 076b2d918a..827abb3c5b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/3audio.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/3audio.md @@ -1,5 +1,6 @@ --- title: Configure and test audio +description: Configure and test the Raspberry Pi microphone and speakers so the bot can capture speech and play responses. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/4python-code.md b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/4python-code.md index f2cc8e6b90..42beb0cd2b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/4python-code.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/4python-code.md @@ -1,5 +1,6 @@ --- title: Create the Python application +description: Create the Python application that detects a wake word, sends speech input to ChatGPT, and plays audio output. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/5run.md b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/5run.md index f74bd12274..e4630536b9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/5run.md +++ b/content/learning-paths/embedded-and-microcontrollers/raspberry_pi_chatgpt_bot/5run.md @@ -1,5 +1,6 @@ --- title: Run and test the bot +description: Run the Raspberry Pi ChatGPT bot and test the complete voice interaction workflow. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/dev-env.md b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/dev-env.md index 3b8c9023bb..d1c3a54055 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/dev-env.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/dev-env.md @@ -1,5 +1,6 @@ --- title: Set up the development environment +description: Set up an Arm Linux development machine with the tools required to build Llama 3 for ExecuTorch. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/executorch.md b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/executorch.md index d0fe999c43..b4b65fd689 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/executorch.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/executorch.md @@ -1,5 +1,6 @@ --- title: Set up ExecuTorch +description: Install and configure ExecuTorch so the Llama 3 model can be compiled for Raspberry Pi 5. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/llama3.md b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/llama3.md index 714ec069d3..a9935b3cb4 100755 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/llama3.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/llama3.md @@ -1,5 +1,6 @@ --- title: Set up Llama 3 +description: Download and prepare the Llama 3 model assets needed for the ExecuTorch deployment workflow. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/run.md b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/run.md index 1e1ee80ff6..610b9bd5a6 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/run.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-llama3/run.md @@ -1,5 +1,6 @@ --- title: Run the model on a Raspberry Pi 5 +description: Deploy the compiled Llama 3 model to Raspberry Pi 5 and run local inference on the device. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/build.md b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/build.md index 4f7f39a0d6..1874a0f0bd 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/build.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/build.md @@ -1,6 +1,6 @@ - --- -# User change +--- title: "Build MXNet" +description: Build and install MXNet inside the Raspberry Pi OS file system on an Arm server, then verify the Python package before deployment. weight: 3 @@ -106,4 +106,3 @@ Building MXNet takes about 20 minutes on an AWS c6g.2xlarge EC2 instance. A native build on a Raspberry Pi 4 can be done using the steps above. Setting the number of jobs too high will result in out of memory failures. With `-j4` and the build fails, even on a Raspberry Pi with Gb RAM. With `-j1` the build completes, but takes over 6 hours. Continue to the next section to download the new image and install it on a Raspberry Pi for testing. - diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/deploy.md b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/deploy.md index 11ad5f5d06..1f36953265 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/deploy.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/deploy.md @@ -1,6 +1,7 @@ - --- +--- # User change title: "Install on Raspberry Pi" +description: Copy the Raspberry Pi OS image with MXNet to a local machine, write it to an SD card, and verify MXNet on a Raspberry Pi. weight: 4 @@ -61,4 +62,4 @@ The expected output format is below. Your version may be slightly different. 2.0.0 ``` -You have significantly reduced MXNet compile time, transferred the result to an SD card, and confirmed MXNet can immediately run on a Raspberry Pi. \ No newline at end of file +You have significantly reduced MXNet compile time, transferred the result to an SD card, and confirmed MXNet can immediately run on a Raspberry Pi. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/setup.md b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/setup.md index d0a5eca09e..a861462ad8 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi-mxnet/setup.md @@ -1,6 +1,7 @@ - --- +--- # User change title: "Install a Raspberry Pi OS file system" +description: Prepare a Raspberry Pi OS image on an Arm Linux server by resizing, mounting, and entering the file system with chroot for an MXNet build. weight: 2 @@ -160,4 +161,3 @@ sudo chroot /mnt /bin/bash The bash shell is now inside the Raspberry Pi file system. It runs as if this is a Raspberry Pi and the file system is the same as if it was being done on a Raspberry Pi board. Continue to the next section to build MXNet, an example C++ application. - diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/docker.md b/content/learning-paths/embedded-and-microcontrollers/rpi/docker.md index ebe55166e5..f61c87f880 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/docker.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/docker.md @@ -1,6 +1,7 @@ --- # User change title: "Docker" +description: Install Docker on Raspberry Pi 4 and run a containerized workload to validate the Arm Linux environment. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/id.md b/content/learning-paths/embedded-and-microcontrollers/rpi/id.md index 8cfd9ea26d..fae99338ea 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/id.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/id.md @@ -1,6 +1,7 @@ --- # User change title: "Identifying the hardware" +description: Identify Raspberry Pi 4 hardware details and system information before running software and performance examples. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/intro.md b/content/learning-paths/embedded-and-microcontrollers/rpi/intro.md index 38155a67b3..842a64156a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/intro.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/intro.md @@ -1,6 +1,7 @@ --- # User change title: "Introduction to the Raspberry Pi 4" +description: Review Raspberry Pi 4 hardware specifications and setup considerations for Arm software development. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/kernel.md b/content/learning-paths/embedded-and-microcontrollers/rpi/kernel.md index 0faa7d008f..3c1480286f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/kernel.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/kernel.md @@ -1,6 +1,7 @@ --- # User change title: "Linux Kernel Compile" +description: Compile the Linux kernel for Raspberry Pi 4 and compare build behavior with an Arm cloud instance. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/perf.md b/content/learning-paths/embedded-and-microcontrollers/rpi/perf.md index 9260c128f0..ede1963ce5 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/perf.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/perf.md @@ -1,6 +1,7 @@ --- # User change title: "Linux Perf" +description: Use Linux perf on Raspberry Pi 4 to collect performance data from Arm workloads. weight: 8 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/setup.md b/content/learning-paths/embedded-and-microcontrollers/rpi/setup.md index b23e846416..2713e6019f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/setup.md @@ -1,6 +1,7 @@ --- # User change title: "Setup a Raspberry Pi 4 and an Arm cloud instance" +description: Set up Raspberry Pi 4 and an Arm cloud instance so you can compare local and remote Arm development workflows. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi/tf.md b/content/learning-paths/embedded-and-microcontrollers/rpi/tf.md index 217f338c4e..5f53249f21 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi/tf.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi/tf.md @@ -1,6 +1,7 @@ --- # User change title: "TensorFlow" +description: Install and run TensorFlow on Raspberry Pi 4 to test machine learning workloads on Arm hardware. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/debug.md b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/debug.md index 83054784b1..2b1e209b3e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/debug.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/debug.md @@ -1,6 +1,7 @@ --- # User change title: "How do I debug RPi Pico applications?" +description: Connect debug wiring for Raspberry Pi Pico applications and use the debugger to inspect firmware execution. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/hello.md b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/hello.md index 8f3adc610d..4b928aee6f 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/hello.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/hello.md @@ -1,6 +1,7 @@ --- # User change title: "How do I run Hello World for Raspberry Pi Pico?" +description: Build and run the Hello World example for Raspberry Pi Pico to verify the SDK and board setup. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/perf.md b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/perf.md index b810ba37b6..478787810c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/perf.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/perf.md @@ -1,6 +1,7 @@ --- # User change title: "How do I measure RPi Pico Application Performance?" +description: Build a Raspberry Pi Pico application and measure its execution performance on the microcontroller. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/sdk.md b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/sdk.md index 74190adb42..ad680c831a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/rpi_pico/sdk.md +++ b/content/learning-paths/embedded-and-microcontrollers/rpi_pico/sdk.md @@ -1,6 +1,7 @@ --- # User change title: "How do I install the Raspberry Pi Pico SDK?" +description: Install the Raspberry Pi Pico SDK and configure the tools needed to build Pico applications. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/1_overview.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/1_overview.md index bbca4dc735..ae7f81651e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/1_overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/1_overview.md @@ -1,5 +1,6 @@ --- title: Profile Linux kernel modules with Arm Streamline +description: Review the Arm Streamline kernel module profiling workflow and the Linux targets used for performance analysis. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/2_build_kernel_image.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/2_build_kernel_image.md index bfde6c9ffe..04988ae6ff 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/2_build_kernel_image.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/2_build_kernel_image.md @@ -1,5 +1,6 @@ --- title: Set up your environment +description: Build a Linux image with Buildroot so the target environment can run kernel module profiling examples. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/3_oot_module.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/3_oot_module.md index 9bfc522b7c..d60884e189 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/3_oot_module.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/3_oot_module.md @@ -1,5 +1,6 @@ --- title: Build the out-of-tree kernel module +description: Create and build an out-of-tree Linux kernel module designed to expose cache-unfriendly behavior for Streamline analysis. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/4_sl_profile_oot.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/4_sl_profile_oot.md index e5ff493910..54afad166d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/4_sl_profile_oot.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/4_sl_profile_oot.md @@ -1,5 +1,6 @@ --- title: Profile the out-of-tree kernel module +description: Profile the out-of-tree kernel module with Arm Streamline and inspect the performance bottlenecks it exposes. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/5_intree_kernel_driver.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/5_intree_kernel_driver.md index 3d33f88175..9d2daaea06 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/5_intree_kernel_driver.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/5_intree_kernel_driver.md @@ -1,5 +1,6 @@ --- title: Integrate a custom character device driver into the Linux kernel +description: Integrate a custom character device driver into the Linux kernel so it can be profiled as an in-tree module. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/6_sl_profile_intree.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/6_sl_profile_intree.md index e4f50c5330..03091fd2ae 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/6_sl_profile_intree.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/6_sl_profile_intree.md @@ -1,5 +1,6 @@ --- title: Profile the in-tree kernel driver +description: Profile the in-tree kernel driver with Arm Streamline and compare results with the out-of-tree module workflow. weight: 7 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/7_sl_spe.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/7_sl_spe.md index f1897f2381..42b38d4b76 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/7_sl_spe.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/7_sl_spe.md @@ -1,5 +1,6 @@ --- title: Use Streamline with the Statistical Profiling Extension +description: Use Arm Streamline with Statistical Profiling Extension data to analyze Linux workload behavior in more detail. weight: 8 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/8_summary.md b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/8_summary.md index 6436995b80..bcb6059086 100644 --- a/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/8_summary.md +++ b/content/learning-paths/embedded-and-microcontrollers/streamline-kernel-module/8_summary.md @@ -1,5 +1,6 @@ --- title: Summary +description: Summarize the kernel module profiling workflow and the Streamline techniques used to analyze Linux drivers. weight: 9 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/features.md b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/features.md index 25023fc47d..a558fb2e34 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/features.md +++ b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/features.md @@ -1,6 +1,7 @@ --- # User change title: Feature extraction +description: Extract features from captured training data so the TensorFlow model can learn the letter recognition task. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/run_nn.md b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/run_nn.md index ace948f192..2f15cecc5a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/run_nn.md +++ b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/run_nn.md @@ -1,6 +1,7 @@ --- # User change title: Run the model on development board +description: Deploy the trained TensorFlow model to the STM32 development board and run inference from the generated firmware. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/setup.md b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/setup.md index 0e84c2b6bf..7f7809eb3d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/setup.md +++ b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/setup.md @@ -1,6 +1,7 @@ --- # User change title: Prepare development environment +description: Install Anaconda and prepare the Python environment for training and deploying the STM32 TensorFlow model. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/test.md b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/test.md index dc7751d42b..0aab5f115d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/test.md +++ b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/test.md @@ -1,6 +1,7 @@ --- # User change title: Train the model +description: Create and train the TensorFlow model used for letter recognition before deploying it to the STM32 board. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/train_nn.md b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/train_nn.md index 17942e6cbc..5b4fb1b521 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/train_nn.md +++ b/content/learning-paths/embedded-and-microcontrollers/tflow_nn_stcube/train_nn.md @@ -1,6 +1,7 @@ --- # User change title: Collect training data +description: Collect training data for the letter recognition model and prepare it for TensorFlow feature extraction. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/tfm/tfm.md b/content/learning-paths/embedded-and-microcontrollers/tfm/tfm.md index af9be250c5..0e67a433e1 100644 --- a/content/learning-paths/embedded-and-microcontrollers/tfm/tfm.md +++ b/content/learning-paths/embedded-and-microcontrollers/tfm/tfm.md @@ -1,6 +1,7 @@ --- # User change title: "Build and run TF-M tests and example application" +description: Build and run Trusted Firmware-M tests and the reference application on an Arm Fixed Virtual Platform. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/env-setup-1.md b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/env-setup-1.md index 415cf50697..b000281a42 100644 --- a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/env-setup-1.md +++ b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/env-setup-1.md @@ -1,5 +1,6 @@ --- title: Set up your environment +description: Install the tools and Python dependencies needed to train and deploy the tiny rock-paper-scissors model on Arm. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fine-tune-2.md b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fine-tune-2.md index e4fa83ecee..16ad300e62 100644 --- a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fine-tune-2.md +++ b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fine-tune-2.md @@ -1,5 +1,6 @@ --- title: Train and Test the rock-paper-scissors Model +description: Train and test the PyTorch rock-paper-scissors classifier before converting it for embedded inference. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fvp-3.md b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fvp-3.md index 53983fca76..8a05e97421 100644 --- a/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fvp-3.md +++ b/content/learning-paths/embedded-and-microcontrollers/training-inference-pytorch/fvp-3.md @@ -1,5 +1,6 @@ --- title: Run the model on Corstone-320 FVP +description: Compile the rock-paper-scissors model for ExecuTorch and run it on the Corstone-320 Fixed Virtual Platform. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/hello.md b/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/hello.md index a16a61939c..cae6f88b28 100644 --- a/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/hello.md +++ b/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/hello.md @@ -1,6 +1,7 @@ --- # User change title: "Run TrustZone Hello World example" +description: Build and run the TrustZone Hello World example on the NXP LPCXpresso55S69 board with Keil MDK. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/trustzone_concepts.md b/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/trustzone_concepts.md index 091c6983a7..87ac86eaad 100644 --- a/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/trustzone_concepts.md +++ b/content/learning-paths/embedded-and-microcontrollers/trustzone_nxp_lpc/trustzone_concepts.md @@ -1,6 +1,7 @@ --- # User change title: "Breaking down the application" +description: Understand the secure and non-secure application flow used by the TrustZone example on the NXP board. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/bay-assembly.md b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/bay-assembly.md index 914a424ba7..7e6db91f2c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/bay-assembly.md +++ b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/bay-assembly.md @@ -1,6 +1,7 @@ --- # User change title: Assembly Instructions for the Chassis Bays +description: Assemble the 3D-printed chassis bays used to mount single board computers in the universal SBC rack system. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/card-plate-assembly.md b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/card-plate-assembly.md index 4c996df002..96e0f5eb8e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/card-plate-assembly.md +++ b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/card-plate-assembly.md @@ -1,6 +1,7 @@ --- # User change title: Assembly Instructions for the Chassis Bays +description: Assemble the card plates that hold single board computers within the universal SBC chassis. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/print-parts.md b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/print-parts.md index c658152768..66ed2b9d35 100644 --- a/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/print-parts.md +++ b/content/learning-paths/embedded-and-microcontrollers/universal-sbc-chassis/print-parts.md @@ -1,6 +1,7 @@ --- # User change title: Print the Required Parts +description: Print the required 3D parts for the universal SBC chassis and prepare them for assembly. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uv_debug/2_basics.md b/content/learning-paths/embedded-and-microcontrollers/uv_debug/2_basics.md index f9a74bab3f..09763f606d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uv_debug/2_basics.md +++ b/content/learning-paths/embedded-and-microcontrollers/uv_debug/2_basics.md @@ -1,6 +1,7 @@ --- # User change title: "Use basic run/stop debug" +description: Use basic run and stop debugging in Keil uVision to inspect an embedded application on the target. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uv_debug/3_event_recorder.md b/content/learning-paths/embedded-and-microcontrollers/uv_debug/3_event_recorder.md index 6b8e79f862..7d27be3a8d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uv_debug/3_event_recorder.md +++ b/content/learning-paths/embedded-and-microcontrollers/uv_debug/3_event_recorder.md @@ -1,6 +1,7 @@ --- # User change title: "Debug using Event Recorder" +description: Use Event Recorder in Keil uVision to capture and analyze runtime events from an embedded application. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uv_debug/4_swv.md b/content/learning-paths/embedded-and-microcontrollers/uv_debug/4_swv.md index 2ff24068d4..fb9ccc55de 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uv_debug/4_swv.md +++ b/content/learning-paths/embedded-and-microcontrollers/uv_debug/4_swv.md @@ -1,6 +1,7 @@ --- # User change title: "Debug using Serial Wire Viewer" +description: Use Serial Wire Viewer in Keil uVision to observe trace data from a running Cortex-M application. weight: 4 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uv_debug/5_etm_trace.md b/content/learning-paths/embedded-and-microcontrollers/uv_debug/5_etm_trace.md index 9d72d6f034..87807faa84 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uv_debug/5_etm_trace.md +++ b/content/learning-paths/embedded-and-microcontrollers/uv_debug/5_etm_trace.md @@ -1,6 +1,7 @@ --- # User change title: "Advanced debug with ETM trace" +description: Use ETM trace in Keil uVision to capture instruction flow and analyze advanced debug behavior. weight: 5 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uv_debug/6_power_ulplus.md b/content/learning-paths/embedded-and-microcontrollers/uv_debug/6_power_ulplus.md index 1f4257471e..0d6b93c293 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uv_debug/6_power_ulplus.md +++ b/content/learning-paths/embedded-and-microcontrollers/uv_debug/6_power_ulplus.md @@ -1,6 +1,7 @@ --- # User change title: "Measure Power with ULINKplus" +description: Measure target power with ULINKplus in Keil uVision and correlate energy use with firmware execution. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-1.md b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-1.md index 81f531cdee..c6081f885b 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-1.md +++ b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-1.md @@ -1,5 +1,6 @@ --- title: Using Keil Studio +description: Convert a uVision project to csolution format in Keil Studio and build it with CMSIS-Toolbox. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-2.md b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-2.md index f608c39e50..e46a94dfda 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-2.md +++ b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-2.md @@ -1,5 +1,6 @@ --- title: Using the command line +description: Convert a uVision project to csolution format from the command line and verify the CMSIS-Toolbox build. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-mdk.md b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-mdk.md index 629c04ec96..01d82b6777 100644 --- a/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-mdk.md +++ b/content/learning-paths/embedded-and-microcontrollers/uvprojx-conversion/how-to-mdk.md @@ -1,5 +1,6 @@ --- title: Using µVision +description: Convert a uVision project inside Keil MDK and prepare it for CMSIS-Toolbox based workflows. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/config_creation.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/config_creation.md index 5efa5b2a27..a63815ec19 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/config_creation.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/config_creation.md @@ -1,5 +1,6 @@ --- title: Create a vcpkg-configuration.json file +description: Create a vcpkg-configuration.json file that defines tool sources and versions for reproducible embedded development. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/initialization.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/initialization.md index 1f86275470..3a45f2258c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/initialization.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/initialization.md @@ -1,5 +1,6 @@ --- title: Initialize vcpkg +description: Initialize vcpkg in the project so command-line tools can be installed from the configured registries. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/installation.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/installation.md index e84eab3ff6..ca2290f43a 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/installation.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/installation.md @@ -1,5 +1,6 @@ --- title: Install vcpkg +description: Install vcpkg and verify the command-line setup used for managing Arm development tools. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/licenseactivation.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/licenseactivation.md index 2162faef99..619d2ca642 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/licenseactivation.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/licenseactivation.md @@ -1,5 +1,6 @@ --- title: Activate a license +description: Activate tool licenses through vcpkg so installed Arm command-line tools are ready for use. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/removal.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/removal.md index 62722d8a28..c93997300e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/removal.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/removal.md @@ -1,5 +1,6 @@ --- title: Remove vcpkg +description: Remove vcpkg-managed tools and configuration when you need to reset the local tool installation. weight: 7 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/usage.md b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/usage.md index 37e5a6e8aa..5d3e3b6d60 100644 --- a/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/usage.md +++ b/content/learning-paths/embedded-and-microcontrollers/vcpkg-tool-installation/usage.md @@ -1,5 +1,6 @@ --- title: Use vcpkg +description: Use vcpkg commands to install, list, and manage versioned tools for an embedded development workflow. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/2-overview.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/2-overview.md index b087e70934..7cdae77bd8 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/2-overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/2-overview.md @@ -1,5 +1,6 @@ --- title: Overview +description: Review the TinyML performance visualization workflow for deploying ExecuTorch models on Corstone-320 virtual hardware. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/3-executorch-workflow.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/3-executorch-workflow.md index 4862f6cc9d..da151371df 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/3-executorch-workflow.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/3-executorch-workflow.md @@ -1,6 +1,7 @@ --- # User change title: "Understand the ExecuTorch workflow" +description: Understand the ExecuTorch conversion and runtime flow used to deploy neural network models to Arm targets. weight: 3 diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/4-env-setup-execut.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/4-env-setup-execut.md index 598f785873..65ea826bc2 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/4-env-setup-execut.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/4-env-setup-execut.md @@ -1,6 +1,7 @@ --- # User change title: "Set up your ExecuTorch environment" +description: Install ExecuTorch and prepare the Python environment needed for model conversion and deployment. weight: 4 diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/5-env-setup-fvp.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/5-env-setup-fvp.md index 1208f92761..0735aa71a4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/5-env-setup-fvp.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/5-env-setup-fvp.md @@ -1,6 +1,7 @@ --- # User change title: "Set up the Corstone-320 Fixed Virtual Platform" +description: Install and configure the Corstone-320 Fixed Virtual Platform for running and visualizing TinyML models. weight: 5 diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/6-run-model.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/6-run-model.md index cc6b3d8e17..6fd82bb1b9 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/6-run-model.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/6-run-model.md @@ -1,6 +1,7 @@ --- # User change title: "Deploy and run Mobilenet V2 on the Corstone-320 FVP" +description: Deploy MobileNet V2 with ExecuTorch on the Corstone-320 FVP and verify model execution. weight: 6 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/7-configure-fvp-gui.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/7-configure-fvp-gui.md index 257198342c..5e852faf85 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/7-configure-fvp-gui.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/7-configure-fvp-gui.md @@ -1,6 +1,7 @@ --- # User change title: "Enable GUI and deploy a model on Corstone-320 FVP" +description: Enable the Corstone-320 FVP graphical interface so you can visualize model execution while inference runs. weight: 7 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/8-evaluate-output.md b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/8-evaluate-output.md index 1034282f82..ebda9ae7c3 100644 --- a/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/8-evaluate-output.md +++ b/content/learning-paths/embedded-and-microcontrollers/visualizing-ethos-u-performance/8-evaluate-output.md @@ -1,6 +1,7 @@ --- # User change title: "Evaluate Ethos-U Performance" +description: Interpret Ethos-U performance output from the FVP and use the results to understand model behavior. weight: 8 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/yocto_qemu/yocto_build.md b/content/learning-paths/embedded-and-microcontrollers/yocto_qemu/yocto_build.md index 8fe1a8777a..1f173b9207 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yocto_qemu/yocto_build.md +++ b/content/learning-paths/embedded-and-microcontrollers/yocto_qemu/yocto_build.md @@ -1,6 +1,7 @@ --- # User change title: "How do I get started with Yocto Linux on Qemu?" +description: Build a minimal Yocto Linux image for a 64-bit Arm QEMU target and boot it in the emulator. weight: 3 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/build-firmware.md b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/build-firmware.md index 6745db9bc9..1c20a0386d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/build-firmware.md +++ b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/build-firmware.md @@ -1,5 +1,6 @@ --- title: Build the firmware +description: Build the Himax firmware that runs the YOLO object detection model on the WiseEye2 microcontroller module. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/dev-env.md b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/dev-env.md index 348b8eb84f..3fe98fb579 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/dev-env.md +++ b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/dev-env.md @@ -1,5 +1,6 @@ --- title: Set up the environment +description: Install the software tools and SDK dependencies required to build YOLO firmware for the Himax WiseEye2 module. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/flash-and-run.md b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/flash-and-run.md index ac03163972..6d101004b4 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/flash-and-run.md +++ b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/flash-and-run.md @@ -1,5 +1,6 @@ --- title: Flash firmware onto the microcontroller +description: Flash YOLO firmware to the Himax WiseEye2 module and verify object detection on the microcontroller. weight: 5 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/overview.md b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/overview.md index 41435620a5..fc55c27b54 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/overview.md +++ b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/overview.md @@ -1,5 +1,6 @@ --- title: Overview +description: Review the Himax WiseEye2 module and the YOLO object detection workflow before building and flashing firmware. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/web-toolkit.md b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/web-toolkit.md index 63ad577719..6fee29695e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/web-toolkit.md +++ b/content/learning-paths/embedded-and-microcontrollers/yolo-on-himax/web-toolkit.md @@ -1,5 +1,6 @@ --- title: Run additional models in the web toolkit +description: Modify the Himax web toolkit build settings and run additional models on the Grove Vision AI module. weight: 6 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/zephyr/zephyr.md b/content/learning-paths/embedded-and-microcontrollers/zephyr/zephyr.md index 3ab574ce6b..089d0f658e 100644 --- a/content/learning-paths/embedded-and-microcontrollers/zephyr/zephyr.md +++ b/content/learning-paths/embedded-and-microcontrollers/zephyr/zephyr.md @@ -1,6 +1,7 @@ --- # User change title: "Build and run Zephyr applications" +description: Build and run Zephyr RTOS applications on the Corstone-300 FVP using Arm Virtual Hardware. weight: 2 # 1 is first, 2 is second, etc. diff --git a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/1_installation.md b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/1_installation.md index a4ac9f182c..3c11d6660c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/1_installation.md +++ b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/1_installation.md @@ -1,5 +1,6 @@ --- title: Set up the Workbench for Zephyr development environment +description: Install Workbench for Zephyr in VS Code and configure the tools needed for Arm Cortex-M Zephyr development. weight: 2 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/2_development.md b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/2_development.md index 6be1d64510..9f925ba77c 100644 --- a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/2_development.md +++ b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/2_development.md @@ -1,5 +1,6 @@ --- title: Build a Zephyr application with Workbench for Zephyr +description: Create and build a Zephyr application with Workbench for Zephyr and prepare it for a supported development board. weight: 3 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/3_debug.md b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/3_debug.md index 2a6541734b..f095759c1d 100644 --- a/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/3_debug.md +++ b/content/learning-paths/embedded-and-microcontrollers/zephyr_vsworkbench/3_debug.md @@ -1,5 +1,6 @@ --- title: Analyze and debug a Zephyr application +description: Debug a Zephyr application with Workbench for Zephyr and inspect firmware behavior using integrated analysis tools. weight: 4 ### FIXED, DO NOT MODIFY diff --git a/content/learning-paths/laptops-and-desktops/_index.md b/content/learning-paths/laptops-and-desktops/_index.md index a0444a649f..016b1d54c0 100644 --- a/content/learning-paths/laptops-and-desktops/_index.md +++ b/content/learning-paths/laptops-and-desktops/_index.md @@ -13,14 +13,14 @@ pinned_learning_paths: operatingsystems_filter: - Android: 3 - ChromeOS: 2 -- Linux: 41 -- macOS: 11 -- Windows: 47 +- Linux: 46 +- macOS: 14 +- Windows: 50 subjects_filter: - CI-CD: 7 -- Containers and Virtualization: 6 +- Containers and Virtualization: 8 - Migration to Arm: 30 -- ML: 8 +- ML: 11 - Performance and Architecture: 30 subtitle: Build native Windows on Arm applications that are fast and efficient. title: Laptops and Desktops @@ -32,16 +32,17 @@ tools_software_languages_filter: - Arm Performance Libraries: 2 - Arm64EC: 1 - Assembly: 1 -- Bash: 4 +- Bash: 5 - C: 12 - C#: 6 - CCA: 1 - Clang: 13 -- CMake: 4 -- CPP: 12 +- CMake: 5 +- CPP: 13 - CSS: 1 -- Docker: 9 +- Docker: 12 - ExecuTorch: 1 +- FastAPI: 1 - FFmpeg: 1 - GCC: 12 - Git: 1 @@ -67,35 +68,42 @@ tools_software_languages_filter: - LLVM: 2 - llvm-mca: 1 - MCP: 1 +- MediaPipe: 1 - MSBuild: 1 - MSVC: 1 - MTE: 1 +- MuJoCo: 1 - Neon: 1 - Neovim: 1 - Node.js: 3 +- Ollama: 1 - ONNX Runtime: 1 - OpenCV: 1 - perf: 4 - PGO: 1 - PowerShell: 1 - Pytest: 1 -- Python: 14 +- Python: 16 - PyTorch: 1 - QEMU: 1 - Qt: 2 +- Raspberry Pi: 1 - RDP: 1 +- Reachy Mini: 1 - Remote.It: 1 - RME: 1 - Runbook: 17 - Rust: 2 - SME2: 3 +- SSH: 2 - SVE: 1 - SVE2: 1 - Testcontainers: 1 +- Topo: 2 - Trusted Firmware: 1 - Ubuntu: 1 - Visual Studio: 14 -- Visual Studio Code: 13 +- Visual Studio Code: 14 - Windows Forms: 1 - Windows Performance Analyzer: 1 - Windows Presentation Foundation: 1 @@ -110,8 +118,4 @@ weight: 2 # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit --- diff --git a/content/learning-paths/mobile-graphics-and-gaming/_index.md b/content/learning-paths/mobile-graphics-and-gaming/_index.md index a2ad9b593d..aaaccdb20d 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/_index.md +++ b/content/learning-paths/mobile-graphics-and-gaming/_index.md @@ -13,14 +13,14 @@ pinned_learning_paths: - nss-unreal - vulkan-ml-sample operatingsystems_filter: -- Android: 40 -- Linux: 40 -- macOS: 19 -- Windows: 16 +- Android: 41 +- Linux: 43 +- macOS: 22 +- Windows: 19 subjects_filter: - Gaming: 6 -- Graphics: 6 -- ML: 23 +- Graphics: 8 +- ML: 28 - Performance and Architecture: 36 subtitle: Optimize Android apps and build faster games using cutting-edge Arm tech. title: Mobile, Graphics, and Gaming @@ -35,62 +35,66 @@ tools_software_languages_filter: - Arm Mobile Studio: 1 - Arm Performance Studio: 3 - Assembly: 1 -- Bash: 1 -- Bazel: 1 +- Bash: 2 +- Bazel: 2 - C: 5 - C#: 3 - C++: 3 - CCA: 1 - Clang: 12 -- CMake: 3 -- CPP: 15 +- CMake: 4 +- CPP: 16 - Docker: 1 -- ExecuTorch: 7 +- ExecuTorch: 8 - Frame Advisor: 1 - GCC: 12 - Generative AI: 2 - Godot: 1 - Google Pixel 8: 1 - Google Test: 1 +- Gradio: 1 - Halide: 1 - Hugging Face: 6 - Java: 7 -- Jupyter Notebook: 1 -- KleidiAI: 3 -- Kotlin: 9 +- Jupyter Notebook: 2 +- KleidiAI: 4 +- Kotlin: 10 - LiteRT: 1 -- llama.cpp: 3 -- LLM: 1 +- LiteRT-LM: 1 +- llama.cpp: 4 +- LLM: 2 - LLVM: 1 - llvm-mca: 1 - MediaPipe: 2 +- Model Explorer: 1 - MTE: 2 -- Neon: 1 -- NX: 4 +- Neon: 2 +- NX: 7 - ONNX: 1 -- ONNX Runtime: 2 +- ONNX Runtime: 3 - OpenGL ES: 1 -- Python: 11 -- PyTorch: 3 +- Python: 12 +- PyTorch: 4 - QEMU: 1 - RenderDoc: 1 - RME: 1 - Runbook: 14 - Rust: 2 - SDDiskTool: 1 -- SME2: 9 -- SVE2: 1 +- SME2: 11 +- SVE2: 2 - TensorFlow: 1 - TorchAO: 1 -- TOSA: 1 +- TOSA: 2 +- Transformers: 1 - Trusted Firmware: 1 - Unity: 6 -- Unreal Engine: 4 -- Visual Studio: 1 +- Unreal Engine: 6 +- Visual Studio: 2 - Visual Studio Code: 1 -- Vulkan: 6 +- Vulkan: 8 - Vulkan SDK: 1 -- XNNPACK: 2 +- XNNPACK: 3 weight: 3 # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit @@ -102,7 +106,4 @@ weight: 3 # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit # auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit -# auto-generated padding to avoid Hugo YAML alias limit --- diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md b/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md index 3a9b8533fb..100d7a661a 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/_index.md @@ -1,28 +1,77 @@ --- -title: Get started with Arm Performance Studio +title: Profile an Android application with Arm Performance Studio -description: Learn how to use each of the tools supplied with Arm Performance Studio (formerly known as Arm Mobile Studio). +description: Profile a debuggable Android graphics application with Arm Performance Studio and analyze performance with Streamline, Performance Advisor, Frame Advisor, RenderDoc for Arm GPUs, and Mali Offline Compiler. minutes_to_complete: 60 -who_is_this_for: Android application and games developers new to Arm Performance Studio. +who_is_this_for: This is an introductory topic for Android application and games developers new to Arm Performance Studio. learning_objectives: - - Learn the basic features of each component of Arm Performance Studio. - - Get started profiling and optimizing your application. + - Capture a Streamline profile from a debuggable Android application + - Generate and inspect a Performance Advisor report + - Capture and analyze a frame with Frame Advisor and RenderDoc for Arm GPUs + - Use Mali Offline Compiler to estimate shader cost prerequisites: - An Android device. - - Arm Performance Studio supports applications built with OpenGL ES versions 2.0 to 3.2, or Vulkan versions 1.0 to 1.2. + - An debuggable build of your application built with OpenGL ES versions 2.0 to 3.2, or Vulkan versions 1.0 to 1.2. - For OpenGL ES applications, your device must be running Android 10 or later. - For Vulkan applications, your device must be running Android 9 or later. - - A debuggable build of your application. - Arm Performance Studio installed. Follow the [Arm Performance Studio install guide](/install-guides/ams/) for instructions. - - Android SDK Platform tools installed. Required for the Android Debug bridge (adb). + - Android SDK Platform tools installed for the Android Debug bridge (adb). + +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-26T16:37:19Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 80078c6f05717cbf24c3b695a82fa15bbe477bd14a290195569dda4efe6599ee + summary_generated_at: '2026-06-26T16:37:19Z' + summary_source_hash: 80078c6f05717cbf24c3b695a82fa15bbe477bd14a290195569dda4efe6599ee + faq_generated_at: '2026-06-26T16:37:19Z' + faq_source_hash: 80078c6f05717cbf24c3b695a82fa15bbe477bd14a290195569dda4efe6599ee + summary: >- + You'll profile an Android graphics application on Arm + Mali-based GPUs using Arm Performance Studio. After preparing a debuggable build, you'll + connect an Android device over adb, explore a provided Streamline sample to understand the + available views, then capture a profile from your own application and generate a Performance + Advisor report with the CLI. You'll also perform frame-level inspection with Frame Advisor + and RenderDoc for Arm GPUs, and use Mali Offline Compiler to estimate shader + cost. By the end, you'll understand how to progress from example data to capturing on-device + profiles and interpreting reports that inform deeper frame and shader analysis. + faqs: + - question: How do I launch Streamline and select my Android device? + answer: >- + Open the Performance Studio Hub and launch Streamline. In the Start view, choose Android + (adb) as the device type and select your device from the list. + - question: What should I check in my app build before profiling with Streamline? + answer: >- + Build a debuggable version and include options that facilitate call stack unwinding by Streamline. + For Unity, enable Development Build in Build settings. + - question: What steps import the example Streamline capture? + answer: >- + In Streamline, select File > Import, choose Import Streamline Sample Captures, then select + the Android example and finish. The sample capture is added so you can open it and explore + the views. + - question: How do I generate a Performance Advisor report from a capture? + answer: >- + Open a terminal, navigate to the capture location, and run streamline-cli with the -pa option + on the .apc file (for example, "Android - GPU Bound Example.apc"). The capture is processed + and a Performance Advisor report is produced. + - question: Do I need Python for Performance Advisor? + answer: >- + Yes. Performance Advisor uses a Python script to connect to your device and requires Python + 3.8 or later. +# END generated_summary_faq author: Ronan Synnott -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md b/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md index 6db0edfda6..b437777634 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/ams.md @@ -1,32 +1,53 @@ --- # User change -title: "What is Arm Performance Studio?" +title: Set up Arm Performance Studio + +description: Install and launch Arm Performance Studio, update your PATH, and confirm the profiling tools are available for the Android application workflow. weight: 2 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -[Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio) is a performance analysis tool suite for developers to performance test their applications on devices with Mali-based GPUs. It consists of 4 easy-to-use tools that show you how well your application performs either on off-the-shelf Android devices, or Linux targets. The tools help you to identify problems that might slow down performance, overheat the device, or drain the battery. +## What is Arm Performance Studio? + +[Arm Performance Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio) is a performance analysis tool suite that you can use to performance test applications on devices with Mali-based GPUs. + +Performance Studio consists of four tools that show you how well your application performs either on off-the-shelf Android devices, or Linux targets. You can use the tools to identify problems that might slow down performance, overheat the device, or drain the battery. | Component | Functionality | |----------|-------------| -| [Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) with [Performance Advisor](https://developer.arm.com/Tools%20and%20Software/Performance%20Advisor) | Capture a performance profile that shows all the performance counter activity from the device. Generate an easy-to-read performance summary from an annotated Streamline capture, and get actionable advice about where you should optimize. | +| [Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) with [Performance Advisor](https://developer.arm.com/Tools%20and%20Software/Performance%20Advisor) | Capture a performance profile that shows all the performance counter activity from the device. Generate a performance summary from an annotated Streamline capture, and get actionable advice about where you should optimize. | | [Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) | Capture the API calls and rendering from a problem frame and get comprehensive geometry metrics to discover what might be slowing down your application. | | [Mali Offline Compiler](https://developer.arm.com/Tools%20and%20Software/Mali%20Offline%20Compiler) | Analyze how efficiently your shader programs perform on a range of Mali GPUs. | | [RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) | The industry-standard tool for debugging Vulkan graphics applications, including early support for Arm GPU extensions and Android features. | -## Download and Install Arm Performance Studio +## Download and install Arm Performance Studio + +Arm Performance Studio is supported on Windows, Linux, and macOS hosts. To download Arm Performance Studio, see the [Arm Performance Studio downloads page](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads). + +For installation instructions, see the [Arm Performance Studio install guide](/install-guides/ams/). + +## Update your PATH environment variable (Linux and macOS) + +Edit your `PATH` environment variable to add the paths to the Streamline and Mali Offline Compiler executables. By adding the paths, you can run Streamline's `Streamline-cli -pa` command and Mali Offline Compiler's `malioc` command from any directory. This step isn't necessary on Windows, as this is done automatically when Arm Performance Studio is installed. + +On macOS, edit your `/etc/paths` file to add the following paths: -Arm Performance Studio is supported on Windows, Linux, and macOS hosts. Get the [Arm Performance Studio installation package](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads). +``` +//streamline +//mali_offline_compiler +``` -Refer to the [Arm Performance Studio install guide](/install-guides/ams/) for installation instructions. +On Linux, edit your `PATH` environment variable to add the paths to the Performance Advisor executable. Add this command to the `.bashrc` file in your home directory, so that this environment variable is set whenever you initialize a shell session. -## Launch the tools +``` + PATH=$PATH://streamline + PATH=$PATH://mali_offline_compiler +``` -To open the tools, launch the Performance Studio Hub: +## What you've accomplished and what's next -- On Windows, search for Performance Studio. -- On macOS and Linux, open the Performance Studio application file from the install directory. +You've set up Arm Performance Studio and updated your `PATH` so you can use the profiling tools from a terminal. - ![Performance Studio Hub](images/ps_hub.png) +Next, you'll set up the application that you'll profile in this Learning Path. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md b/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md index 5d83889000..ce1c6ca5d6 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/fa.md @@ -1,78 +1,89 @@ --- # User change -title: "Frame Advisor" +title: Analyze your application with Frame Advisor + +description: Capture a frame burst with Frame Advisor and inspect render graph, framebuffer, content metrics, and detailed metrics views for bottlenecks. weight: 8 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -[Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) offers in-depth frame-based analysis for mobile graphics in Android applications. By capturing the API calls and rendering processes of a specific frame, you can identify potential performance bottlenecks that may be causing slowdowns in your application. -## Prerequisites +## Connect to your Android device + +[Frame Advisor](https://developer.arm.com/Tools%20and%20Software/Frame%20Advisor) offers in-depth frame-based analysis for mobile graphics in Android applications. -Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). +By capturing the API calls and rendering processes of a specific frame, you can identify performance bottlenecks that might slow down your application. -## Connect to the device +Start by connecting to your device. 1. Launch the Performance Studio Hub and open Frame Advisor. - On Windows, search for Performance Studio. - On macOS and Linux, open the Performance Studio application file from the install directory. - ![Performance Studio Hub](images/ps_hub.png) + ![Screenshot of the Arm Performance Studio Hub showing the Frame Advisor launch card used to open Frame Advisor#center](images/ps_hub.png) -1. Select `New trace` to start a new trace. +2. Select **New trace** to start a new trace. - ![Frame Advisor launch screen](images/fa_launch_screen.png) + ![Screenshot of the Frame Advisor welcome screen showing the New trace button used to start a frame capture session#center](images/fa_launch_screen.png) -1. Select your device, and the application that you want to capture frames from. +3. Select your device, and the application that you want to capture frames from. - ![Device connection screen](images/fa_connect.png) + ![Screenshot of Frame Advisor showing a connected Android device, a selected debuggable application, OpenGL ES selected, and the Next button for starting the session#center](images/fa_connect.png) -1. If your application uses the Vulkan API, change the selection in the API settings to `Vulkan`. +4. If your application uses the Vulkan API, change the selection in the API settings to **Vulkan**. -1. Click `Next` to continue. +5. Select **Next** to continue. - Unless you chose the `Pause on connect` option in the `Device connection` screen, the application starts automatically on the device. + Unless you chose the **Pause on connect** option in the **Device connection** screen, the application starts automatically on the device. ## Capture a frame burst -1. The `Capture` screen provides options for your capture session. +After connecting to your device, you can capture a frame burst. + +1. The **Capture** screen provides options for your capture session. - ![Frame Advisor capture screen](images/fa_capture.png) + ![Screenshot of the Frame Advisor Capture frames for analysis screen showing the live application preview, frame count control, and Capture button#center](images/fa_capture.png) - When you approach the part of your game where the problem occurs, click `Pause` and use the `Step` button to focus in just before it. + When you approach the part of your game where the problem occurs, select **Pause** and use the **Step** button to focus in just before it. -1. You can capture one frame burst of up to 3 consecutive frames. Adjust the `Frame count` as required. +2. You can capture one frame burst of up to three consecutive frames. Adjust the **Frame count** as required. -1. Click the `Capture` button to start capturing the frame burst. Wait for the capture to complete. This may take several seconds. +3. Select the **Capture** button to start capturing the frame burst. Wait for the capture to complete. This might take several seconds. -1. Click `Analyze` to see the results. It may take a few minutes to analyze the data. +4. Select **Analyze** to see the results. It might take a few minutes to analyze the data. ## Analyze the capture -Frame Advisor presents the captured data in the `Analysis` screen. See your captured frames in the `Frame Hierarchy` view. +Frame Advisor presents the captured data in the **Analysis** screen. See your captured frames in the **Frame Hierarchy** view. -![Example Analysis screen](images/fa_example_analysis_screen_1-1.png) +![Screenshot of the Frame Advisor Analysis screen showing Frame Hierarchy, Render Graph, API Calls, Framebuffers, Content Metrics, and Detailed Metrics panels for a captured frame#center](images/fa_example_analysis_screen_1-1.png) Explore each frame to evaluate how efficiently they were rendered on the device. 1. Look at the Render Graph to see how the frame was constructed. - ![Render Graph](images/fa_render_graph_1.1.gif) + ![Render Graph view in Frame Advisor showing render passes connected by texture and render-buffer dependencies so unused attachments can be identified#center](images/fa_render_graph_1.1.gif) + + Evaluate the render graph to look for render passes or input or output attachments that aren’t used in the final output and can be removed to save processing power and bandwidth. + +2. Expand a frame in the **Frame Hierarchy** view, to see the render passes and draw calls within it. Step through the draw calls and watch the scene being built up in the **Framebuffers** view with each draw. Look for draw calls that can be eliminated, or identical draw calls that can be batched together. + + ![Framebuffers view in Frame Advisor showing the selected draw call output so you can step through how the frame is built#center](images/fa_frame_buffer_view.png) - Evaluate the render graph to look for render passes or input or output attachments that aren’t used in the final output, and could be removed, saving processing power and bandwidth. +3. In the **Content Metrics** view, sort draw calls by the number of primitives to find the most expensive objects. See whether these objects can be simplified. -1. Expand a frame in the `Frame Hierarchy` view, to see the render passes and draw calls within it. Step through the draw calls and watch the scene being built up in the `Framebuffers` view with each draw. Look for draw calls that could be eliminated, such as those that do not contribute anything to the final output. Look for identical draw calls that could be batched together into one draw. + ![Content Metrics view in Frame Advisor sorted by primitive count with the Prims column highlighted to identify expensive draw calls#center](images/fa_content_metrics.png) - ![Framebuffers view](images/fa_frame_buffer_view.png) +4. For an expensive object, check the **Detailed Metrics** view to see how efficiently the object's mesh is being rendered to the screen. Look for objects with duplicated vertices, or those that don't efficiently reuse indices. -1. In the `Content Metrics` view, sort draw calls by the number of primitives to find the most expensive objects. See whether these objects could be simplified. + ![Detailed Metrics view in Frame Advisor showing mesh complexity, locality, redundancy, and memory layout for the selected draw call#center](images/fa_detailed_metrics_view.png) - ![Content Metrics view](images/fa_content_metrics.png) +To see how to capture and analyze a problem frame with Frame Advisor, see the [Capture and analyze a problem frame with Frame Advisor video tutorial](https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Capture%20and%20analyze%20a%20problem%20frame%20with%20Frame%20Advisor). -1. For an expensive object, check the `Detailed Metrics` view to see how efficiently the object's mesh is being rendered to the screen. Look for objects with duplicated vertices, or those that do not efficiently reuse indices. +## What you've accomplished and what's next - ![Detailed Metrics view](images/fa_detailed_metrics_view.png) +You've now analyzed your application with Frame Advisor. -Watch this [video tutorial](https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Capture%20and%20analyze%20a%20problem%20frame%20with%20Frame%20Advisor) to see how to capture and analyze a problem frame with Frame Advisor. +Next, you'll use RenderDoc for Arm GPUs to capture frames and select application events for debugging. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md b/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md index 54bc14ba31..1aa8648390 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/malioc.md @@ -1,36 +1,38 @@ --- # User change -title: "Mali Offline Compiler" +title: Analyze shader program performance with Mali Offline Compiler + +description: Use Mali Offline Compiler to compile shader code, compare cycle estimates, and understand when shader cost affects the profiled application. weight: 10 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -Mali Offline Compiler is a command-line tool that you can use to compile all shaders and kernels from OpenGL ES and Vulkan, and generate a performance report for the GPU of interest. -In a terminal, test that Mali Offline Compiler is installed correctly, by typing: +## Before you begin + +Mali Offline Compiler is a command-line tool that you can use to compile shaders and kernels from OpenGL ES and Vulkan. The tool generates a performance report for the GPU of interest. + +To test that Mali Offline Compiler is installed correctly, run: ``` malioc --help ``` The `--help` option returns usage instructions and the full list of available options for the malioc command. -Note -{{% notice %}} +{{% notice Note %}} On macOS, Mali Offline Compiler might not be recognized as an application from an identified developer. To enable Mali Offline Compiler, open **System Preferences > Security & Privacy**, and select **Allow Anyway** for the `malioc` item. {{% /notice %}} -## Supported GPUs - -To see the full list of [supported GPUs](https://developer.arm.com/documentation/101863/latest/Platform-support/GPU-support) use: +To see the full list of [supported GPUs](https://developer.arm.com/documentation/101863/latest/Platform-support/GPU-support), use: ```console malioc --list ``` -To get information on [API support](https://developer.arm.com/documentation/101863/latest/Platform-support/API-support) for a given GPU, use: +For more information about [API support](https://developer.arm.com/documentation/101863/latest/Platform-support/API-support) for a given GPU, use: ```console malioc --info --core @@ -38,11 +40,13 @@ malioc --info --core ## Compile your shader -You can compile OpenGL ES (`--opengles`) and Vulkan (`--vulkan`) shader programs, as well as Open GL (`--opengl `) C kernels (Linux host only). +You can compile OpenGL ES (`--opengles`) and Vulkan (`--vulkan`) shader programs. On Linux hosts, you can also compile OpenGL (`--opengl `) C kernels. -A performance report will be generated. +Mali Offline Compiler generates a performance report. -An example (`OpenGL ES`) shader is provided in the [documentation](https://developer.arm.com/documentation/102468/latest/Compile-your-shader): +If your frame analysis points to shader cost, compile one of your shaders. You can also use this sample shader to learn how to read the report. + +The following example (`OpenGL ES`) shader is provided in [Compile your shader](https://developer.arm.com/documentation/102468/latest/Compile-your-shader) in Arm documentation: ```C #version 310 es #define WINDOW_SIZE 5 @@ -75,15 +79,17 @@ Compile the shader for [Mali-G76](https://developer.arm.com/Processors/Mali-G76) malioc --core Mali-G76 shader.frag ``` -The full list of available options can be seen with: +To view the full list of available options, run: + ```console malioc --help ``` -For more information, refer to [Compiling OpenGL ES shaders](https://developer.arm.com/documentation/101863/latest/Using-Mali-Offline-Compiler/Compiling-OpenGL-ES-shaders) and [Compiling Vulkan shaders](https://developer.arm.com/documentation/101863/latest/Using-Mali-Offline-Compiler/Compiling-Vulkan-shaders) in the Mali Offline Compiler User Guide. -## Analyze the report +For more information, see [Compiling OpenGL ES shaders](https://developer.arm.com/documentation/101863/latest/Using-Mali-Offline-Compiler/Compiling-OpenGL-ES-shaders) and [Compiling Vulkan shaders](https://developer.arm.com/documentation/101863/latest/Using-Mali-Offline-Compiler/Compiling-Vulkan-shaders) in the Mali Offline Compiler User Guide. + +## Interpret the report -The report will provide an approximate cycle cost breakdown for the major functional units in the design. Use this information to optimize your shader. +The report provides an approximate cycle cost breakdown for the major functional units in the design. Use this information to optimize your shader. For example, compiling the unoptimized implementation for `Mali-G76` reports the following cycle information: ```output @@ -94,7 +100,8 @@ Longest path cycles: 4.53 0.00 0.25 2.50 A A = Arithmetic, LS = Load/Store, V = Varying, T = Texture ``` -An example optimization is explained in the [documentation](https://developer.arm.com/documentation/102468/latest/Optimize-your-shader). +An example optimization is described in [Optimize your shader](https://developer.arm.com/documentation/102468/latest/Optimize-your-shader) in Arm documentation: + ```C #version 310 es #define WINDOW_SIZE 5 @@ -124,6 +131,7 @@ void main() { } ``` Compiling the optimized implementation reports: + ```output A LS V T Bound Total instruction cycles: 0.96 0.00 0.25 2.50 T @@ -131,6 +139,22 @@ Shortest path cycles: 0.54 0.00 0.25 2.50 T Longest path cycles: 0.96 0.00 0.25 2.50 T A = Arithmetic, LS = Load/Store, V = Varying, T = Texture ``` -Observe that the number of `Arithmetic` cycles has been significantly reduced. +Observe that the number of total `Arithmetic` cycles has been significantly reduced from 4.53 to 0.96. + +To learn more about interpreting Mali Offline Compiler reports, see the [Arm GPU Training - Episode 3.5: Mali Offline Compiler](https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Arm%20Mali%20GPU%20Training%20-%20EP3-5) video tutorial. + +## What you've accomplished + +You've used Mali Offline Compiler to analyze shader performance on a Mali-based GPU of interest. + +You can use the components and workflows described in this Learning Path to profile your applications and analyze performance using Arm Performance Studio. + +You can also explore the following supporting tools: -Understanding the output of the report is key to the usefulness of the Mali Offline Compiler. This brief [video tutorial](https://developer.arm.com/Additional%20Resources/Video%20Tutorials/Arm%20Mali%20GPU%20Training%20-%20EP3-5) is an excellent starter. +- [Unity Integration package](https://github.com/ARM-software/mobile-studio-integration-for-unity/) to add more application awareness — in the form of custom annotations and software counters — to Performance Advisor and Streamline profiling reports. +- [Unity System Metrics for Mali package](https://forum.unity.com/threads/introducing-system-metrics-mali-package.1126178/) to visualize frame-based Arm GPU performance metrics using the Unity profiler for efficient early triage of performance problems. +- [Godot integration package](https://github.com/ARM-software/arm-performance-studio-integration-for-godot) to export custom software counters and event annotations in Godot. +- [Arm ASTC Encoder texture compressor](https://github.com/ARM-software/astc-encoder) to compress and decompress textures using the Adaptive Scalable Texture Compression (ASTC) texture format. +- [libGPUInfo library](https://github.com/ARM-software/libGPUInfo) to query the configuration of the Arm GPU present in the system to adjust the application workload at runtime. +- [libGPUCounters library](https://github.com/ARM-software/libGPUCounters) to select and sample a set of Arm GPU performance counters for integration of Arm GPU data into custom tooling. +- [libGPULayers library](https://github.com/ARM-software/libGPULayers) to create new Vulkan layers for Android development. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md b/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md index be3098a655..d90c7ba538 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/pa.md @@ -1,13 +1,18 @@ --- # User change -title: "Performance Advisor with your application" +title: Create a Performance Advisor report for your application + +description: Run streamline_me.py, capture extra frame data with Streamline, and generate HTML and JSON Performance Advisor reports for your application. weight: 7 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -Now that you have seen a [Performance Advisor example report](/learning-paths/mobile-graphics-and-gaming/ams/pa_example/), you can use it to capture data from your own application. + +## Connect to Android device and collect frame data + +Now that you've seen a [Performance Advisor example report](/learning-paths/mobile-graphics-and-gaming/ams/pa_example/), you can use it to capture data from your own application. Performance Advisor runs on a Streamline capture file, so the first step is to take a capture with Streamline. Streamline must capture extra frame data from the device, which Performance Advisor needs to generate a report. To capture the extra frame data, you must first run the provided Python script, `streamline_me.py`. @@ -15,33 +20,27 @@ This script does the following: * Temporarily installs a daemon application on your device, called `gatord`, which Streamline uses to collect counter data. * Temporarily installs the OpenGL ES or Vulkan layer library file on your device, which is needed to collect frame data. -* Enables you to specify options for the capture, such as whether to collect screenshots when the FPS drops below a certain threshold. - -## Before you begin - -Performance Advisor uses a Python script to connect to your device. You will need `Python 3.8` or later installed on your host machine. - -Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). +* Allows you to specify options for the capture, such as whether to collect screenshots when the FPS drops below a certain threshold. -## Connect to the device +To connect to the Android device and capture frame data: -1. Open a terminal or command prompt, navigate to the `Arm Performance Studio` install directory and locate the `streamline_me.py` script: +1. Open a terminal or command prompt, navigate to the Arm Performance Studio install directory and locate the `streamline_me.py` script: ```console cd /streamline/bin/android ``` -1. Run the script, enabling frame boundaries, with: +2. Run the script, enabling frame boundaries, with: ```console python3 streamline_me.py --lwi-mode=counters ``` {{% notice Tip %}} -To see all available options, use `python3 streamline_me.py --help` +To see all available options, use `python3 streamline_me.py --help`. {{% /notice %}} -1. The script returns a numbered list of the Android package names for the debuggable applications that are installed on your device. Enter the number of the application you want to profile. +3. The script returns a numbered list of the Android package names for the debuggable applications that are installed on your device. Enter the number of the application you want to profile. ```python Searching for devices: @@ -64,42 +63,46 @@ To see all available options, use `python3 streamline_me.py --help` The script identifies the GPU in the device, installs the daemon application and layer library, then waits for you to complete the capture in Streamline. -1. Leave the terminal window open, as you need to come back to it after the capture is complete, to stop the script. When the script ends, any captured screenshots are saved to the directory you specified, and the daemon application and layer library are uninstalled from the device. Do not unplug the device until the script has ended. +{{% notice Note %}} +Leave the terminal window open, as you need to come back to it after the capture is complete, to stop the script. -See the [Get started with Performance Advisor Tutorial](https://developer.arm.com/documentation/102478/latest/Run-the-streamline-me-py-script) for full instructions. +When the script ends, any captured screenshots are saved to the directory you specified, and the daemon application and layer library are uninstalled from the device. Don't unplug the device until the script has ended. +{{% /notice %}} + +For full instructions, see the [Get started with Performance Advisor Tutorial](https://developer.arm.com/documentation/102478/latest/Run-the-streamline-me-py-script). ## Capture data with Streamline -1. Open Streamline and select the device and application on the `Start` tab. +1. Open Streamline and select the device and application on the **Start** tab. -1. Click `Start capture` to start capturing profile data from the target. Enter a name and location for the capture file that Streamline creates. +2. Select **Start capture** to start capturing profile data from the target. Enter a name and location for the capture file that Streamline creates. -1. The application starts automatically on the device. Interact with the application as required. +3. The application starts automatically on the device. Interact with the application as required. -1. When you have collected enough data, click the `Stop capture` button. +4. When you've collected enough data, select **Stop capture**. -1. Return to your terminal, and press `ENTER` to terminate the `streamline_me.py` script. +5. Return to your terminal, and press `ENTER` to terminate the `streamline_me.py` script. ## Generate an HTML performance report 1. In the terminal window, navigate to the location where you stored the Streamline capture file (`.apc`). -1. Run Streamline's `streamline-cli` command with the `-pa` option on the Streamline capture file to generate the report. The default name is `report.html`. +2. Run Streamline's `streamline-cli` command with the `-pa` option on the Streamline capture file to generate the report. The default name is `report.html`. ```console streamline-cli -pa my_capture.apc ``` - The available options are documented in the [Performance Advisor User Guide](https://developer.arm.com/documentation/102009/latest/Command-line-options/The-pa-command), else can be seen with: + For a list of available options, see [The Streamline-cli -pa command](https://developer.arm.com/documentation/102009/9-7/Command-line-options/The-Streamline-cli--pa-command) in Arm documentation, or run the following command: ```console streamline-cli -pa -h ``` - To pass a list of options in a separate file to `Streamline-cli -pa`, use: + To pass a list of options in a separate file to `streamline-cli -pa`, use: ``` - Streamline-cli -pa "@" + streamline-cli -pa "@" ``` ## Generate a JSON performance report @@ -108,11 +111,17 @@ This feature is particularly useful when used within a [CI workflow](https://dev 1. In the terminal window, navigate to the location where you stored the Streamline capture file (`.apc`). -1. Run Streamline's `streamline-cli` command with the `-pa` and `--type=json` options on the Streamline capture file to generate the report (named `report.json` in below): +2. Run Streamline's `streamline-cli` command with the `-pa` and `--type=json` options on the Streamline capture file to generate the report named `report.json`: ```console streamline-cli -pa --type=json:report.json my_capture.apc ``` -## Performance budgets +## Specify performance budgets + +You can specify a performance budget that is reflected in the Performance Advisor report. For more information, see [Setting performance budgets](https://developer.arm.com/documentation/102009/latest/Quick-start-guide/Setting-performance-budgets) in Arm documentation. + +## What you've accomplished and what's next + +You've now generated JSON and HTML Performance Advisor reports for your application. -You can specify a performance budget which will be reflected in the Performance Advisor report. For more information, refer to the [Performance Advisor User Guide](https://developer.arm.com/documentation/102009/latest/Quick-start-guide/Setting-performance-budgets) section on performance budgets. +Next, you'll perform frame-based analysis on your application using Frame Advisor. \ No newline at end of file diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/pa_example.md b/content/learning-paths/mobile-graphics-and-gaming/ams/pa_example.md index ef80a4fa31..99a6b696da 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/pa_example.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/pa_example.md @@ -1,25 +1,28 @@ --- # User change -title: "Performance Advisor example report " +title: View an example Performance Advisor report + +description: Generate an example Performance Advisor report from the sample Streamline capture and review the capture summary. weight: 6 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -Performance Advisor creates an easy-to-read report from a Streamline capture. This helps you quickly understand how your Android application performed on a mobile device. ## Generate a performance report -The supplied [Arm Streamline example capture](/learning-paths/mobile-graphics-and-gaming/ams/streamline_example/) can be used to generate a `Performance Advisor` report. +Performance Advisor creates an easy-to-read report from a Streamline capture that you can use to understand how your Android application performs on a mobile device. + +You can use the [Arm Streamline example capture](/learning-paths/mobile-graphics-and-gaming/ams/streamline_example/) that comes with Arm Performance Studio to generate an example Performance Advisor report. 1. Open a terminal, and navigate to the location of the imported capture. -1. Run the `streamline-cli` command with the `-pa` option on the Streamline capture file (.apc): +1. Run the `streamline-cli` command with the `-pa` option on the Streamline capture file (`.apc`): ```command streamline-cli -pa "Android - GPU Bound Example.apc" ``` - The capture is processed, and a `html` report generated. Warnings shown can be ignored for now: + The capture is processed, and an HTML report is generated. For now, you can ignore the warnings shown: ```output Importing capture... Fetching data... @@ -28,9 +31,15 @@ The supplied [Arm Streamline example capture](/learning-paths/mobile-graphics-an Generating report type html... Report performance_advisor-.html" successfully generated ``` - Open the report in a browser and explore the report. - ![Performance Advisor #center](images/pa.png "Performance Advisor report") + Open the report in a browser and review the summary. + ![Screenshot of a Performance Advisor report showing device information, capture summary, average frame rate, boundedness distribution, and resource utilization#center](images/pa.png "Performance Advisor report") ## Evaluate the report -Refer to the [Performance Advisor tutorial](https://developer.arm.com/documentation/102478/latest/Example-Performance-Advisor-report) for a detailed explanation about the charts in the report. +For a detailed explanation on how to interpret the report, see the [Example Performance Advisor report tutorial](https://developer.arm.com/documentation/102478/latest/Example-Performance-Advisor-report) in Arm documentation. + +## What you've accomplished and what's next + +You've created a Performance Advisor report from the example Streamline capture and seen how the report summarizes application performance. + +Next, you'll create a report for your application. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md b/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md index f5e529c70b..fd429c3f20 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/renderdoc.md @@ -1,52 +1,61 @@ --- # User change -title: "RenderDoc for Arm GPUs" +title: Debug your application with RenderDoc for Arm GPUs + +description: Connect RenderDoc for Arm GPUs to an Android target, capture frames, and inspect events and GPU output for debugging. weight: 9 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -[RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) is an Arm fork of the [RenderDoc](https://renderdoc.org/) open-source debugger. The Arm release includes support for API features and extensions that are available on the latest Arm GPUs, but not yet supported in upstream RenderDoc. Arm intends to contribute changes to the upstream project, but some Arm-specific or Android-specific features may only be available in the Arm fork. -## Prerequisites +## Run RenderDoc for Arm GPUs + +[RenderDoc for Arm GPUs](https://developer.arm.com/Tools%20and%20Software/RenderDoc%20for%20Arm%20GPUs) is an Arm fork of the [RenderDoc](https://renderdoc.org/) open-source debugger. -Build your application, and setup the Android device as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). +The Arm release includes support for API features and extensions that are available on the latest Arm GPUs, but not yet supported in upstream RenderDoc. Arm intends to contribute changes to the upstream project, but some Arm-specific or Android-specific features might be available only in the Arm fork. -## Connect to the device +To run RenderDoc for Arm GPUs: 1. Open RenderDoc for Arm GPUs and select your connected device from the **Replay Context** dropdown list at the bottom left of the RenderDoc UI. - ![Replay Context dropdown location in RenderDoc](images/rd_replay_context.png) + ![Screenshot of the RenderDoc Replay Context selector at the bottom left, where you choose the connected Android target before launching the app#center](images/rd_replay_context.png) The RenderDoc APK starts running on your target. - If you don't see your device, check that your device is setup correctly as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). + If you don't see your device, check that your device is set up correctly as described in [Setup tasks](/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks/). -1. Navigate to the **Launch Application** tab, and set the Executable Path to the application that you want to debug. Click the **Browse** button to view all of the installed application packages on the target and find the `.exe` file. +2. Navigate to the **Launch Application** tab, and set the **Executable Path** to the application that you want to debug. Select the **Browse** button to view all of the installed application packages on the target and find the `.exe` file. -1. Click **Launch**, to start the application running on your target. After a successful launch, a new target-specific tab opens in the UI where you can select the frames that you want to capture. +3. Select **Launch**, to start the application running on your target. After a successful launch, a new target-specific tab opens in the UI where you can select the frames that you want to capture. - ![Capture frame controls in RenderDoc](images/rd_capture_controls.png) + ![Screenshot of RenderDoc for Arm GPUs showing an established Android target connection, capture frame controls, and collected frame thumbnails#center](images/rd_capture_controls.png) As your application runs, you can choose to: - * Capture one or more frames immediately - * Capture one or more frames after a delay - * Capture one or more frames after a specific frame + - Capture one or more frames immediately + - Capture one or more frames after a delay + - Capture one or more frames after a specific frame Use these controls to take captures of your application as it runs on the target device. Captured frames are stored temporarily on the device. -1. When you have finished capturing the frames of interest, stop the application that you are debugging. Keep RenderDoc running though, as this is needed so that you can analyze and debug your captures. +4. When you've finished capturing the frames of interest, stop the application that you are debugging. Keep RenderDoc running so that you can analyze and debug your captures. -1. Select a capture from the **Captures collected** window and click **Open**. When the frame has loaded, it is displayed on the target and in the **Texture Viewer** tab, and the **Event Browser** is populated. +5. Select a capture from the **Captures collected** window and select **Open**. When the frame has loaded, it's displayed on the target and in the **Texture Viewer** tab, and the **Event Browser** is populated. - ![A captured frame loaded into RenderDoc](images/rd_full_ui.png) + ![Screenshot of a captured frame opened in RenderDoc showing the Event Browser, Texture Viewer, API Inspector, and output preview for the selected event#center](images/rd_full_ui.png) By default, the **Event Browser** shows all `action()` events, which include draws, copies, and clears. Enter a search term in the **Filter** dropdown to filter these events. - ![Event Browser in RenderDoc](images/rd_event_browser.png) + ![Screenshot of the RenderDoc Event Browser filtered for draw events with a selected draw call highlighted for debugging frame state#center](images/rd_event_browser.png) + + Selected events are highlighted with a green flag. The other windows in the UI update to display information for the selected event, including the render state, data resources, and GPU output. + +For a full list of features, see the [RenderDoc documentation](https://renderdoc.org/docs/index.html#). + +## What you've accomplished and what's next - Selected events are highlighted with a green flag. All the other windows in the UI update to display information that is specific to the selected event. You can use this to view the render state and data resources that are used by the current event, and view the GPU output that resulted from it. +You've now run RenderDoc for Arm GPUs on your application and learned how to capture frames and select events for debugging. -See the [RenderDoc documentation](https://renderdoc.org/docs/index.html#) to explore the full list of features. \ No newline at end of file +Next, you'll run Mali Offline Compiler to compile shaders and generate performance reports. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md b/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md index 4efb4d6f45..09b579b4cb 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/setup_tasks.md @@ -1,44 +1,29 @@ --- # User change -title: "Setup tasks" +title: Set up an Android application for profiling + +description: Prepare a debuggable Android application and device connection so Arm Performance Studio can capture profiling data. weight: 3 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -## Installation - -1. Install Arm Performance Studio by following the instructions in the [Arm Performance Studio install guide](/install-guides/ams/). Details about changes since the last release can be found in the [Release Note](https://developer.arm.com/documentation/107649/latest/). -1. Ensure you have installed [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb). `adb` is available with the Android SDK platform tools, which are installed as part of Android Studio. Alternatively, you can download them separately as part of the Android SDK platform tools. -1. Performance Advisor uses a Python script to connect to your device. To run this script, you will need [Python](https://www.python.org/downloads/) 3.8 or later installed. - -## Update your PATH environment variable (Linux and macOS) - -Edit your `PATH` environment variable to add the paths to the Streamline and Mali Offline Compiler executables. This is so that you can run Streamline's `Streamline-cli -pa` command and Mali Offline Compiler's `malioc` command from any directory. This step is not necessary on Windows, as this is done automatically when Arm Performance Studio is installed. - -On macOS, edit your `/etc/paths` file to add the following paths: +## Before you begin -``` -//streamline -//mali_offline_compiler -``` +Complete the following prerequisites: -On Linux, edit your `PATH` environment variable to add the paths to the Performance Advisor executable. Add this command to the `.bashrc` file in your home directory, so that this environment variable is set whenever you initialize a shell session. - - ``` - PATH=$PATH://streamline - PATH=$PATH://mali_offline_compiler -``` +1. Install [Android Debug Bridge (adb)](https://developer.android.com/studio/command-line/adb). `adb` is available with the Android SDK platform tools, which are installed as part of Android Studio. +2. Performance Advisor uses a Python script to connect to your device. To run this script, you'll need [Python](https://www.python.org/downloads/) 3.8 or later installed. ## Build your application -The application must be compiled with debug enabled, as well as additional options to facilitate call stack unwinding by Streamline. +Compile the application with debug enabled, as well as additional options to facilitate call stack unwinding by Streamline. -* To set [Unity](https://unity.com/) applications to be debuggable, enable [Development Build](https://docs.unity3d.com/6000.0/Documentation/Manual/android-BuildProcess.html) in `Build settings`. -* In Android Studio, use a build variant that includes `debuggable true` (`isDebuggable = true` in Kotlin scripts) in the build configuration. -* In Unreal Engine, open `Project Settings > Project > Packaging > Project`, and ensure that the `For Distribution` checkbox is not set. -* For C++ or Java applications, refer to the [Target setup guide for Android](https://developer.arm.com/documentation/101813/latest/Target-Setup/Compile-your-application) for instructions on how to compile your application with the right options. +- To set [Unity](https://unity.com/) applications to be debuggable, enable **[Development Build](https://docs.unity3d.com/6000.0/Documentation/Manual/android-BuildProcess.html)** in **Build settings**. +- In Android Studio, use a build variant that includes `debuggable true` (`isDebuggable = true` in Kotlin scripts) in the build configuration. +- In Unreal Engine, open **Project Settings > Project > Packaging > Project**, and ensure that the **For Distribution** checkbox isn't set. +- For instructions to compile your C++ or Java applications with the right options, see the [Target setup guide for Android](https://developer.arm.com/documentation/101813/latest/Target-Setup/Compile-your-application). {{% notice Tip %}} To assist with readability and add context, you can optionally include [annotations](https://developer.arm.com/documentation/101816/latest/Annotate-your-code/Add-annotations-to-your-code) in your code, which are then displayed in Streamline. @@ -46,10 +31,12 @@ To assist with readability and add context, you can optionally include [annotati ## Set up the Android device -1. On the device, ensure that [Developer Mode](https://developer.android.com/studio/debug/dev-options) is enabled. -1. Enable `USB Debugging` under `Settings > Developer options`. If your device asks you to authorize connection to your computer, confirm the connection. -1. Connect the device to the host through USB and approve the debug connection on the device when prompted. -1. To test the connection, run the `adb devices` command in a command terminal. If successful, this returns the ID of your device: +To set up your Android device, follow these steps: + +1. On the device, ensure that **[Developer Mode](https://developer.android.com/studio/debug/dev-options)** is enabled. +2. Enable **USB Debugging** under **Settings > Developer options**. If your device asks you to authorize connection to your computer, confirm the connection. +3. Connect the device to the host through USB and approve the debug connection on the device when prompted. +4. To test the connection, run the `adb devices` command in a terminal. If successful, this returns the ID of your device: ```command adb devices @@ -59,4 +46,10 @@ To assist with readability and add context, you can optionally include [annotati If you see that the device is listed as `unauthorized`, try disabling and re-enabling `USB Debugging` on the device, and accept the authorization prompt to enable connection to the computer. -1. Install the [debuggable](https://developer.android.com/studio/debug) application on the device. +5. Install the [debuggable](https://developer.android.com/studio/debug) application on the device. + +## What you've accomplished and what's next + +You've now set up your Android device and built the application you'll use for profiling. + +Next, you'll look at an example Arm Streamline report to understand the Streamline component of Arm Performance Studio. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md index e6de786905..8e39003cc7 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline.md @@ -1,47 +1,58 @@ --- # User change -title: "Streamline with your application" +title: Use Arm Streamline to capture data for your application + +description: Capture a Streamline profile from your Android application and inspect timeline counters to start performance analysis. weight: 5 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -Now that you have seen an [Arm Streamline example capture](/learning-paths/mobile-graphics-and-gaming/ams/streamline_example/), you can use it to capture data from your own application. ## Select the device and application in Streamline +Now that you've seen an [Arm Streamline example capture](/learning-paths/mobile-graphics-and-gaming/ams/streamline_example/), you can use it to capture data from your own application. + 1. Launch the Performance Studio Hub and open Streamline. - On Windows, search for Performance Studio. - On macOS and Linux, open the Performance Studio application file from the install directory. - ![Performance Studio Hub](images/ps_hub.png) + ![Screenshot of the Arm Performance Studio Hub showing the Streamline launch card used to open Streamline#center](images/ps_hub.png) -1. In the Streamline `Start` view, select `Android (adb)` as your device type, then select your device from the list of detected devices. This installs the `gatord` daemon and connects to the device. +2. In the Streamline **Start** view, select **Android (adb)** as your device type, then select your device from the list of detected devices. This installs the `gatord` daemon and connects to the device. -1. Wait for the list of available packages to populate, then select the one you wish to profile. -1. With `Capture Arm GPU profile` selected, Streamline will detect the Arm GPU in the device, and select an appropriate counter template for it. Alternatively, to choose a different template or to build your own configuration, select `Use advanced mode` and click `Configure counters`. +3. Wait for the list of available packages to populate, then select the application you want to profile. +4. With **Capture Arm GPU profile** selected, Streamline detects the Arm GPU in the device, and selects an appropriate counter template for it. Alternatively, to choose a different template or to build your own configuration, select **Use advanced mode** and select **Configure counters**. - ![Connect to device #center](images/start.png "Connect to the device") + ![Screenshot of the Streamline Start view with Android adb selected, a connected Samsung device selected, a debuggable application selected, and Capture Arm GPU profile enabled#center](images/start.png "Connect to the device") {{% notice Tip %}} -Optionally, you can set a preferred location to store your captures using `Window` > `Preferences` > `Data Locations`. New reports will be created in the topmost folder specified. +Optionally, you can set a preferred location to store your captures using **Window** > **Preferences** > **Data Locations**. New reports are created in the topmost folder specified. {{% /notice %}} ## Capture data -1. Click `Start capture` to start capturing profile data from the device. Enter a name and location for the capture file. +1. Select **Start capture** to start capturing profile data from the device. Enter a name and location for the capture file. -1. The application starts automatically on the device. Interact with the application as desired for the profiling run you wish to do. +2. The application starts automatically on the device. Interact with the application as desired for the profiling run you want to do. -1. When you have collected enough data, click `Stop capture`. -![Stop capture #center](images/stop_capture.webp "Stop Capture") +3. When you've collected enough data, select **Stop capture**. +![Screenshot of Streamline during a capture with the Stop capture button highlighted and performance charts updating in the Timeline view#center](images/stop_capture.webp "Stop Capture") -Streamline will stop capturing data, remove the daemon, and process the captured data. +Streamline stops capturing data, removes the daemon, and processes the captured data. ## Analyze the results -The charts in the `Timeline` view show the performance counter activity captured from the device. Hover over the charts to see the values at that point in time. Use the Calipers to focus on particular windows of activity. Refer to the [Streamline User Guide](https://developer.arm.com/documentation/101816/latest/Analyze-your-capture) for full instructions on how to use the features in the `Timeline` view. +The charts in the **Timeline** view show the performance counter activity captured from the device. Hover over the charts to see the values at that point in time. Use the Calipers to focus on particular windows of activity. + +For instructions to use the features in the **Timeline** view, see the [Streamline User Guide](https://developer.arm.com/documentation/101816/latest/Analyze-your-capture). + +To understand how to interpret the capture from different points of view, see [Android performance triage with Streamline](https://developer.arm.com/documentation/102540/latest/). + +## What you've accomplished and what's next + +You've now generated and analyzed an Arm Streamline report for your application. -Understanding the output of Streamline is key to the usefulness of Streamline. The documentation for [Android performance triage with Streamline](https://developer.arm.com/documentation/102540/latest/) on Arm Developer describes how to understand the capture from a number of points of view, depending on what information you are trying to extract from it. +Next, you'll view an example Performance Advisor report. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline_example.md b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline_example.md index 0073e1364d..f4c3283e07 100644 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/streamline_example.md +++ b/content/learning-paths/mobile-graphics-and-gaming/ams/streamline_example.md @@ -1,30 +1,39 @@ --- # User change -title: "Arm Streamline example capture" +title: Interpret an example Arm Streamline report + +description: Import and inspect the sample Streamline capture included with Arm Performance Studio so you can recognize key timeline views before profiling your app. weight: 4 # 1 is first, 2 is second, etc. # Do not modify these elements layout: "learningpathall" --- -This learning path explores Streamline for Android application profiling on a mobile device. For other use cases, refer to the supporting materials for [Arm Development Studio](https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio). -## Example Streamline report +## View the example Arm Streamline report -To help you understand the capabilities of Streamline, an example Streamline profile is provided with Arm Performance Studio. +To understand the capabilities of Streamline, use the example Streamline profile that comes with Arm Performance Studio. -1. To open the example profile, in Streamline, select `File` > `Import`. -1. Select `Import Streamline Sample Captures` and click `Next`. - ![Import #center](images/import.png "Import Streamline Sample Captures") +1. To open the example profile, in Streamline, select **File** > **Import**. +2. Select **Import Streamline Sample Captures** and click **Next**. + ![Screenshot of the Streamline Import dialog with Import Streamline Sample Captures selected before clicking Next#center](images/import.png "Import Streamline Sample Captures") -1. Select the Android example and click `Finish`. - ![Samples #center](images/samples.png "Select sample captures") +3. Select the Android example and click **Finish**. + ![Screenshot of the Import Sample Captures dialog with the Android GPU Bound Example selected before clicking Finish#center](images/samples.png "Select sample captures") -1. Double-click on the report in `Streamline Data`, then click `Analyze` when prompted. The report will be processed, and an interactive timeline will be shown. -![Timeline #center](images/timeline.png "Streamline Timeline") +4. Select the report in **Streamline Data**, then select **Analyze** when prompted. After the report is processed, you'll see an interactive timeline. +![Screenshot of the Streamline Timeline tab for the Android GPU Bound Example showing CPU cycles, draw calls, frame rate, Mali core cycles, and process activity#center](images/timeline.png "Streamline Timeline") ## Analyze the results -The charts in the `Timeline` view show the performance counter activity captured from the device. Hover over the charts to see the values at that point in time. Use the Calipers to focus on particular windows of activity. Refer to the [Streamline User Guide](https://developer.arm.com/documentation/101816/latest/Analyze-your-capture) for full instructions on how to use the features in the `Timeline` view. +The charts in the **Timeline** view show the performance counter activity captured from the device. Hover over the charts to see the values at that point in time. Use the Calipers to focus on particular windows of activity. + +For instructions to use the features in the **Timeline** view, see the [Streamline User Guide](https://developer.arm.com/documentation/101816/latest/Analyze-your-capture). + +Understanding the output of Streamline is key to the tool's usefulness. To understand how to interpret the capture from different points of view, see [Android performance triage with Streamline](https://developer.arm.com/documentation/102540/latest/). + +## What you've accomplished and what's next + +You've now viewed an example Arm Streamline report and interpreted the results using Arm documentation. -Understanding the output of Streamline is key to the usefulness of Streamline. [Android performance triage with Streamline](https://developer.arm.com/documentation/102540/latest/) describes how to understand the capture from a number of points of view, depending on what information you are trying to extract from it. +Next, you'll use Arm Streamline to capture data for your application. diff --git a/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md b/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md deleted file mode 100644 index adec0314da..0000000000 --- a/content/learning-paths/mobile-graphics-and-gaming/ams/supporting_tools.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -# User change -title: "Supporting tools" - -weight: 11 # 1 is first, 2 is second, etc. - -# Do not modify these elements -layout: "learningpathall" ---- - -Arm provides the following projects to further assist application developers: - -[Unity Integration package](https://github.com/ARM-software/mobile-studio-integration-for-unity/). Integrate this package in to your Unity application during development and gain the ability to add more application awareness to Performance Advisor and Streamline profiling reports. This package exports key software counters from the Unity profiler to Streamline, and also exports a C# API to allow developers to export custom annotations and software counters that can be visualized in performance reports. - -[Unity System Metrics for Mali package](https://forum.unity.com/threads/introducing-system-metrics-mali-package.1126178/). Integrate this package in to your Unity application during development and visualize frame-based Arm GPU performance metrics using the Unity profiler. This allows efficient early triage of performance problems in-editor, allowing developers to switching to Streamline only when they need to investigate rendering performance issues in more detail. - -[Godot integration package](https://github.com/ARM-software/arm-performance-studio-integration-for-godot). This package provides an open-source Godot game engine integration for Streamline and Performance Advisor. It contains GDScript bindings for the Streamline annotation API, allowing users to export custom software counters, and event annotations. - -[Arm ASTC Encoder texture compressor](https://github.com/ARM-software/astc-encoder) is an open-source texture compressor for the Adaptive Scalable Texture Compression (ASTC) texture format. It supports all block sizes, all color profiles, as well as both 2D and volumetric 3D textures. The astcenc compressor can be built as either a standalone command-line application or a library that can be integrated into an existing asset creation pipeline. - -[libGPUInfo library](https://github.com/ARM-software/libGPUInfo) is an open-source utility that can be integrated into an application to query the configuration of the Arm GPU present in the system, including the GPU model, shader core count, shader core performance characteristics, and cache size. This information can be used to adjust the application workload at runtime to match the capabilities of the device being used. - -[libGPUCounters library](https://github.com/ARM-software/libGPUCounters) is an open-source utility that allows applications to select and sample a set of Arm GPU performance counters. This library provides access to the same counter data that can be visualized in the Streamline tool, allowing integration of Arm GPU data into custom tooling. - -[libGPULayers library](https://github.com/ARM-software/libGPULayers) is an open-source project that provides tooling to quickly create new Vulkan layers for Android, as well as some off-the-shelf layers that can be used during development. diff --git a/content/learning-paths/servers-and-cloud-computing/_index.md b/content/learning-paths/servers-and-cloud-computing/_index.md index 5a33c82da3..3ac5354a08 100644 --- a/content/learning-paths/servers-and-cloud-computing/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/_index.md @@ -12,10 +12,10 @@ pinned_learning_paths: - performix-microarchitecture operatingsystems_filter: - Android: 3 -- Linux: 223 -- macOS: 15 +- Linux: 260 +- macOS: 17 - other: 1 -- Windows: 14 +- Windows: 16 pinned_modules: - module: name: Recommended getting started learning paths @@ -23,14 +23,14 @@ pinned_modules: - providers - migration subjects_filter: -- CI-CD: 13 -- Containers and Virtualization: 41 -- Databases: 24 +- CI-CD: 14 +- Containers and Virtualization: 49 +- Databases: 29 - Libraries: 9 -- ML: 32 -- Performance and Architecture: 89 +- ML: 41 +- Performance and Architecture: 102 - Storage: 2 -- Web: 17 +- Web: 18 subtitle: Migrate and optimize cloud native apps on Arm-based servers. title: Servers and Cloud Computing tools_software_languages_filter: @@ -40,54 +40,64 @@ tools_software_languages_filter: - ACL: 1 - ActiveGate: 1 - AI: 1 +- Alluxio: 1 +- Amazon Elastic Container Service (Amazon ECS): 1 - Android Studio: 1 - Ansible: 2 - Apache: 1 - Apache Arrow: 1 - Apache Beam: 1 - Apache Cassandra: 1 -- Apache Spark: 2 +- Apache Spark: 4 - Apache Tomcat: 2 - ApacheBench: 1 - Argo CD: 1 - Arm Compiler for Linux: 1 - Arm Development Studio: 3 - Arm ISA: 1 -- Arm Performance Libraries: 2 -- Arm Performix: 2 +- Arm Performance Libraries: 3 +- Arm Performix: 7 - Arm Streamline: 1 +- Arm System Characterization Tool: 1 - armclang: 1 - armie: 1 - ArmRAL: 1 - Arrow Flight: 1 +- ASCT: 1 - ASP.NET Core: 2 - Assembly: 5 - async-profiler: 1 - Autocannon: 1 - AWS: 2 +- AWS CDK CLI: 1 +- AWS CLI: 1 - AWS Cloud Formation: 1 - AWS CodeBuild: 1 - AWS EC2: 3 - AWS Elastic Container Service (ECS): 1 -- AWS Elastic Kubernetes Service (EKS): 3 +- AWS Elastic Kubernetes Service (EKS): 4 - AWS Graviton: 1 +- AWS IoT Greengrass: 1 - AWS Lambda: 1 -- Azure: 1 -- Azure CLI: 3 +- Azure: 2 +- Azure CLI: 4 - Azure Portal: 1 -- Bash: 3 +- Bash: 8 - bash: 2 - Bastion: 3 +- Benchstat: 1 - BOLT: 3 +- boto3: 1 - bpftool: 1 - Buildkite: 1 -- C: 14 +- C: 15 - C#: 2 -- C++: 3 +- C++: 5 - Capstone: 1 - Cargo: 1 - cassandra-stress: 1 - CCA: 9 +- ChromaDB: 1 - CircleCI: 2 - Clair: 1 - Clang: 13 @@ -95,42 +105,51 @@ tools_software_languages_filter: - ClickHouse: 2 - Cloud Build: 1 - Cloud SQL (PostgreSQL): 1 -- CMake: 2 +- CMake: 6 - Confidential Containers: 1 - Couchbase: 1 -- CPP: 15 +- CPP: 16 - cqlsh: 1 - Criterion: 1 +- DeepSpeed: 1 - Demo: 3 +- DevStack: 1 - Django: 2 -- Docker: 35 +- Docker: 38 - Docker Buildx: 1 - Dynatrace: 1 +- Elasticsearch: 1 - Envoy: 3 - Erlang: 1 +- ESRally: 1 - ExecuTorch: 1 - Facter: 1 +- FastAPI: 1 - Fastpath: 1 +- fio: 1 - FlameGraph: 1 -- Flask: 1 +- Flask: 4 - Flink: 2 +- Flyte: 1 - Fortran: 1 - FunASR: 1 - FVP: 8 - Gardener: 1 -- GCC: 28 +- GCC: 30 - gdb: 1 - Geekbench: 1 - Generative AI: 13 +- Gerrit: 1 - Git: 2 - GitHub: 3 - GitHub Actions: 3 - GitHub CLI: 1 -- GitHub Copilot: 2 +- GitHub Copilot: 3 - GitLab: 2 - GKE: 3 - glibc: 1 -- Go: 4 +- Gluten: 1 +- Go: 5 - Golang: 1 - Google Artifact Registry: 1 - Google Axion: 3 @@ -141,121 +160,152 @@ tools_software_languages_filter: - Google Test: 1 - Grafana: 1 - Groovy (Jenkins Pipeline): 1 +- gRPC: 1 +- Hadoop: 1 - HammerDB: 1 -- Helm: 3 +- Helm: 4 - Herd7: 1 - Hiera: 1 -- Hugging Face: 12 +- Hive: 1 +- Hugging Face: 13 - InnoDB: 1 - Intrinsics: 1 - iPerf3: 1 - ipmitool: 1 - Jaeger: 1 -- Java: 6 +- Java: 10 +- JavaScript: 1 - JAX: 1 - Jenkins: 1 - JMH: 1 - JSON: 1 +- K3s: 2 - Kafka: 2 - Kata Containers: 1 - KEDA: 1 - Kedify: 1 - Keras: 2 +- Keycloak: 1 - KinD: 1 - Kiro: 1 +- Kolla-Ansible: 1 - kube-bench: 1 - kubectl: 2 -- Kubernetes: 17 +- Kubernetes: 20 - Libamath: 2 - libbpf: 1 - Linaro Forge: 1 - Linux: 1 +- Linux kernel: 1 - Litmus7: 1 - llama.cpp: 2 - Llama.cpp: 2 +- LlamaIndex: 1 - LLM: 11 - LLVM: 1 - llvm-mca: 1 - LM Evaluation Harness: 1 +- Longhorn: 1 - LSE: 1 - MariaDB: 1 - Maven: 1 -- MCP: 3 +- MCP: 6 - Memcached: 2 - Memorystore (Redis): 1 -- MinIO: 1 +- MinIO: 2 +- MLflow: 1 - MLPerf: 1 - ModelScope: 1 - MongoDB: 4 - mongostat: 1 - mongotop: 1 - mpi: 1 -- MySQL: 10 +- MQTT: 1 +- MySQL: 11 - Neon: 7 - Networking: 1 - Nexmark: 1 -- NGINX: 7 +- NGINX: 8 - nginx: 1 -- Node.js: 5 +- Node.js: 6 - node.js: 1 - npm: 3 -- Ollama: 1 +- NumPy: 1 +- Ollama: 2 - ONNX Runtime: 2 - OpenBLAS: 1 - OpenBMC: 1 +- OpenCV: 1 +- OpenEBS: 1 +- OpenJDK: 1 - OpenJDK 17: 1 - OpenJDK 21: 2 +- OpenRNG: 1 - OpenShift: 1 +- OpenStack: 1 +- OpenStack CLI: 1 - Orchard Core: 1 - PAPI: 1 -- perf: 8 -- Perf: 1 +- perf: 10 +- Perf: 2 +- pgbench: 1 - PHP: 1 - PHPBench: 1 - pika: 1 -- PostgreSQL: 7 +- PostgreSQL: 9 - Profiling: 1 - Prometheus: 1 - psycopg2: 1 - Puppet: 1 - Pytest: 1 -- Python: 37 +- Python: 52 - Python 3.11: 1 -- PyTorch: 10 +- PyTorch: 13 +- Qdrant: 1 - QEMU: 1 +- QuantLib: 1 - RabbitMQ: 1 +- Rafay: 1 - RAG: 1 - Rails: 1 -- Redis: 5 +- Ray: 1 +- rctl: 1 +- Redis: 6 - redis-benchmark: 1 - Remote.It: 2 - RME: 9 - Ruby: 2 -- Runbook: 73 +- Runbook: 74 - Rust: 3 +- scikit-learn: 2 +- Sentence Transformers: 1 - Service Mesh: 1 - Siege: 1 - Skaffold: 1 - SME2: 1 - snappy: 1 - Snort3: 1 -- SQL: 8 +- SQL: 9 +- SSH: 2 - Streamline CLI: 1 - Streamlit: 2 - Supervisor: 1 -- SVE: 5 +- SVE: 6 - SVE2: 2 +- sysbench: 1 - Sysbench: 1 +- Sysreport: 1 - taskset: 1 - Tekton: 1 - Telemetry: 1 - TensorFlow: 3 -- Terraform: 11 +- Terraform: 12 - Testcontainers: 1 - ThirdAI: 1 - TimescaleDB: 1 - Tinkerblox: 1 - topdown-tool: 1 +- Topo: 2 - Trivy: 1 - Trusted Firmware: 1 - Trustee: 2 @@ -263,10 +313,12 @@ tools_software_languages_filter: - TuxMake: 1 - tuxmake: 1 - TypeScript: 2 +- Ubuntu: 1 - Vectorscan: 1 +- Velox: 1 - Veraison: 3 -- Visual Studio Code: 5 -- vLLM: 3 +- Visual Studio Code: 6 +- vLLM: 4 - VS Code: 1 - vvenc: 1 - Web Server: 1 @@ -275,15 +327,16 @@ tools_software_languages_filter: - WordPress: 3 - wrk2: 2 - x265: 1 -- YAML: 1 +- XGBoost: 1 +- YAML: 2 - YCSB: 1 - Yocto/BitBake: 1 - zlib: 1 - ZooKeeper: 1 weight: 1 cloud_service_providers_filter: -- AWS: 89 -- Google Cloud: 104 -- Microsoft Azure: 87 +- AWS: 95 +- Google Cloud: 116 +- Microsoft Azure: 101 - Oracle: 61 --- diff --git a/content/learning-paths/servers-and-cloud-computing/aws-cdk/_index.md b/content/learning-paths/servers-and-cloud-computing/aws-cdk/_index.md new file mode 100644 index 0000000000..71bba85179 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/aws-cdk/_index.md @@ -0,0 +1,60 @@ +--- +title: Deploy containers on Arm-based compute using Amazon ECS and the AWS CDK +description: Learn how to define and deploy a containerized application on Arm-based compute using the AWS Cloud Development Kit. + +minutes_to_complete: 45 + +who_is_this_for: This is an introductory topic for software developers who want to use the AWS Cloud Development Kit (AWS CDK) to deploy containerized applications on Arm-based AWS infrastructure. + +learning_objectives: + - Create an example AWS CDK application in JavaScript + - Define AWS infrastructure using the AWS CDK + - Deploy application resources on Arm-based AWS compute using Amazon ECS and the AWS CDK + +prerequisites: + - An Amazon Web Services (AWS) account + - A local computer with the AWS CLI, AWS CDK CLI, and Node.js installed, with AWS credentials configured. + - Familiarity with the Linux command line and JavaScript + +author: Anupras Mohapatra + +### Tags +skilllevels: Introductory +subjects: Containers and Virtualization +cloud_service_providers: + - AWS +armips: + - Neoverse +operatingsystems: + - Linux +tools_software_languages: + - AWS CDK CLI + - Amazon Elastic Container Service (Amazon ECS) + - AWS CLI + - Node.js + - JavaScript + +further_reading: + - resource: + title: AWS CDK Developer Guide + link: https://docs.aws.amazon.com/cdk/v2/guide/home.html + type: documentation + - resource: + title: AWS CDK CLI install guide + link: /install-guides/aws-cdk/ + type: install-guide + - resource: + title: AWS CLI install guide + link: /install-guides/aws-cli/ + type: install-guide + - resource: + title: Amazon ECS task definitions for 64-bit Arm workloads + link: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-arm64.html + type: documentation + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +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/aws-cdk/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/aws-cdk/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/aws-cdk/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/aws-cdk/app.md b/content/learning-paths/servers-and-cloud-computing/aws-cdk/app.md new file mode 100644 index 0000000000..0e3c93691f --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/aws-cdk/app.md @@ -0,0 +1,117 @@ +--- +title: "Create a sample AWS CDK application" +description: Create a JavaScript AWS CDK application that defines an Amazon ECS service running on Arm-based AWS Fargate compute. +weight: 2 + +layout: "learningpathall" +--- + +## Set up a sample AWS CDK application + +The AWS Cloud Development Kit (AWS CDK) is an open-source infrastructure as code (IaC) software development framework. + +In this section, you'll create a JavaScript CDK application that defines an Amazon Elastic Container Service (ECS) service running on Arm-based AWS Fargate compute. + +Arm-based AWS compute is powered by AWS Graviton processors. For more information about AWS Graviton, see [Level up your compute with AWS Graviton](https://aws.amazon.com/ec2/graviton/level-up-with-graviton/). + +### Before you begin + +Make sure that you've installed the AWS CDK CLI: + +```bash +cdk --version +``` + +The output is similar to: + +```output +2.1125.0 (build 71fd29e) +``` + +For instructions to set up and install the AWS CDK CLI, see the [AWS CDK install guide](/install-guides/aws-cdk). + +Make sure you've installed Node.js: + +```bash +node --version +``` + +The output is similar to: +```output +v26.2.0 +``` + +### Initialize a CDK project + +Create a directory for your CDK project and navigate to it: + +```bash +mkdir arm-cdk-app +cd arm-cdk-app/ +``` + +After navigating into the project directory, initialize a JavaScript CDK project: + +```bash +cdk init --language javascript +``` + +The output is similar to: + +```output +Applying project template app for javascript +# Welcome to your CDK JavaScript project + +This is a blank project for CDK development with JavaScript. + +The `cdk.json` file tells the CDK Toolkit how to execute your app. The build step is not required when using JavaScript. + +## Useful commands + +* `npm run test` perform the jest unit tests +* `npx cdk deploy` deploy this stack to your default AWS account/region +* `npx cdk diff` compare deployed stack with current state +* `npx cdk synth` emits the synthesized CloudFormation template + +... +``` + +### Use the AWS CDK with JavaScript to define a sample application + +In the project, you'll find a file called `arm-cdk-app-stack.js` in the `lib` directory. AWS CDK uses this stack definition to deploy all necessary AWS resources. + +Update `lib/arm-cdk-app-stack.js` to define a load-balanced Amazon ECS service that runs an NGINX web server on an Arm-based AWS Fargate runtime platform. + +Replace the contents of the file with the following code: + +```javascript +const cdk = require('aws-cdk-lib'); +const ecs = require('aws-cdk-lib/aws-ecs'); +const ecsPatterns = require('aws-cdk-lib/aws-ecs-patterns'); + +class ArmCdkAppStack extends cdk.Stack { + constructor(scope, id, props) { + super(scope, id, props); + + new ecsPatterns.ApplicationLoadBalancedFargateService(this, 'Service', { + taskImageOptions: { + image: ecs.ContainerImage.fromRegistry("nginx:latest"), + containerPort: 80, + }, + runtimePlatform: { + cpuArchitecture: ecs.CpuArchitecture.ARM64, + operatingSystemFamily: ecs.OperatingSystemFamily.LINUX, + }, + publicLoadBalancer: true, + }); + } +} + +module.exports = { ArmCdkAppStack }; +``` + +## What you've accomplished and what's next + +You've now set up a sample JavaScript application using AWS CDK and defined an Amazon ECS service that runs on Arm-based AWS Fargate compute. + +Next, you'll use AWS CDK to synthesize and deploy the application. diff --git a/content/learning-paths/servers-and-cloud-computing/aws-cdk/cdk.md b/content/learning-paths/servers-and-cloud-computing/aws-cdk/cdk.md new file mode 100644 index 0000000000..1fecf39844 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/aws-cdk/cdk.md @@ -0,0 +1,90 @@ +--- +title: "Synthesize and deploy the sample AWS CDK application" +description: Synthesize, deploy, verify, and clean up a sample AWS CDK application running on Arm-based AWS Fargate compute. +weight: 3 + +layout: "learningpathall" +--- + +## Synthesize the AWS CDK application + +Before you can deploy an application using the AWS CDK, you need to synthesize it. During synthesis, the AWS CDK checks for errors in the application code and then translates the code into an AWS CloudFormation template. + +Within the project directory, synthesize the application: + +```bash +cdk synth +``` +You can find the generated JSON template at `cdk.out/ArmCdkAppStack.template.json`. + +## Bootstrap the AWS CDK application environment + +After synthesizing your application, you need to bootstrap the environment. In this step, the AWS CDK creates resources such as AWS Identity and Access Management (IAM) roles. + +Within the project directory, bootstrap the environment: + +```bash +cdk bootstrap +``` + +## Deploy the AWS CDK application + +After bootstrapping the environment, you're ready to deploy the application. AWS CDK deploys the application using the AWS CloudFormation stack generated during synthesis and IAM roles created during bootstrap. + +Deploy the application: + +```bash +cdk deploy +``` +By default, the AWS CDK CLI will prompt you to approve IAM-related changes during deployment. + +If you want the AWS CDK CLI to deploy the application without the need for approval, set the `--require-approval` flag to `never` during deployment: + +```bash +cdk deploy --require-approval never +``` + +{{% notice Note %}} +The deployment can take a few minutes to complete. +{{% /notice %}} + +When the deployment completes, the final lines of the output will include a URL to the web server and the load balancer's DNS name: + +```output +Outputs: +ArmCdkAppStack.MyWebServerLoadBalancerDNSXXXXXXX = Hello-MyWeb-ZZZZZZZZZZZZZ-ZZZZZZZZZZ.us-east-1.elb.amazonaws.com +ArmCdkAppStack.MyWebServerServiceURLYYYYYYYY = http://Hello-MyWeb-ZZZZZZZZZZZZZ-ZZZZZZZZZZ.us-east-1.elb.amazonaws.com +``` + +## Verify application deployment + +Open the service URL (`ArmCdkAppStack.MyWebServerServiceURL...`) from the deployment output in a web browser of your choice. + +You'll see the following welcome message: + +![Screenshot of the application showing the NGINX welcome page and confirming the web server was deployed on Arm-based compute successfully.#center](nginx-output.png "NGINX welcome page indicating successful deployment") + +## Clean up AWS resources + +After you've validated the deployment, clean up the AWS resources that you created with AWS CDK to avoid incurring costs: + +```bash +cdk destroy +``` +By default, the AWS CDK CLI will prompt you to approve the deletion of `ArmCDKAppStack`. + +If you want the AWS CDK CLI to clean up resources without the need for approval, use the `--force` or `-f` flag: + +```bash +cdk destroy -f +``` + +{{% notice Note %}} +The cleanup process can take a couple minutes to complete. +{{% /notice %}} + +## What you've accomplished + +You've now synthesized and deployed a sample containerized application on Arm-based compute using Amazon ECS and the AWS CDK. After verifying that the deployment was successful, you cleaned up resources. + +You can use this workflow to programmatically deploy and manage containerized applications on Arm-based compute powered by AWS Graviton processors. diff --git a/content/learning-paths/servers-and-cloud-computing/aws-cdk/nginx-output.png b/content/learning-paths/servers-and-cloud-computing/aws-cdk/nginx-output.png new file mode 100644 index 0000000000..f3f2f158f6 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/aws-cdk/nginx-output.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_index.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_index.md new file mode 100644 index 0000000000..b8d079fc36 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_index.md @@ -0,0 +1,67 @@ +--- +title: Deploy Gerrit on Google Cloud C4A + +draft: true +cascade: + draft: true + +description: Learn how to install and configure Gerrit on Google Cloud Axion C4A Arm64 instances and benchmark its performance +minutes_to_complete: 30 + +who_is_this_for: This is an introductory topic for developers deploying Gerrit in Arm Linux environments, specifically using Google Cloud C4A virtual machines (VM) powered by Axion processors. + +learning_objectives: + - Provision an Arm-based Ubuntu 24.04 LTS virtual machine on Google Cloud (C4A with Axion processors) + - Install Gerrit Server on the Ubuntu arm64 (C4A) instance + - Verify Gerrit deployment by accessing the web console + - Benchmark Gerrit by measuring operations per second (ops/sec), memory utilization, and disk performance on the Arm platform + +prerequisites: + - A [Google Cloud Platform (GCP)](https://cloud.google.com/free) account with billing enabled + - Basic familiarity with [Gerrit](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html) + +author: Doug Anson + +##### Tags +skilllevels: Introductory +subjects: CI-CD +cloud_service_providers: + - Google Cloud + +armips: + - Neoverse + +tools_software_languages: + - Gerrit + +operatingsystems: + - Linux + +# ================================================================================ +# FIXED, DO NOT MODIFY +# ================================================================================ +further_reading: + - resource: + title: Google Cloud documentation + link: https://cloud.google.com/docs + type: documentation + + - resource: + title: Gerrit documentation + link: https://gerrit-review.googlesource.com/Documentation/ + type: documentation + + - resource: + title: Getting started with Google Cloud Platform + link: /learning-paths/servers-and-cloud-computing/csp/google/ + type: website + + - resource: + title: Gerrit 3.14 release notes + link: https://www.gerritcodereview.com/3.14.html + type: documentation + +weight: 1 +layout: "learningpathall" +learning_path_main_page: "yes" +--- diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_next-steps.md new file mode 100644 index 0000000000..c3db0de5a2 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # Set to always be larger than the content in this path to be at the end of the navigation. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/background.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/background.md new file mode 100644 index 0000000000..987bbb428c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/background.md @@ -0,0 +1,23 @@ +--- +title: About Gerrit and Google Axion C4A + +weight: 2 + +layout: "learningpathall" +--- + +## Google Axion C4A Arm instances in Google Cloud + +Google Axion C4A is a family of Arm-based virtual machines built on Google’s custom Axion CPU, which is based on Arm Neoverse-V2 cores. Designed for high-performance and energy-efficient computing, these virtual machines offer strong performance for modern cloud workloads such as CI/CD pipelines, microservices, media processing, and general-purpose applications. + +The C4A series provides a cost-effective alternative to x86 virtual machines while leveraging the scalability and performance benefits of the Arm architecture in Google Cloud. + +To learn more about Google Axion, refer to the [Introducing Google Axion Processors, our new Arm-based CPUs](https://cloud.google.com/blog/products/compute/introducing-googles-new-arm-based-cpu) blog. + +## Gerrit + +Gerrit is an open-source, web-based code review system for Git repositories that lets teams review proposed commits before they are merged into a codebase. It is especially useful for projects that want patchset-based reviews, inline comments, approval labels, fine-grained permissions, and integration with CI/CD systems before changes land. + +To learn more, start with the official Gerrit site and documentation, especially the product overview and user guide, which explain how Gerrit fits into a development workflow and how to review, upload, and manage changes. + +There is also a [Basic Gerrit Walkthrough — For GitHub Users](https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough-github.html) which explains the core principles of code review in Gerrit compared to pull requests. diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/benchmarking.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/benchmarking.md new file mode 100644 index 0000000000..56e9619a36 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/benchmarking.md @@ -0,0 +1,155 @@ +--- +title: Benchmark Gerrit +weight: 6 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Overview + +This section guides you through benchmarking basic Gerrit performance on your Axion VM. The benchmark consists of a custom script that will exercise and time key Gerrit features/functions. + +## Download and Install the benchmarking script + +Clone the following repo into your VM: + +```bash +cd $HOME +git clone https://github.com/DougAnsonAustinTx/gerrit_test +``` + +## Run Benchmark + +Run the benchmark: + +```bash +cd $HOME/gerrit_test +chmod 755 *.sh +sudo SYNTH_PROFILE=production_like REQUIRE_GERRIT_METRICS=true ./gerrit_perf_test.sh +``` + +The benchmark script will run through some sample exercises that Gerrit supports and will capture performance data from those exercises and place them into a specified JSON file similar to this (partial omitted for brevity): + +```json +{ + "run": { + "run_id": "20260622T152549Z", + "timestamp_utc": "2026-06-22T15:35:19Z", + "host": "douans01-gerrit-arm-6.c.arm-deveco-stedvsl-prd.internal", + "os": "Debian GNU/Linux 13 (trixie)" + }, + "software": { + "java_version": "openjdk version \"21.0.11\" 2026-04-21 OpenJDK Runtime Environment (build 21.0.11+10-1-deb13u2-Debian) OpenJDK 64-Bit Server VM (build 21.0.11+10-1-deb13u2-Debian, mixed mode, sharing) ", + "gerrit_version": "gerrit version 3.11.2", + "gerrit_base_url": "http://127.0.0.1:8080", + "gerrit_test_http_user": "admin", + "prometheus_url": "http://127.0.0.1:9090", + "gerrit_metrics_url": "http://127.0.0.1:8080/plugins/metrics-reporter-prometheus/metrics", + "gerrit_metrics_probe_status": "ok", + "gerrit_metrics_auth_mode": "bearer" + }, + "workload": { + "test_duration_seconds_per_step": 120, + "concurrency_steps": "2,1,1 4,2,1 6,3,2 8,4,2", + "legacy_single_step_defaults": { + "rest_concurrency": 6, + "git_clone_concurrency": 3, + "git_push_concurrency": 2 + }, + "synthetic_profile": "production_like", + "synthetic_projects": 8, + "synthetic_initial_files_per_project": 300, + "synthetic_initial_commits_per_project": 50, + "synthetic_review_changes_per_project": 40, + "synthetic_large_files_per_project": 8, + "synthetic_large_file_kb": 1024 + }, + "startup_state": { + "initial_gerrit_was_running": "true" + }, + "operation_summary": [ + { + "type": "git_clone", + "count": 4301, + "ok_count": 4301, + "fail_count": 0, + "min_ms": 105, + "avg_ms": 244.42269239711695, + "p50_ms": 220, + "p90_ms": 418, + "p95_ms": 456, + "p99_ms": 521, + "max_ms": 611 + }, + { + "type": "git_push_refs_for", + "count": 570, + "ok_count": 570, + "fail_count": 0, + "min_ms": 75, + "avg_ms": 157.13333333333333, + "p50_ms": 155, + "p90_ms": 222, + "p95_ms": 239, + "p99_ms": 288, + "max_ms": 344 + }, + { + "type": "rest_change_query", + "count": 42992, + "ok_count": 42992, + "fail_count": 0, + "min_ms": 12, + "avg_ms": 31.553265723855603, + "p50_ms": 30, + "p90_ms": 50, + "p95_ms": 56, + "p99_ms": 69, + "max_ms": 105 + } + ] + // rest of file omitted for brevity... +} +``` + +This JSON file can be processed to create a summary of the performance of Gerrit on our Axion C4A VM. + +## Performance summary + +The benchmark run completed successfully on the production-like profile with Gerrit metrics enabled. It +recorded 47,863 measured client operations over four 120-second steps, with 47,863 successes and zero failures. +The benchmark gives a high-quality performance view: client latency, stepwise concurrency behavior, node +CPU/memory/disk, and Gerrit-side JVM, GC, Jetty, cache, queue, Git, REST, NoteDB, and receive-commits metrics +are all present: + +![Charts and graphs showing the Gerrit benchmark performance summary including operation counts, success rates, and latency metrics across the four 120-second test steps.#center](images/analysis.png "Gerrit Benchmark Summary") + +Client-visible correctness is excellent: all 47,863 measured operations succeeded. REST query latency remains low +with a p99 of 69 ms. Clone is the dominant pressure point at a p99 of 521 ms, and push remains sub-second at a p99 of 288 ms: + +![Performance metrics showing client-side operation summary with statistics for git_clone, git_push_refs_for, and rest_change_query operations, including latency percentiles and success rates.#center](images/client-summary.png "Client-side Operation Summary") + +The useful capacity signal is the flattening throughput curve after step 2. CPU is already near saturation in step 2, then +stays around 99% in steps 3 and 4. Latency continues rising: clone p99 increases from 221 ms in step 2 to 550 ms in +step 4, while aggregate throughput only rises from 103.3 to 108.4 ops/sec: + +![Graph showing throughput and latency trends across four concurrency steps, demonstrating how performance degrades as concurrency increases and CPU approaches saturation.#center](images/stepwise-summary.png "Stepwise Concurrency Behavior Summary") + +Host CPU pressure: + +![Chart displaying CPU usage metrics across the benchmark steps, showing how CPU pressure increases and stabilizes near saturation levels as concurrency increases.#center](images/cpu-pressure.png "CPU Pressure Summary") + +Gerrit server-side correlation observations: + +![Graph showing correlations between various Gerrit server-side metrics such as GC pressure, cache performance, and queue depths in relation to client request latency.#center](images/gerrit-correlation.png "Gerrit Server-side Correlation Findings") + +Basic Server Metrics: + +![Server metrics dashboard showing host resource utilization metrics including memory, disk I/O, and other system-level performance indicators during the benchmark run.#center](images/server-metrics.png "Basic Additional Server Metrics") + +## What you've accomplished + +You have successfully deployed Gerrit on a Google Cloud C4A Axion Arm64 VM running Ubuntu 24.04 LTS, verified the web console, and measured its performance using a production-like benchmark profile. All operations completed with zero failures, and the results establish a practical capacity baseline for a single-node Gerrit deployment on Arm-based infrastructure. + +To build on this foundation, you can explore multi-node Gerrit deployments, tune JVM flags for the Neoverse-V2 core, or compare performance across different C4A instance sizes to find the right balance of cost and throughput for your team's workload. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/firewall_setup.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/firewall_setup.md new file mode 100644 index 0000000000..18038bbc32 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/firewall_setup.md @@ -0,0 +1,52 @@ +--- +title: Create a firewall rule on GCP +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Overview + +This step creates a firewall rule in Google Cloud Console to allow incoming TCP traffic on port 8080, which is required for your Gerrit deployment to be accessible. + +{{% notice Note %}} +If you need help setting up Google Cloud Platform (GCP), see the Learning Path [Getting started with Google Cloud Platform](/learning-paths/servers-and-cloud-computing/csp/google/). +{{% /notice %}} + +## Create a firewall rule in GCP +To expose TCP port 8080 for Gerrit, start by creating a new firewall rule in Google Cloud Console: + +- Open the [Google Cloud Console](https://console.cloud.google.com/). +- In the navigation menu, select **VPC network** > **Firewall**. +- Select **Create firewall rule**. + +You'll use this rule to allow incoming traffic on TCP port 8080, which is required for Gerrit access on your Arm-based VM. + +![Google Cloud Console showing the Create firewall rule page with Name set to allow-tcp-8080, Direction set to Ingress, Action set to Allow, Targets set to Specified target tags with allow-tcp-8080, and Source IPv4 ranges set to 0.0.0.0/0. These settings configure the firewall to allow incoming TCP traffic on port 8080 from any IPv4 address.#center](images/firewall-rule.png "Create a firewall rule") + +- Set **Name** to `allow-tcp-8080`. +- Select the network you want to use for your VM. The default is `autoscaling-net`, but your organization might use a different network. +- Set **Direction of traffic** to **Ingress**. +- Set **Action on match** to **Allow**. +- For **Targets**, select **Specified target tags** and enter `allow-tcp-8080` in the **Target tags** field. +- In **Source IPv4 ranges**, enter `0.0.0.0/0`. + +This configuration allows incoming TCP traffic on port 8080 from any IPv4 address. + +![Google Cloud Console showing the firewall rule configuration form with allow-tcp-8080 in the Name field, Ingress direction, Allow action, Specified target tags field with allow-tcp-8080, and Source IPv4 ranges set to 0.0.0.0/0. This configuration enables TCP port 8080 traffic for Gerrit access.#center](images/network-rule.png "Creating the TCP/8080 firewall rule") + +## Specify protocols and ports + +Next, configure the protocols and ports for your firewall rule: + +- Under **Protocols and ports**, select **Specified protocols and ports**. +- Check the **TCP** box. +- In the **Ports** field, enter `8080`. +- Select **Create** to finish adding the firewall rule. + +This step ensures that only TCP traffic on port 8080 is allowed through the firewall. + +![Google Cloud Console showing the Protocols and ports section with TCP checkbox selected and Ports field containing 8080. This ensures only TCP traffic on port 8080 is allowed through the firewall for Gerrit.#center](images/network-port.png "Specifying the TCP port to expose") + +Your network firewall rule has now been created. You're ready to continue with VM creation. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/analysis.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/analysis.png new file mode 100644 index 0000000000..ce708f0a8f Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/analysis.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/client-summary.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/client-summary.png new file mode 100644 index 0000000000..612698d9e8 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/client-summary.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/cpu-pressure.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/cpu-pressure.png new file mode 100644 index 0000000000..50e9070689 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/cpu-pressure.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/firewall-rule.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/firewall-rule.png new file mode 100644 index 0000000000..cb2d9bf40a Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/firewall-rule.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-pubip-ssh.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-pubip-ssh.png new file mode 100644 index 0000000000..558745de3e Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-pubip-ssh.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-shell.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-shell.png new file mode 100644 index 0000000000..7e2fc3d1b5 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-shell.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-vm.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-vm.png new file mode 100644 index 0000000000..0d1072e20d Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gcp-vm.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-correlation.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-correlation.png new file mode 100644 index 0000000000..4972e46701 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-correlation.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-dashboard.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-dashboard.png new file mode 100644 index 0000000000..5051a17537 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/gerrit-dashboard.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-config.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-config.png new file mode 100644 index 0000000000..83ffb1c36b Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-config.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-port.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-port.png new file mode 100644 index 0000000000..03e276b13a Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-port.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-rule.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-rule.png new file mode 100644 index 0000000000..dbc18f54c5 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/network-rule.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/server-metrics.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/server-metrics.png new file mode 100644 index 0000000000..488002e152 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/server-metrics.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/stepwise-summary.png b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/stepwise-summary.png new file mode 100644 index 0000000000..256733951b Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/images/stepwise-summary.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/installation.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/installation.md new file mode 100644 index 0000000000..44bd30850d --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/installation.md @@ -0,0 +1,78 @@ +--- +title: Install Gerrit +weight: 5 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Install Gerrit on GCP VM + +This section walks you through how to install and configure Gerrit Server on a GCP Linux VM (Ubuntu 24.04 LTS based VM). + +To ensure a successful setup, follow each step in order and check the output after each command. This helps you catch issues early and confirms that Gerrit is installed and running correctly. + +## Set up your environment + +Before installing Gerrit, update the system and install the required tools: + +```console +sudo apt update && sudo apt upgrade -y +sudo apt install -y wget default-jdk git net-tools +``` + +## Download and Setup/Install Gerrit server + +Download the Gerrit server package for ARM64 architecture. + +```console +mkdir -p ${HOME}/gerrit +wget -O gerrit.war https://gerrit-releases.storage.googleapis.com/gerrit-3.14.0.war +java -jar gerrit.war init -d ${HOME}/gerrit --dev --batch --install-all-plugins +``` + +## Verify service status: + +```console +ps -ef | grep Gerrit +``` + +You should see similar output: + +```output +doug_an+ 11807 1 18 21:01 ? 00:00:14 GerritCodeReview -Dflogger.backend_factory=com.google.common.flogger.backend.log4j.Log4jBackendFactory#getInstance -Dflogger.logging_context=com.google.gerrit.server.logging.LoggingContext#getInstance -jar /home/doug_anson_arm_com/gerrit/bin/gerrit.war daemon -d /home/doug_anson_arm_com/gerrit --run-id=1781730091.11737 +``` + +## Check required ports + +To confirm Gerrit is ready to accept connections, check that the required ports are open and listening. If you see "LISTEN" next to these ports, Gerrit is running and network services are available. + +Gerrit uses port 8080 for its web console function. + +Run the following command to verify the ports are active: + +```console +netstat -a | grep http | grep LISTEN +``` + +The output is similar to: + +```output +tcp6 0 0 [::]:http-alt [::]:* LISTEN +``` + +If you see "LISTEN" for the "http-alt" port, Gerrit is ready for baseline testing and further configuration. This confirms that the core Gerrit services are running and accessible on your Arm-based GCP VM. + +## Confirm that the Gerrit dashboard is accessible + +Using a browser and the "Public IP Address" saved off when the VM instance was created, go to the following URL in the browser: + +```output +http://my_vm_public_ip_address:8080 +``` + +You should see output similar to this: + +![Gerrit web console dashboard showing the main interface with navigation menu and project/change options available.#center](images/gerrit-dashboard.png "Gerrit Dashboard") + +In the next section, you will benchmark Gerrit performance on your Arm VM. diff --git a/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/instance.md b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/instance.md new file mode 100644 index 0000000000..79d61edef8 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/gerrit-on-gcp/instance.md @@ -0,0 +1,49 @@ +--- +title: Create a Google Axion C4A Arm virtual machine on GCP +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Overview + +Provision a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP) using the `c4a-standard-4` machine type (4 vCPUs, 16 GB memory) in the Google Cloud Console. + +{{% notice Note %}} +For support on GCP setup, see the Learning Path [Getting started with Google Cloud Platform](/learning-paths/servers-and-cloud-computing/csp/google/). +{{% /notice %}} + +## Provision a Google Axion C4A Arm VM in Google Cloud Console + +To create a virtual machine based on the C4A instance type: +- Navigate to the [Google Cloud Console](https://console.cloud.google.com/). +- Go to **Compute Engine > VM Instances** and select **Create Instance**. +- Under **Machine configuration**: + - Populate fields such as **Instance name**, **Region**, and **Zone**. + - Set **Series** to `C4A`. + - Select `c4a-standard-4` for machine type. + +![Google Cloud Console interface showing the Create Instance page with Machine configuration section. Series is set to C4A and machine type shows c4a-standard-4 selected. The dialog displays configuration options for CPU, memory, and other VM settings.#center](images/gcp-vm.png "Creating a Google Axion C4A Arm virtual machine in Google Cloud Console") + + +- Under **OS and Storage**, select **Change**. Choose an Arm64-based OS image. For this Learning Path, select **Ubuntu 24.04 LTS**. +- Change the size of the primary disk from 10 GB to 100 GB +- Click **Select** to confirm your OS choice. +- Under **Networking**, enable **Allow HTTP traffic** and **Allow HTTPS traffic**. +- In the **Network tags** field, add `allow-tcp-8080` to allow Gerrit dashboard traffic. + +![Google Cloud Console interface showing the Networking tab for VM instance configuration. The Network tags field displays allow-tcp-8080 to enable firewall rule for Gerrit dashboard traffic on port 8080. Other networking options and VM configuration controls are visible.#center](images/network-config.png "Adding the TCP/8080 firewall rule to our VM") + +- Select **Create** to launch your VM instance. +- After the VM is ready, you'll see an **SSH** button next to your instance in the VM list. The public IP address for your VM also appears here. +- Copy the public IP address—you'll need it later to connect to Gerrit. +- Select **SSH** to open a shell session directly in your browser. + +![Google Cloud Console showing the VM Instances list with a running VM instance. The SSH button is highlighted next to the instance entry, with the public IP address visible in the same row. This shows how to access the SSH terminal to connect to your Arm-based VM.#center](images/gcp-pubip-ssh.png "Invoke a SSH session into your running VM instance") + +A window from your browser should come up and you should now see a shell into your VM instance: + +![Browser-based terminal window showing an active shell session on the Ubuntu VM instance. The command prompt is ready for input. This demonstrates successful connection to your C4A Arm virtual machine on Google Cloud.#center](images/gcp-shell.png "Terminal shell in your VM instance") + +You are now ready to install Gerrit. diff --git a/content/learning-paths/servers-and-cloud-computing/mysql_tune/_index.md b/content/learning-paths/servers-and-cloud-computing/mysql_tune/_index.md index 48039b70c6..6baf52b3ab 100644 --- a/content/learning-paths/servers-and-cloud-computing/mysql_tune/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/mysql_tune/_index.md @@ -1,19 +1,71 @@ --- -title: Learn how to Tune MySQL +title: Tune MySQL performance on Arm-based platforms +description: Learn how to tune MySQL configuration, Linux memory settings, and storage options to improve database performance on Arm-based platforms. minutes_to_complete: 30 -who_is_this_for: This is an advanced topic for software developers and DevOps professionals interested in optimizing MySQL performance on Arm-based VMs in the cloud. +who_is_this_for: This Learning Path is for database administrators (DBAs) and software developers who want to optimize MySQL performance on Arm-based platforms. learning_objectives: - - Tune MySQL to increase performance + - Configure MySQL settings that affect connection handling, memory usage, disk flush behavior, and concurrency. + - Enable huge pages for MySQL and size them based on the InnoDB buffer pool. + - Evaluate storage, kernel, compiler, and library choices that can affect MySQL performance. prerequisites: - - Bare-metal or cloud [installation of MySQL](/learning-paths/servers-and-cloud-computing/mysql/) + - On-prem or cloud [installation of MySQL](https://dev.mysql.com/doc/refman/en/) + - A repeatable MySQL workload or benchmark that you can run before and after tuning + +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-26T21:28:59Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 19acf30951401ec15201ee8e387eb59f9248f627664bc693cf05928233bf2b6f + summary_generated_at: '2026-06-26T21:28:59Z' + summary_source_hash: 19acf30951401ec15201ee8e387eb59f9248f627664bc693cf05928233bf2b6f + faq_generated_at: '2026-06-26T21:28:59Z' + faq_source_hash: 19acf30951401ec15201ee8e387eb59f9248f627664bc693cf05928233bf2b6f + summary: >- + You'll learn how to use a measurement-driven approach to tune MySQL performance on Arm-based platforms. + You'll explore system factors — storage technology and file systems, + disk scheduling, kernel memory management, compiler, and library versions — that you can adjust. In addition, you'll learn about optimizable MySQL parameters related to connection + handling, memory usage, disk flush behavior, and concurrency, and learn how to enable and + size huge pages based on the InnoDB buffer pool. By the end, you'll know what parameters to update for running controlled experiments, + and be able to make persistent configuration choices aligned with your workload. + faqs: + - question: How do I know a MySQL tuning change actually helped? + answer: >- + Run the same repeatable workload before and after the change and compare throughput, latency, + and profiles. Change one parameter at a time or use a designed experiment so results are + attributable to specific settings. + - question: Should I set MySQL parameters in an option file or on the `mysqld` command line? + answer: >- + Use an option file for persistent tuning so changes are reviewable, version controlled, + and applied on restart. The examples in the Learning Path target the `[mysqld]` group. Command-line flags are suitable + for temporary tests. + - question: Which storage option should I use when testing performance? + answer: >- + In general, locally attached SSD storage performs best, but network-based storage can also + perform well. Test the storage technologies and file systems you have, and review disk scheduling + behavior with your workload. + - question: When should I look at kernel, compiler, or library choices instead of MySQL settings? + answer: >- + Evaluate them before or alongside MySQL tuning because operating system settings, kernel + memory management, compiler choices, and library versions can affect throughput and latency. + Treat them as part of the same performance experiment set. + - question: How should I size huge pages for MySQL? + answer: >- + Enable huge pages for MySQL and size them based on the InnoDB buffer pool. This aligns page + allocation with the primary memory consumer in typical MySQL deployments. +# END generated_summary_faq author: Julio Suarez -generate_summary_faq: true +generate_summary_faq: false rerun_summary: false rerun_faqs: false @@ -41,13 +93,25 @@ test_maintenance: true further_reading: - resource: - title: MySQL documentation - link: https://www.mysql.com/ + title: MySQL Reference Manual + link: https://dev.mysql.com/doc/refman/en/ + type: documentation + - resource: + title: InnoDB configuration parameters + link: https://dev.mysql.com/doc/refman/en/innodb-parameters.html type: documentation - resource: - title: Running MySQL on ARM - link: https://mysqlonarm.github.io/Running-MySQL-on-ARM/ + title: Optimizing InnoDB disk I/O + link: https://dev.mysql.com/doc/refman/en/optimizing-innodb-diskio.html type: documentation + - resource: + title: Linux HugeTLBpage documentation + link: https://docs.kernel.org/admin-guide/mm/hugetlbpage.html + type: documentation + - resource: + title: Migrating applications to Arm servers + link: /learning-paths/servers-and-cloud-computing/migration/ + type: learning-path ### FIXED, DO NOT MODIFY # ================================================================================ @@ -55,4 +119,3 @@ weight: 1 layout: learningpathall learning_path_main_page: 'yes' --- - diff --git a/content/learning-paths/servers-and-cloud-computing/mysql_tune/before_and_after.md b/content/learning-paths/servers-and-cloud-computing/mysql_tune/before_and_after.md index b5fd336d99..4d1863c904 100644 --- a/content/learning-paths/servers-and-cloud-computing/mysql_tune/before_and_after.md +++ b/content/learning-paths/servers-and-cloud-computing/mysql_tune/before_and_after.md @@ -1,17 +1,38 @@ --- -title: "About MySQL performance tuning" +title: Measure the impact of tuning MySQL +description: Learn how to approach MySQL performance tuning as a measurement-driven process and compare baseline results with tuned results. weight: 2 layout: "learningpathall" --- -## About database performance tuning +## About performance tuning -The configuration of a database and the types of requests made by clients to it will differ from use case to use case. This means there is no one size fits all set of tuning parameters for `MySQL`. Use the information in this learning path as general guidance to help with tuning `MySQL`. +Performance tuning is most useful when you treat it as a measurement process, not a fixed checklist. You can tune by changing one parameter at a time, running a designed experiment, comparing profiles, or using automation and AI-assisted tools to explore a larger configuration space. -## Importance of tuning +There isn't a universal set of tuning parameters that works best for every application. The right settings depend on the workload, data size, memory capacity, storage performance, network behavior, software version, system architecture, operating system, and other application-specific factors. -Application tuning allows you to gain performance without scaling a deployment up (bigger machines) or out (more machines). This gives the option to use the gained performance, or to trade it for cost savings by reducing the total compute resources provisioned. +Whatever method you use, keep the measurements repeatable. Record the system configuration, workload, software versions, and tuning parameters so you can identify which changes improved performance and which changes had little effect. -## Note on MySQL Documentation +## Why tune MySQL -All links to [MySQL documentation](https://dev.mysql.com/doc/refman/en/) in this learning path point to the latest version of the documentation. If you are using an older version of MySQL, be sure to change the documentation version after clicking the links. \ No newline at end of file +MySQL performance can be limited by memory usage, disk I/O, connection handling, concurrency, or synchronization overhead. By tuning MySQL, you can use the available compute, memory, and storage resources more efficiently. + +Improved performance can give you higher throughput, lower latency, or better cost efficiency. A tuned configuration can increase capacity on the same system, or help you meet the same performance target with fewer compute resources. + +## Example benchmark result + +The following example shows MySQL throughput with HammerDB TPROC-C before and after tuning on an Arm Neoverse V3 system. + +![Bar chart comparing MySQL HammerDB TPROC-C normalized NOPM throughput before and after tuning on an Arm Neoverse V3 system. At 128 clients, the out-of-box configuration is 1.00 and the tuned configuration is 15.37.#center](oobvstuned.png "MySQL HammerDB TPROC-C throughput before and after tuning") + +This benchmark result is an example, not a guaranteed improvement for every workload. Your results depend on the MySQL version, database size, storage device, memory capacity, client thread count, and the queries used in the test. + +{{% notice Note %}} +Links to MySQL documentation in this Learning Path point to the latest version of the documentation. If you use an older version of MySQL, select the matching documentation version after opening the links. +{{% /notice %}} + +## What you've learned and what's next + +You've now learned why tuning MySQL is beneficial, and reviewed an example benchmark result demonstrating improvement in throughput after tuning. + +Next, you'll learn about different system parameters that you can tune for performance. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib.md b/content/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib.md index 287cf756a3..5a140cf703 100644 --- a/content/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib.md +++ b/content/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib.md @@ -1,6 +1,7 @@ --- # User change -title: "System, Kernel, Compiler, and Libraries" +title: Tune storage, kernel, compiler, and library settings for performance +description: Learn how storage, kernel page size, Linux huge pages, compiler settings, and OpenSSL choices can affect MySQL performance on Arm-based systems. weight: 3 # 1 is first, 2 is second, etc. @@ -8,29 +9,35 @@ weight: 3 # 1 is first, 2 is second, etc. layout: "learningpathall" --- -## Storage technology, file system format, and disk scheduling +## Tune the system around MySQL -The underlying storage technology and the file system format can impact performance. In general, locally attached SSD storage will perform best. However, network based storage systems can perform well. You should spend some time studying and experimenting with different storage technologies and configuration options. +MySQL configuration is only one part of performance tuning. Operating system settings, storage behavior, kernel memory management, compiler choices, and library versions can also affect throughput and latency. The following are system-level areas to check before or alongside MySQL-specific tuning. -Aside from the storage technology, the file system format used with `MySQL` can impact performance. The `xfs` file system is a good starting point. The `ext4` file system is another good alternative. Last, it is recommended to use storage drives that are dedicated to the database (i.e. not shared with the OS or other applications). +### Storage technology, file systems, and disk scheduling -When running in the cloud, the disk scheduling algorithm is typically set to `noop` or a similar "dumb" algorithm. This is typically optimal for `MySQL` in the cloud, so no adjustment is needed. However, if running `MySQL` on an on-prem server, it's a good idea to double check what the disk scheduling algorithm is, and possibly change it. According to the [Optimizing InnoDB Disk I/O documentation](https://dev.mysql.com/doc/refman/en/optimizing-innodb-diskio.html), `noop` or `deadline` might be better options. It's worth testing this with on-prem systems. +Storage technology and file system choices can affect performance. In general, locally attached SSD storage performs best, but network-based storage systems can also perform well. Test the storage technologies and configuration options available in your environment. -## MySQL storage engines +The file system used with MySQL can also affect performance. The `xfs` file system is a good starting point, and `ext4` is another good option. For production systems, use storage volumes dedicated to the database instead of sharing them with the operating system or other applications. -There are different storage engines available for `MySQL`. The default storage engine is `InnoDB`. `InnoDB` is the default storage engine because it performs the best in the broadest set of use cases. +When running in the cloud, the disk scheduling algorithm is typically set to `noop` or a similar minimal scheduler. This is usually a good setting for MySQL in cloud environments, so no adjustment is needed. -Information on alternative storage engines can be found in the [MySQL documentation](https://dev.mysql.com/doc/refman/en/storage-engines.html). +If you run MySQL on an on-premises server, double-check the disk scheduling algorithm and test alternatives. According to the [Optimizing InnoDB Disk I/O documentation](https://dev.mysql.com/doc/refman/en/optimizing-innodb-diskio.html), `noop` or `deadline` might be better options for some systems. -## Kernel configuration +### MySQL storage engines -`MySQL` can benefit from adjustments to kernel parameters. Below is a list of kernel related settings that can have a positive impact on performance. +MySQL supports different storage engines. The default storage engine is `InnoDB`, which performs best across the broadest set of use cases. -### Linux virtual memory subsystem +For more information on alternative storage engines, see the [MySQL storage engine documentation](https://dev.mysql.com/doc/refman/en/storage-engines.html). -Making changes to the Linux Virtual Memory subsystem can improve performance. +### Kernel configuration -These settings can be changed in the `/etc/sysctl.conf` file, or by using the `sysctl` command. +MySQL can benefit from adjustments to kernel parameters. The following kernel-related settings can improve performance. + +#### Linux virtual memory subsystem + +Making changes to the Linux virtual memory subsystem can improve performance. + +You can change these settings by using the `sysctl` command or by adding configuration files under `/etc/sysctl.d/`. Documentation on the virtual memory subsystem parameters can be found in the [admin-guide for sysctl in the Linux source code](https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/sysctl/vm.rst). @@ -40,16 +47,37 @@ To list all sysctl parameters available: sudo sysctl -a ``` -See the `sysctl` command documentation for more. +For more information, see the `sysctl` command documentation. + +#### Consider 64 KB kernel pages on Arm + +Some Arm Linux distributions provide kernels built with `64 KB` base pages instead of `4 KB` base pages. This is a kernel selection or build-time choice, not a `sysctl` setting you can change on a running system. + +A `64 KB` base page can improve some memory-intensive workloads because each base page maps more memory. This can reduce Memory Management Unit (MMU) translation overhead, reduce page-table walk depth, and relieve Translation Lookaside Buffer (TLB) pressure, including instruction-side TLB pressure in the CPU front end. + +The tradeoff is memory efficiency. Larger base pages can increase internal fragmentation for workloads with many small or sparsely touched mappings, which can reduce the effective amount of memory available to the application and operating system. + +The benefit is workload dependent, so compare a `4 KB` kernel and a `64 KB` kernel with the same MySQL and storage configuration. + +Base page size also affects the huge page sizes available on Arm. The common PMD-level huge page sizes are: + +| Kernel base page size | PMD-level huge page size | +|-----------------------|--------------------------| +| `4 KB` | `2 MiB` | +| `64 KB` | `512 MiB` | + +For more information, see the Linux kernel documentation for [Memory Layout on AArch64 Linux](https://docs.kernel.org/next/arm64/memory.html) and [HugeTLBpage on ARM64](https://docs.kernel.org/next/arm64/hugetlbpage.html). ### Huge memory pages - `MySQL` benefits from using huge memory pages. Huge pages reduce how often virtual memory pages are mapped to physical memory. - +MySQL can benefit from using huge memory pages, especially when the InnoDB buffer pool is large. Huge memory pages have a similar performance goal to `64 KB` base pages: they map more memory per translation entry, which can reduce page-table walks and TLB pressure. + +The tradeoff is also similar. Huge pages reserve memory in larger chunks, so over-allocating them can reduce the memory available for other uses. Under-allocating them can prevent MySQL from using huge pages at all. The performance impact depends on your workload and system configuration. + To see the current huge memory page configuration, run the following command on the host: ```bash -cat /proc/meminfo | grep ^Huge +grep '^Huge' /proc/meminfo ``` The output should be similar to: @@ -63,44 +91,53 @@ Hugepagesize: 2048 kB Hugetlb: 0 kB ``` -Huge pages are not being used if `HugePages_Total` is 0 (this is typically the default). - -Also note that `Hugepagesize` is 2MiB which is the typical default for huge pages on Linux. +Huge pages are not being used if `HugePages_Total` is `0` (this is typically the default). -The sysctl parameter that enables huge pages is shown below: +The `Hugepagesize` value depends on the kernel base page size and platform configuration. Use the value reported by `/proc/meminfo` when calculating `vm.nr_hugepages`. -```output -vm.nr_hugepages -``` +The sysctl parameter that enables huge pages is `vm.nr_hugepages`. -This parameter sets the number of huge pages you want the kernel to make available to applications. +This parameter sets the number of huge pages you want the kernel to make available to applications. -The total amount of memory that will be used for huge pages will be this number (defaulted to 0) times the `Hugepagesize`. +The total amount of memory used for huge pages is this number, which defaults to 0, multiplied by the `Hugepagesize` value. -As an example, if you want a total of 1GB of huge page space, then you should set `vm.nr_hugepages` to 500 (500x2MB=1GB). +For example, if you want `1 GiB` of huge page space and `Hugepagesize` is `2 MiB`, set `vm.nr_hugepages` to `512`. ```bash -sudo sysctl -w vm.nr_hugepages=500 +sudo sysctl -w vm.nr_hugepages=512 ``` To make the change permanent: ```bash -sudo sh -c 'echo "vm.nr_hugepages=500" >> /etc/sysctl.conf' +echo "vm.nr_hugepages=512" | sudo tee /etc/sysctl.d/99-mysql-hugepages.conf +sudo sysctl --system ``` -### Selecting the number of huge pages to use +#### Selecting the number of huge pages to use -You should set `vm.nr_hugepages` to a value that gives a total huge page space equal to or slightly larger than the `MySQL` buffer pool size. Selecting the buffer pool size is discussed in the [Tuning MySQL](/learning-paths/servers-and-cloud-computing/mysql_tune/tuning/) section. +If huge pages improve your workload, set `vm.nr_hugepages` to a value that gives a total huge page space equal to or slightly larger than the InnoDB buffer pool size, which is controlled by `innodb_buffer_pool_size`. + +{{% notice Important %}} +After restarting MySQL with `large-pages=ON`, check both `/proc/meminfo` and the MySQL error log. If the huge page pool is too small, or MySQL cannot allocate huge pages for another reason, InnoDB can fall back to traditional memory and write `Warning: Using conventional memory pool.` to the MySQL error log. You might also see an allocation warning similar to `large_page_aligned_alloc mmap(... bytes) failed; errno 12`. +{{% /notice %}} + +Selecting the buffer pool size is discussed in the [Tuning MySQL](/learning-paths/servers-and-cloud-computing/mysql_tune/tuning/) section. Typically, only the number of huge pages needs to be configured. However, for more information on the different parameters that affect the configuration of huge pages, review the [admin-guide for hugetlbpage in the Linux source code](https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/mm/hugetlbpage.rst). -## Compiler Considerations +### Compiler considerations + +If you build MySQL from source, the compiler version and optimization flags can affect performance. Use a recent version of GCC, and consider flags such as `-mcpu` and `-flto` for additional optimization. These flags are explained in the [Migrating C/C++ applications](/learning-paths/servers-and-cloud-computing/migration/c/) section of the [Migrating applications to Arm servers](/learning-paths/servers-and-cloud-computing/migration/) Learning Path. + +### OpenSSL considerations + +MySQL relies on [OpenSSL](https://www.openssl.org/) for cryptographic operations. The OpenSSL version used with MySQL, and the compiler version and switches used to build it, can affect performance. The default OpenSSL version provided by your Linux distribution is typically sufficient. -The easiest way to gain performance is to use the latest version of GCC. Aside from that, the flags `-mcpu` and `-flto` can be used to potentially gain additional performance. Usage of these flags is explained in the [Migrating C/C++ applications](/learning-paths/servers-and-cloud-computing/migration/c/) section of the [Migrating applications to Arm servers](/learning-paths/servers-and-cloud-computing/migration/) learning path. +If you build MySQL from source, you can also build and install a newer version of OpenSSL before building MySQL. This might improve performance for workloads that spend significant time in cryptographic operations. -## OpenSSL Considerations +## What you've learned and what's next -MySQL relies on [OpenSSL](https://www.openssl.org/) for cryptographic operations. Thus, the version of OpenSSL used with MySQL (and the GCC version and switches used to compile it) can impact performance. Typically using the Linux distribution default version of OpenSSL is sufficient. +You've now explored changes you can make at the system-level related to storage, memory pages, compiler flags, and OpenSSL to improve MySQL performance on Arm. -However, it is possible to use newer versions of OpenSSL which could yield performance improvements. This is achieved by building and installing OpenSSL before building MySQL. \ No newline at end of file +Next, you'll learn about specific MySQL parameters that you can tune for performance. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/mysql_tune/oobvstuned.png b/content/learning-paths/servers-and-cloud-computing/mysql_tune/oobvstuned.png new file mode 100644 index 0000000000..ffb533528f Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/mysql_tune/oobvstuned.png differ diff --git a/content/learning-paths/servers-and-cloud-computing/mysql_tune/tuning.md b/content/learning-paths/servers-and-cloud-computing/mysql_tune/tuning.md index 93293bf523..53b5517aaf 100644 --- a/content/learning-paths/servers-and-cloud-computing/mysql_tune/tuning.md +++ b/content/learning-paths/servers-and-cloud-computing/mysql_tune/tuning.md @@ -1,6 +1,7 @@ --- # User change -title: "Tuning MySQL" +title: Tune MySQL configuration for performance +description: Learn how to tune MySQL server parameters for connections, memory, disk flushing, transaction durability, I/O capacity, and lock polling. weight: 4 # 1 is first, 2 is second, etc. @@ -8,92 +9,182 @@ weight: 4 # 1 is first, 2 is second, etc. layout: "learningpathall" --- -## MySQL configuration +## Choose MySQL parameters for tuning -There are different ways to set configuration parameters for `MySQL`. +You can set MySQL server configuration parameters in an option file or on the `mysqld` command line. -This is discussed in the [Specifying Program Options](https://dev.mysql.com/doc/refman/en/program-options.html) section of the MySQL documentation. +For persistent tuning, use an option file so the configuration can be reviewed, version controlled, and applied consistently when MySQL restarts. For more information, see the MySQL[Specifying Program Options](https://dev.mysql.com/doc/refman/en/program-options.html) documentation. -The configurations below can be directly pasted into a `MySQL` configuration file under the group `mysqld`. +The examples in this section are intended for the `[mysqld]` group in a MySQL option file. -It's also possible to specify these configurations on the `mysqld` command line. However, it's better to use configuration files since these can be version controlled more easily. +{{% notice Note %}} +In general, leave most MySQL settings at their defaults and change them only when you have a workload requirement, test result, profile, or observed bottleneck that supports the change. +{{% /notice %}} -Last, keep in mind, that in general, it's usually best to leave most configs at default, and only change them if there is a suspected/known issue. +### Connections and prepared statements -### Connections and prepared transactions +The following example shows intentionally high limits that can be useful in benchmark environments where you want to prevent connection or prepared statement limits from affecting the test result: +```ini +# Intentionally high benchmark limits. +max_connections=100000 +max_prepared_stmt_count=4194304 ``` -max_connections=100000 # Default 151 -max_prepared_stmt_count=4194304 # Default 16382 + +The [`max_connections`](https://dev.mysql.com/doc/refman/en/server-system-variables.html#sysvar_max_connections) parameter doesn't directly improve performance. It raises the number of client connections MySQL can accept. Higher values consume more memory and can also depend on operating system limits such as file descriptors, so size this value for your expected peak connection count. + +The [`max_prepared_stmt_count`](https://dev.mysql.com/doc/refman/en/server-system-variables.html#sysvar_max_prepared_stmt_count) parameter limits the total number of prepared statements across the server. The default protects the server from excessive memory use. Increase this value only when a benchmark or application needs more prepared statements, and avoid carrying an oversized value into production without measuring memory impact. + +### Dedicated server configuration + +If the system runs only MySQL, enable the dedicated server setting: + +```ini +innodb_dedicated_server=ON ``` -`max_connections` doesn't impact performance, but if a high connection count is expected or required, this should be raised in order to not reject requests from clients. +The [`innodb_dedicated_server`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_dedicated_server) parameter automatically sizes selected InnoDB settings for a server dedicated to MySQL. Check the [MySQL dedicated server documentation](https://dev.mysql.com/doc/refman/en/innodb-dedicated-server.html) for the MySQL version you deploy because the behavior can change between releases. -Keep in mind that more connections means more resources will be consumed, especially memory. Setting this to something higher is completely dependent on use case and requirements. +In MySQL 8.4+, `innodb_dedicated_server` automatically configures `innodb_buffer_pool_size` and `innodb_redo_log_capacity`. On systems with more than `4 GiB` of RAM, `innodb_buffer_pool_size` is set to `75%` of detected system memory. -`max_prepared_stmt_count` is 16382 by default. It's a good idea to set this as small as possible in order to help prevent denial of service attacks. You can make it very large in a test environment that uses many prepared statements. +The auto-sized values are a useful starting point, but you can still override individual settings when workload requirements or performance data justify the change. -### Dedicated Server Configuration +### Buffer pool size + +The [`innodb_buffer_pool_size`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_buffer_pool_size) parameter is one of the most important MySQL performance settings. It controls how much memory InnoDB can use to cache indexes and table data. + +If MySQL runs on a dedicated server, `innodb_dedicated_server=ON` can be enough to size the buffer pool. If you don't use `innodb_dedicated_server`, or you want to test a specific value, set `innodb_buffer_pool_size` based on your workload and available memory: + +```ini +# Example value for a dedicated 128 GiB test system. +innodb_buffer_pool_size=96G ``` -innodb_dedicated_server=ON + +The [MySQL InnoDB buffer pool documentation](https://dev.mysql.com/doc/refman/en/innodb-buffer-pool.html) suggests setting the buffer pool size to as much as `80%` of system memory on a dedicated database server. Leave memory for the operating system, connections, background MySQL memory use, and any other processes on the system. + +Confirm the current buffer pool size: + +```sql +SHOW VARIABLES LIKE 'innodb_buffer_pool_size'; ``` -If the node will only run `MySQL` and no other application. One of the easiest ways to gain performance is by setting `innodb_dedicated_server=ON`. This setting does different things depending on the version of `MySQL`, so it's important to check the [documentation](https://dev.mysql.com/doc/refman/en/innodb-dedicated-server.html) for the specific version of `MySQL` being deployed. As of version 8.4, this setting will automatically set both `innodb_buffer_pool_size` and `innodb_redo_log_capacity`. Two configurations that impact performance. -On systems with a large amount of RAM (greater than 4GB), the `innodb_buffer_pool_size` will be set to 75% total system memory. `innodb_buffer_pool_size` is one of the most important configuration parameters that can be set. It determines how much memory can be used to store indexes and table data. It's a cache that improves read/write latency by relieving pressure on storage. If `innodb_dedicated_server` is not used, then this parameter should be set. The [MySQL documentation](https://dev.mysql.com/doc/refman/en/innodb-buffer-pool.html) suggests this be set to up to 80% of total system memory. The default of 128MiB is probably going to be far less than 80% of total system memory. +{{% notice Note %}} +The `innodb_buffer_pool_size` value is shown in bytes. Use the value reported by MySQL when calculating huge page allocation. +{{% /notice %}} -`innodb_redo_log_capacity` was introduced in MySQL 8.0.30. It controls the amount of disk space used for redo log files. In earlier versions of `MySQL`, the parameters `innodb_log_file_size` and `innodb_log_files_in_group` influence redo log size and behavior. `innodb_redo_log_capacity` simplifies things. When `innodb_dedicated_server` is enabled, `innodb_redo_log_capacity` is set to (number of available logical processors / 2)GB with a max of 16GB. If `innodb_dedicated_server` is not used, then `innodb_redo_log_capacity` should be set. If the redo log is too small, the status variable [`Innodb_log_waits`](https://dev.mysql.com/doc/refman/en/server-status-variables.html#statvar_Innodb_log_waits) will be large. This indicates that the redo log buffer is waiting for the log to be flushed to storage before continuing. Ideally, this status variable is 0 at all times. +### Buffer pool instances -### Huge Pages +For large buffer pools, multiple buffer pool instances can improve concurrency by reducing contention as different threads read and write cached pages. +```ini +# Example value for a large buffer pool. +innodb_buffer_pool_instances=8 ``` -large_pages=ON # default is OFF + +The [`innodb_buffer_pool_instances`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_buffer_pool_instances) setting takes effect only when `innodb_buffer_pool_size` is at least `1 GiB`. The total buffer pool is divided across the instances, so keep each instance at least `1 GiB`. Test values such as `4`, `8`, or `16` with your workload, and avoid creating so many instances that each one becomes too small. + +### Redo log capacity + +For write-heavy workloads, you can keep `innodb_dedicated_server=ON` and explicitly set a larger redo log capacity than the value MySQL calculates automatically: + +```ini +innodb_dedicated_server=ON +# Example override for write-heavy workloads. +innodb_redo_log_capacity=32G ``` -Turning on `large_pages` can result in significant performance gains. +The [`innodb_redo_log_capacity`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_redo_log_capacity) parameter controls the amount of disk space used for redo log files. It was introduced in MySQL `8.0.30`. In earlier MySQL versions, [`innodb_log_file_size`](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_log_file_size) and [`innodb_log_files_in_group`](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_log_files_in_group) control redo log size and behavior. -Using larger pages helps to reduce how often physical memory has to get mapped to virtual memory. Note that huge pages needs to be [turned on at the kernel level](/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib/) for this to work. +The auto-sized `innodb_redo_log_capacity` value is a starting point. Increasing it can improve write-heavy workloads by giving InnoDB more redo log space before checkpoints limit write throughput. An explicit `innodb_redo_log_capacity` value overrides the value calculated by `innodb_dedicated_server` for that variable, while still allowing `innodb_dedicated_server` to size other settings such as `innodb_buffer_pool_size`. -If `innodb_dedicated_server` is set to `ON`, then `innodb_buffer_pool_size` will automatically be set. The value of `innodb_buffer_pool_size` is needed to calculate how many huge pages will need to be allocated. The value of `innodb_buffer_pool_size` can be confirmed by checking the variable in the `mysql` cli. +{{% notice Note %}} +When you override one of the automatically configured variables, MySQL prints a startup warning such as `Option innodb_dedicated_server is ignored for innodb_redo_log_capacity`. That warning is expected for the overridden variable. +{{% /notice %}} -```sql -SHOW VARIABLES LIKE 'innodb_buffer_pool_size'; +Larger redo logs use more disk space and can increase crash recovery time, so test values against both performance and operational requirements. + +### Huge pages + +Enable large page support in the MySQL configuration: + +```ini +large-pages=ON ``` -> NOTE: The innodb_buffer_pool_size unit is bytes. -> There is no need to confirm the value of `innodb_buffer_pool_size` if it is set manually (i.e. you are not using `innodb_dedicated_server=ON`). -> Alternatively, you can estimate the value of `innodb_buffer_pool_size` since the calculation when `innodb_dedicated_server=ON` is in the documentation. Use the command "`free --bytes`" to get the total system memory in bytes. +Turning on [`large-pages`](https://dev.mysql.com/doc/refman/en/server-system-variables.html#sysvar_large_pages) can improve performance when MySQL uses a large InnoDB buffer pool. Larger pages map more memory per translation entry, which can reduce page-table walks and TLB pressure. + +Huge pages must also be configured at the Linux kernel level. For huge page setup instructions, see the [system, kernel, compiler, and library settings](/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib/) section of this Learning Path. + +Divide the buffer pool size by the huge page size to estimate the number of huge pages needed. Use the `Hugepagesize` value from `/proc/meminfo`, and allocate enough huge pages for a total huge page space equal to or slightly larger than the buffer pool. + +{{% notice Important %}} +After restarting MySQL with `large-pages=ON`, check `/proc/meminfo` and the MySQL error log. If the huge page pool is too small, or MySQL can't allocate huge pages for another reason, InnoDB can fall back to traditional memory and print `Warning: Using conventional memory pool.` to the MySQL error log. -Divide this number by the huge page size (convert to bytes first) to get the number of huge pages that should be allocated. Instructions on how to get the huge page size and to set the number of pages is in the [System, Kernel, Compiler, and Libraries](/learning-paths/servers-and-cloud-computing/mysql_tune/kernel_comp_lib/) section. +You might also see an allocation warning similar to `large_page_aligned_alloc mmap(... bytes) failed; errno 12`. +{{% /notice %}} -In general, there's no need to adjust other memory parameters unless an issue is suspected/found. That said, other memory related configurations that could be worth exploring are the [Buffer Pool Prefetching](https://dev.mysql.com/doc/refman/en/innodb-performance-read_ahead.html) configurations (take this as an FYI). You may see modest performance gains by decreasing the `innodb_read_ahead_threshold` from the default. The default is very conservative and will result in very little to no prefetching. Some workloads may benefit from being less conservative with prefetching. Turning on random prefetch (`innodb_random_read_ahead`) seems to hurt performance but could benefit some user cases. The affects of these settings will be use case dependent. +You don't usually need to change other memory parameters unless you observe a specific issue. One optional area to test is [InnoDB buffer pool prefetching](https://dev.mysql.com/doc/refman/en/innodb-performance-read_ahead.html). Lowering [`innodb_read_ahead_threshold`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_read_ahead_threshold) from the default can help workloads with predictable sequential access patterns, while [`innodb_random_read_ahead`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_random_read_ahead) can help some workloads and hurt others. Treat these settings as workload-specific experiments. ### Disk flush behavior -``` -innodb_use_fdatasync=ON # Default is OFF prior to MySQL 8.4 +For MySQL versions earlier than 8.4, test `innodb_use_fdatasync`: + +```ini +innodb_use_fdatasync=ON ``` -Setting `innodb_use_fdatasync` to ON helps reduce the number of system calls that occur when flushing data to disk. Using `fdatasync` reduces flushing by not updating the meta data associated with files when those files are written to. For most use cases, this is acceptable. As of MySQL 8.4, this is now set to `ON` by default. If running an older version of `MySQL`, it is generally recommended to set this to `ON`. In fact, this is why it has been defaulted to `ON` in newer version of `MySQL`. +The [`innodb_use_fdatasync`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_use_fdatasync) parameter allows InnoDB to use `fdatasync()` instead of `fsync()` for operating systems and flush methods that support it. This can improve write performance because `fdatasync()` flushes file data without forcing unrelated metadata updates, such as timestamps to disk. Metadata required to retrieve the data is still flushed. In MySQL 8.4, this setting defaults to `ON`. -### Concurrency configuration +### Transaction durability settings -Increasing parallelism uses available resources more efficiently. It's always a good idea to look at parameters related to parallel execution. +Use the following settings when transaction durability and consistency are required (these are the default in MySQL 8.4+): +```ini +sync_binlog=1 +innodb_flush_log_at_trx_commit=1 ``` -innodb_io_capacity=10000 # Default is 200 prior to MySQL 8.4 and 10000 from 8.4 -innodb_io_capacity_max=20000 # Default is 2x innodb_io_capacity + +The [`sync_binlog`](https://dev.mysql.com/doc/refman/en/replication-options-binary-log.html#sysvar_sync_binlog) parameter controls how often MySQL synchronizes the binary log to disk. + +The [`innodb_flush_log_at_trx_commit`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit) parameter controls how InnoDB writes and flushes redo log records at transaction commit. + +When both settings are `1`, MySQL prioritizes transaction durability over peak write throughput. Relaxing either setting can reduce how often transactions wait for binary log and redo log data to be flushed to durable storage. This can improve parallel transaction execution and write throughput, especially on write-heavy workloads, but it increases the time window where committed transactions exist only in memory or operating system cache. + +{{% notice Warning %}} +Changing `sync_binlog` or `innodb_flush_log_at_trx_commit` away from `1` trades away transaction durability, which is part of ACID compliance. + +Values such as `sync_binlog=0`, `sync_binlog=N` where `N` is greater than `1`, or `innodb_flush_log_at_trx_commit=0` or `2` can lose committed transactions during a power failure, operating system crash, or unexpected MySQL exit. + +Change these settings only when your application and recovery process can tolerate potential transaction loss. +{{% /notice %}} + +### I/O capacity configuration + +Increasing parallelism can help InnoDB use available storage resources more efficiently. For older MySQL versions on SSD-backed or cloud storage, test values similar to the MySQL 8.4 defaults: + +```ini +innodb_io_capacity=10000 +innodb_io_capacity_max=20000 ``` -`innodb_io_capacity` tells the `InnoDB` storage engine how many IOPS it can issue to storage. Prior to `MySQL` 8.4, the default was 200 which is very low and more appropriate for rotational storage. Modern SSD storage and even cloud based storage can benefit greatly from increasing this value. As of `MySQL` 8.4, the default value has been increased to 10000. If you are using an older version of `MySQL` where this is defaulted to 200, it might benefit you to set this to 10000. See the [MySQL InnoDB I/O Capacity documentation](https://dev.mysql.com/doc/refman/en/innodb-configuring-io-capacity.html) for more. +The [`innodb_io_capacity`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_io_capacity) parameter tells InnoDB how many I/O operations per second it can issue to storage for background work. Before MySQL 8.4, the default was `200`, which is often too low for modern SSD and cloud storage. In MySQL 8.4, the default is `10000`. -`innodb_io_capacity_max` defaults to 2x of `innodb_io_capacity`. This should be ok for most use cases. +The [`innodb_io_capacity_max`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_io_capacity_max) parameter provides a higher limit for bursts of background work. It defaults to `2x` `innodb_io_capacity`. Use that relationship as a starting point, then adjust the values based on storage capability and measured performance. ### Spin lock configuration +Use the following setting as a starting point for testing lock polling behavior: + +```ini +innodb_sync_spin_loops=30 ``` -innodb_sync_spin_loops=120 # Default is 30 -``` -You should experiment with the `innodb_sync_spin_loops` parameter. This sets the number of times a thread checks for an `InnoDB` lock to be free before yielding execution to another thread. +The [`innodb_sync_spin_loops`](https://dev.mysql.com/doc/refman/en/innodb-parameters.html#sysvar_innodb_sync_spin_loops) parameter controls how many times a thread checks whether an InnoDB mutex is free before yielding execution to another thread. + +Profiling MySQL under heavy load on Arm with Linux `perf` can show time spent waiting for locks. Increasing `innodb_sync_spin_loops` can reduce context switching when locks are released quickly, but setting it too high can waste power and delay other useful work. Keep the default value, `30`, unless profiling and measured performance show that a different value helps. For more information, see the MySQL [Configuring Spin Lock Polling documentation](https://dev.mysql.com/doc/refman/en/innodb-performance-spin_lock_polling.html). + +## What you've learned + +You've now explored various MySQL parameters you can tune for improved performance. -Profiling `MySQL` under heavy load on Arm with Linux `perf` shows that `MySQL` spends a lot of time waiting for locks to be freed. Experimenting with tuning parameters around locks might help. Increasing the number of times a lock is checked before the thread yields can reduce context switching. This reduction in context switching tends to increase performance. Start with a value of 120 for `innodb_sync_spin_loops`, but you can also try values such as 30, 60, 180, and 240. See the [Configuring Spin Lock Polling](https://dev.mysql.com/doc/refman/en/innodb-performance-spin_lock_polling.html) for more. \ No newline at end of file +You can use the guidance in this Learning Path to optimize the performance of your MySQL databases on Arm. diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md new file mode 100644 index 0000000000..fd55d9730b --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_index.md @@ -0,0 +1,115 @@ +--- +title: Deploy an Amazon EKS cluster with AWS Graviton-based nodes using Rafay + +description: Use the Rafay Kubernetes Operations Platform to provision an Amazon EKS cluster with an AWS Graviton-based node group and deploy NGINX to verify the setup. + + +minutes_to_complete: 60 + +who_is_this_for: > + This is an advanced topic for software developers familiar with Kubernetes and AWS who want to learn how to use the Rafay platform to provision and manage EKS clusters backed by AWS Graviton-based instances. + +learning_objectives: + - Connect your AWS account to the Rafay platform using a cross-account IAM role + - Provision an Amazon EKS cluster with an AWS Graviton-based node group using Rafay + - Deploy and verify workloads on arm64 nodes and clean up all cloud resources + +prerequisites: + - An Amazon Web Services (AWS) [account](https://aws.amazon.com/) with sufficient IAM permissions to create roles, EKS clusters, EC2 instances, CloudFormation stacks, and related resources. + - A [Rafay account](https://rafay.co). + - The [AWS CLI](/install-guides/aws-cli/) installed and configured. + +# START generated_summary_faq +generated_summary_faq: + template_version: summary-faq-v3 + generated_at: '2026-06-24T20:45:31Z' + generator: ai + ai_assisted: true + ai_review_required: true + model: gpt-5 + prompt_template: summary-faq-v3 + source_hash: 76cbd5e4b3a61e9604e0df9b3ba2a5e5af4aa9a0c295ece3c4ee5a98ec365630 + summary_generated_at: '2026-06-24T20:45:31Z' + summary_source_hash: 76cbd5e4b3a61e9604e0df9b3ba2a5e5af4aa9a0c295ece3c4ee5a98ec365630 + faq_generated_at: '2026-06-24T20:45:31Z' + faq_source_hash: 76cbd5e4b3a61e9604e0df9b3ba2a5e5af4aa9a0c295ece3c4ee5a98ec365630 + summary: >- + You'll provision an Amazon EKS cluster on Arm using + the Rafay Kubernetes Operations Platform and validate workloads on AWS Graviton-based nodes. + First, you'll define a declarative cluster manifest in Rafay referencing an existing project, + blueprint, and cloud credential. Then, you'll create the EKS cluster and deploy NGINX pinned to arm64 + to confirm scheduling on Graviton-based instances. Finally, you'll remove the NGINX workload and deprovision the EKS resources to avoid ongoing cloud costs. + faqs: + - question: How do I know the AWS connection to Rafay is set up correctly before creating the + cluster? + answer: >- + Ensure the cross-account IAM role is configured in AWS and added to Rafay as a cloud credential. + In the cluster manifest, reference this credential by name. If it's missing or has insufficient + permissions, cluster creation will fail. + - question: Which fields in the Rafay cluster manifest must match existing configuration? + answer: >- + The project, blueprint name and version, and the cloud credential must already exist in + Rafay. If any of these don't match, the cluster won't be created. + - question: What result should I expect when the EKS cluster is ready to use? + answer: >- + A running cluster with a Graviton-based (`arm64`) node group will be available for workloads. + Nodes should advertise the label `kubernetes.io/arch=arm64`, indicating they can run `arm64` + pods. + - question: How do I verify that the NGINX deployment is running on Graviton nodes? + answer: >- + The provided manifest pins the pods using `nodeSelector: kubernetes.io/arch: arm64`. After + deployment, the pod should schedule and run on nodes labeled `arm64`. If it remains `Pending`, + verify the node group is active and the selector matches node labels. + - question: What should I clean up to avoid ongoing AWS charges? + answer: >- + Delete the NGINX workload and namespace created for the test, then deprovision the EKS cluster + from Rafay. This releases the associated AWS resources. +# END generated_summary_faq + +author: Jason Andrews + +generate_summary_faq: false +rerun_summary: false +rerun_faqs: false + +### Tags +skilllevels: Advanced +subjects: Containers and Virtualization +cloud_service_providers: + - AWS +armips: + - Neoverse +operatingsystems: + - Linux +tools_software_languages: + - Kubernetes + - AWS Elastic Kubernetes Service (EKS) + - Rafay + - NGINX + - rctl + +# FIXED, DO NOT MODIFY +# ================================================================================ +further_reading: + - resource: + title: Rafay CLI overview + link: https://docs.rafay.co/cli/overview/ + type: documentation + - resource: + title: Amazon EKS documentation + link: https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html + type: documentation + - resource: + title: AWS Graviton processors + link: https://aws.amazon.com/ec2/graviton/ + type: documentation + - resource: + title: Kubernetes documentation + link: https://kubernetes.io/docs/home/ + type: documentation + +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # Indicates 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/rafay-eks/_next-steps.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_next-steps.md new file mode 100644 index 0000000000..727b395ddd --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/_next-steps.md @@ -0,0 +1,8 @@ +--- +# ================================================================================ +# FIXED, DO NOT MODIFY THIS FILE +# ================================================================================ +weight: 21 # The weight controls the order of the pages. _index.md always has weight 1. +title: "Next Steps" # Always the same, html page title. +layout: "learningpathall" # All files under learning paths have this same wrapper for Hugo processing. +--- diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md new file mode 100644 index 0000000000..0695230889 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/cluster.md @@ -0,0 +1,190 @@ +--- +title: Create an Amazon EKS cluster using a Rafay cluster manifest +description: Create and apply a Rafay cluster manifest to provision an Amazon EKS cluster with an AWS Graviton-based node group, then download kubeconfig and verify the nodes report arm64. +weight: 3 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Create the cluster manifest + +The Rafay platform uses a declarative YAML manifest to define your EKS cluster. + +Create a file named `demo-eks-graviton.yaml` with the following content: + +```yaml +apiVersion: infra.k8smgmt.io/v3 +kind: Cluster +metadata: + # The name of the cluster + name: demo-eks-graviton + # The name of the project the cluster will be created in + project: defaultproject +spec: + blueprintConfig: + # The name of the blueprint the cluster will use + name: minimal + # The version of the blueprint the cluster will use + version: latest + # The name of the cloud credential that will be used to create the cluster + cloudCredentials: aws-cloud-credential + config: + # The EKS addons that will be applied to the cluster + addons: + - name: kube-proxy + version: latest + - name: vpc-cni + version: latest + - name: coredns + version: latest + managedNodeGroups: + # The AWS AMI family type the nodes will use + - amiFamily: AmazonLinux2023 + # The desired number of nodes that can run in the node group + desiredCapacity: 1 + iam: + withAddonPolicies: + # Enables the IAM policy for cluster autoscaler + autoScaler: true + # Allows for full ECR (Elastic Container Registry) access. This is useful for building, for example, a CI server that needs to push images to ECR + imageBuilder: true + # The Amazon EC2 instance type that will be used for the nodes + instanceType: m7g.large + # The maximum number of nodes that can run in the node group + maxSize: 1 + # The minimum number of nodes that can run in the node group + minSize: 1 + # The name of the node group that will be created in AWS + name: graviton + metadata: + # The name of the cluster + name: demo-eks-graviton + # The AWS region the cluster will be created in + region: us-east-1 + # The tags that will be applied to the AWS cluster resources + tags: + email: user@rafay.co + env: qa + # The Kubernetes version that will be installed on the cluster + version: latest + vpc: + # AutoAllocateIPV6 requests an IPv6 CIDR block with /56 prefix for the VPC + autoAllocateIPv6: false + clusterEndpoints: + # Enables private access to the Kubernetes API server endpoints + privateAccess: true + # Enables public access to the Kubernetes API server endpoints + publicAccess: false + # The CIDR that will be used by the cluster VPC + cidr: 192.168.0.0/16 + type: aws-eks +``` + +Key fields to note: + +- `cloudCredentials` must exactly match the credential name you entered in the Rafay console. +- `project` must be the project you attached the credential to. +- `instanceType` must be a Graviton-based EC2 instance type with Arm Neoverse processors. In this manifest, it's Graviton3-based `m7g.large`. +- `publicAccess` must be `false`. The Kubernetes API server has no public endpoint. You reach the cluster exclusively through RCTL, which routes traffic through the Rafay control plane. + +## Apply the cluster manifest + +Submit the manifest to Rafay using `rctl`: + +```console +rctl apply -f demo-eks-graviton.yaml +``` + +The output is similar to: + +```output +[ + { + "tasksetId": "ko9176k", + "tasksetOperations": [ + { + "operationName": "ClusterCreation", + "resourceName": "demo-eks-graviton", + "operationStatus": "PROVISION_TASK_STATUS_INPROGRESS" + }, + { + "operationName": "NodegroupCreation", + "resourceName": "graviton", + "operationStatus": "PROVISION_TASK_STATUS_PENDING" + }, + { + "operationName": "BlueprintSync", + "resourceName": "demo-eks-graviton", + "operationStatus": "PROVISION_TASK_STATUS_PENDING" + } + ], + "tasksetStatus": "PROVISION_TASKSET_STATUS_INPROGRESS", + "comments": "Configuration is being applied to the cluster" + } +] +``` + +## Monitor cluster provisioning + +Poll the cluster status until it reports `READY`: + +```console +rctl get cluster demo-eks-graviton +``` +Provisioning typically takes 15–20 minutes as Rafay creates the VPC, EKS control plane, and managed node group. + +The output is similar to: + +```output ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +| NAME | CREATED AT | TYPE | STATUS | BLUEPRINT | PROVISION STATUS | ENVIRONMENT CREATED | ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +| demo-eks-graviton | 2026-06-24T15:32:19.936269Z | aws-eks | NOT_READY | minimal | INFRA_CREATION_INPROGRESS | false | ++-------------------+-----------------------------+---------+-----------+-----------+---------------------------+---------------------+ +``` + +While waiting, you can run the command again every few minutes. You'll see various status values before the status changes to `READY`. You can also check the AWS CloudFormation console to look for any stack errors. + +## Download the kubeconfig + +After the cluster is `READY`, download the kubeconfig file: + +```console +rctl kubeconfig download --cluster demo-eks-graviton -f ~/.kube/demo-eks-graviton.kubeconfig +``` + +The output is similar to: + +```output +kubeconfig downloaded to ~/.kube/demo-eks-graviton.kubeconfig +``` + +Export the path so that `kubectl` uses this cluster: + +```console +export KUBECONFIG=~/.kube/demo-eks-graviton.kubeconfig +``` + +## Verify the nodes + +Confirm that the cluster has a running node and that it reports the `arm64` architecture: + +```console +kubectl get nodes -L kubernetes.io/arch +``` + +The output is similar to: + +```output +NAME STATUS ROLES AGE VERSION ARCH +ip-192-168-13-74.ec2.internal Ready 26m v1.36.2-eks-93b80c6 arm64 +``` + +The `arm64` value in the `ARCH` column confirms that the node is running on an AWS Graviton-based instance. Your EKS cluster is ready to accept workloads. + +## What you've accomplished and what's next + +You've now defined and provisioned an Amazon EKS cluster with a Graviton-based node group using Rafay's declarative manifest format. You then applied the manifest with RCTL, waited for the cluster to reach a ready state, and downloaded the kubeconfig so you can interact with the cluster. + +In the next section, you'll deploy NGINX to this cluster and verify it runs on the Graviton-based node. diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp b/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp new file mode 100644 index 0000000000..b9dd2a8265 Binary files /dev/null and b/content/learning-paths/servers-and-cloud-computing/rafay-eks/images/rafay-cloud-credential.webp differ diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md new file mode 100644 index 0000000000..99576ed52c --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/nginx.md @@ -0,0 +1,166 @@ +--- +title: Deploy NGINX to the Amazon EKS cluster and clean up +description: Deploy NGINX to an Amazon EKS cluster on AWS Graviton-based nodes, test in-cluster connectivity, and clean up the Kubernetes and cloud resources. +weight: 4 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Deploy NGINX + +With the Amazon EKS cluster running on Graviton-based nodes, deploy NGINX to confirm that `arm64` workloads schedule and run correctly. + +Create a file named `nginx-graviton.yaml` with the following content: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: nginx +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-arm-deployment + namespace: nginx +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-arm + template: + metadata: + labels: + app: nginx-arm + spec: + nodeSelector: + kubernetes.io/arch: arm64 # Pin pods to Graviton (arm64) nodes + containers: + - name: nginx + image: nginx:1.27 + ports: + - containerPort: 80 +--- +apiVersion: v1 +kind: Service +metadata: + name: nginx-arm-svc + namespace: nginx +spec: + selector: + app: nginx-arm + ports: + - protocol: TCP + port: 80 + targetPort: 80 + type: ClusterIP +``` + +The `nodeSelector: kubernetes.io/arch: arm64` field ensures the pod is scheduled only on nodes that report the `arm64` architecture label. The Graviton node you provisioned has this label. + +Apply the manifest: + +```console +kubectl apply -f nginx-graviton.yaml +``` + +The output is similar to: + +```output +namespace/nginx created +deployment.apps/nginx-arm-deployment created +service/nginx-arm-svc created +``` + +## Verify the deployment + +Check that the pod reaches the `Running` state: + +```console +kubectl get pods -n nginx +``` + +The output is similar to: + +```output +NAME READY STATUS RESTARTS AGE +nginx-arm-deployment-6d4f9b8c7d-xk2pq 1/1 Running 0 30s +``` + +Confirm the service was created: + +```console +kubectl get svc -n nginx +``` + +The output is similar to: + +```output +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +nginx-arm-svc ClusterIP 10.100.42.137 80/TCP 30s +``` + +## Test NGINX connectivity + +The NGINX service is type `ClusterIP`, which means it has no external IP and is reachable only from within the cluster network. The cluster also has `publicAccess: false`, so there's no public Kubernetes API endpoint. Both constraints mean you can't test connectivity from your local machine directly. + +Instead, run a one-off pod inside the cluster that sends a request to the service and then deletes itself: + +```console +kubectl run curl-test --rm -it --image=curlimages/curl --restart=Never -- curl http://nginx-arm-svc.nginx.svc +``` + +The output is similar to: + +```output + + + +Welcome to nginx! + + +

Welcome to nginx!

+

If you see this page, the nginx web server is successfully installed and +working. Further configuration is required.

+ + +pod "curl-test" deleted +``` + +The NGINX welcome page confirms that the workload is running and reachable on your Graviton-based EKS cluster. + +## Clean up resources + +Remove the NGINX workload and then delete the cluster to avoid ongoing AWS charges. + +Delete the NGINX resources: + +```console +kubectl delete -f nginx-graviton.yaml +``` + +The output is similar to: + +```output +namespace "nginx" deleted +deployment.apps "nginx-arm-deployment" deleted +service "nginx-arm-svc" deleted +``` + +{{< notice warning >}} +Deleting the cluster through RCTL triggers the removal of the EKS control plane, managed node group, and associated CloudFormation stacks in your AWS account. If you don't run this command, AWS will continue to charge you for the running EC2 instances and EKS control plane. +{{< /notice >}} + +Delete the EKS cluster through Rafay: + +```console +rctl delete cluster demo-eks-graviton +``` + +## What you've accomplished + +You've now deployed NGINX using a manifest that pins pods to `arm64` nodes, verified the pod reaches a `Running` state, and tested connectivity from inside the cluster. You then cleaned up all provisioned resources. + +Rafay's control plane handles cluster access without requiring a public Kubernetes API endpoint, so you can use Rafay to run private, Graviton-based EKS clusters at scale. + diff --git a/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md b/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md new file mode 100644 index 0000000000..76c181ac20 --- /dev/null +++ b/content/learning-paths/servers-and-cloud-computing/rafay-eks/setup.md @@ -0,0 +1,449 @@ +--- +title: Set up Rafay and AWS access +description: Install kubectl and rctl, configure Rafay CLI access, and register an AWS cloud credential so Rafay can provision a Graviton-based Amazon EKS cluster. +weight: 2 + +### FIXED, DO NOT MODIFY +layout: learningpathall +--- + +## Before you begin + +[Rafay](https://rafay.co) is a Kubernetes operations platform that provisions, secures, and manages the full cluster lifecycle across public cloud, private, and hybrid environments. It provides a single control plane for fleet-wide operations including automated provisioning, upgrades, and governance. + +In this Learning Path, you'll use Rafay to provision an Amazon EKS cluster with an AWS Graviton-based node group and deploy a workload to verify the setup. + +You need the following accounts and tools before starting this Learning Path: + +- An [AWS account](https://aws.amazon.com/) with sufficient IAM permissions to create roles, EKS clusters, EC2 instances, CloudFormation stacks, and related resources. +- A [Rafay account](https://console.rafay.dev). You can [sign up](https://console.rafay.dev/#/signup) if you don't have an account. +- The AWS CLI installed and configured with credentials that have the required permissions. For setup instructions, see the [AWS CLI](/install-guides/aws-cli/) and the [AWS Credentials](/install-guides/aws_access_keys/) install guides. + +Confirm your AWS CLI is working by running the following command, which prints your account and user information: + +```console +aws sts get-caller-identity +``` + +## Install kubectl + +Install the Kubernetes command-line tool by following the [kubectl install guide](/install-guides/kubectl/). + +Confirm the installation: + +```console +kubectl version --client +``` + +The output is similar to: + +```output +Client Version: v1.32.1 +Kustomize Version: v5.5.0 +``` + +## Install RCTL + +RCTL is the Rafay CLI. You'll use it to submit cluster manifests, check cluster status, download kubeconfig files, and delete clusters. + +To download RCTL, log in to the Rafay console, navigate to **My Tools** > **Download CLI**, and download the binary for your operating system. + +The downloads are `.tar.bz2` files. + +On macOS with Apple Silicon, extract the file with: + +```console +tar xvf rctl-darwin-arm64.tar.bz2 +``` + +On Arm Linux, use the filename: + +```console +tar xvf rctl-linux-arm64.tar.bz2 +``` + +{{% notice Note %}} +RCTL is also available for x86_64 Linux and Windows. Modify the filename to match your platform as needed. +{{% /notice %}} + +Move the binary to a directory in your search path: + +```console +sudo mv rctl /usr/local/bin/ +``` + +## Configure RCTL + +Download the RCTL configuration file from the Rafay console. Navigate to **My Tools** > **Download CLI Config** and save the file. + +The file name is formatted for your user information. + +Copy the downloaded file to a known location and initialize `rctl` with it: + +```console +cp ~/Downloads/.json ~/rafay-config.json +rctl config init ~/rafay-config.json +``` + +The config command doesn't have any output. + +Verify the installation: + +```console +rctl version +``` + +The output is similar to: + +```output +VERSION: r4.2.0 +BUILD: r4.2.0-1 +BUILD-TIME: Thu 04 Jun 2026 07:17:05 AM UTC +ARCH: darwin/arm64 +``` + +Confirm that `rctl` can reach the Rafay platform: + +```console +rctl config show +``` + +The output lists your account information, including the endpoints, keys, project, and organization information. + +## Create an AWS IAM role for Rafay + +Rafay provisions EKS resources in your AWS account using a cross-account IAM role. You need two values from the Rafay console before running the script: + +1. Log in to the Rafay console. +2. Select **defaultproject** (or another project) from the project selector in the navigation bar. +3. Navigate to **Infrastructure** > **Cloud Credentials** > **New Credential**. +4. Select **AWS** as the provider, then select **ROLE**. Copy the **Rafay Account ID** and **External ID** displayed on the screen. You'll pass these values to the script that follows. + +Save the following script as `create-rafay-role.sh`: + +```bash +#!/bin/bash +set -euo pipefail + +read -rp "Enter Rafay Account ID: " RAFAY_ACCOUNT_ID +read -rp "Enter External ID: " EXTERNAL_ID + +ROLE_NAME="RafayEKSProvisioner" +REGION="us-east-1" + +TRUST_POLICY=$(cat < **Cloud Credentials** > **New Credential** in the Rafay console. +2. Paste the `Role ARN` into the **Role ARN** field. +3. Enter `aws-cloud-credential` as the credential name. +4. Select **Save**. + +![Screenshot of the Rafay Cloud Credentials page showing the aws-cloud-credential entry with provider AWS, credential type ROLE, and a masked RafayEKSProvisioner role detail#center](images/rafay-cloud-credential.webp "Registered AWS cloud credential in the Rafay console") + +## What you've accomplished and what's next + +You've now installed `kubectl` and `rctl`, authenticated `rctl` to Rafay, and registered an AWS cloud credential. + +Next, you'll create the EKS cluster. diff --git a/content/learning-paths/servers-and-cloud-computing/vllm/_index.md b/content/learning-paths/servers-and-cloud-computing/vllm/_index.md index 069912aca1..030c0ed599 100644 --- a/content/learning-paths/servers-and-cloud-computing/vllm/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/vllm/_index.md @@ -1,5 +1,6 @@ --- -title: Build and Run vLLM on Arm Servers +title: Build and run vLLM on Arm servers +description: Build vLLM from source on an Arm Linux server, run batch inference with a Hugging Face model, and expose the model through an OpenAI-compatible API. minutes_to_complete: 45 @@ -7,12 +8,13 @@ who_is_this_for: This is an introductory topic for software developers and AI en learning_objectives: - Build vLLM from source on an Arm server. - - Download a Qwen LLM from Hugging Face. + - Use a Qwen LLM from Hugging Face. - Run local batch inference using vLLM. - Create and interact with an OpenAI-compatible server provided by vLLM on your Arm server. prerequisites: - - An [Arm-based instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider, or a local Arm Linux computer with at least 8 CPUs and 16 GB RAM. + - An [Arm-based Linux instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider, or a local Arm Linux computer running Ubuntu 24.04 with at least 8 CPUs, 16 GB RAM, and 50 GB of disk storage. + - A system that includes support for BFloat16. author: Jason Andrews @@ -59,4 +61,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/vllm/vllm-run.md b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-run.md index eb0f2a17f6..23cffc9ffc 100644 --- a/content/learning-paths/servers-and-cloud-computing/vllm/vllm-run.md +++ b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-run.md @@ -1,5 +1,6 @@ --- title: Run batch inference using vLLM +description: Use vLLM to load a Qwen model from Hugging Face and run batch inference prompts on an Arm server. weight: 3 ### FIXED, DO NOT MODIFY @@ -8,11 +9,11 @@ layout: learningpathall ## Use a model from Hugging Face -vLLM is designed to work seamlessly with models from the Hugging Face Hub. +vLLM is designed to work with models from the Hugging Face Hub. -The first time you run vLLM, it downloads the required model. This means that you do not have to explicitly download any models. +The first time you run vLLM, it downloads the required model. You don't have to explicitly download any models. -If you want to use a model that requires you to request access or accept the terms, you need to log in to Hugging Face using a token. +To use a model that requires you to request access or accept terms and conditions, log in to Hugging Face using a token: ```bash huggingface-cli login @@ -20,15 +21,15 @@ huggingface-cli login Enter your Hugging Face token. You can generate a token from [Hugging Face Hub](https://huggingface.co/) by clicking your profile on the top right corner and selecting **Access Tokens**. -You also need to visit the Hugging Face link printed in the login output and accept the terms by clicking the **Agree and access repository** button or filling out the request-for-access form, depending on the model. +Visit the Hugging Face link printed in the login output and accept the terms and conditions. Click the **Agree and access repository** button or fill out the request-for-access form, depending on the model. -To run batched inference without the need for a login, you can use the `Qwen/Qwen2.5-0.5B-Instruct` model. +To run batched inference without logging in, use the `Qwen/Qwen2.5-0.5B-Instruct` model. ## Create a batch script -To run inference with multiple prompts, you can create a simple Python script to load a model and run the prompts. +To run inference with multiple prompts, create a Python script to load a model and run the prompts. -Use a text editor to save the Python script below in a file called `batch.py`: +Use a text editor to save the following Python script in a file called `batch.py`: ```python import json @@ -137,4 +138,10 @@ Processed prompts: 100%|██████████████████ } ``` -You can try with other prompts and models such as `meta-llama/Llama-3.2-1B`. Continue to learn how to set up an OpenAI-compatible server. +## What you've accomplished and what's next + +You've now created a Python batch inference script that loads the `Qwen/Qwen2.5-0.5B-Instruct` model from Hugging Face, configures `bfloat16` precision, and sends multiple prompts to vLLM. + +You ran the script and confirmed that vLLM starts on the CPU backend, loads the model, processes the prompts, and returns generated text. + +Next, you'll set up an OpenAI-compatible server so client applications can send requests to vLLM. diff --git a/content/learning-paths/servers-and-cloud-computing/vllm/vllm-server.md b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-server.md index 68b848503e..d9b73b8cd9 100644 --- a/content/learning-paths/servers-and-cloud-computing/vllm/vllm-server.md +++ b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-server.md @@ -1,20 +1,23 @@ --- -title: Run an OpenAI-compatible server +title: Run an OpenAI-compatible vLLM server +description: Start a local vLLM OpenAI-compatible server on Arm Linux and send a chat completion request with curl. weight: 4 ### FIXED, DO NOT MODIFY layout: learningpathall --- -Instead of a batch run from Python, you can create an OpenAI-compatible server. This allows you to leverage the power of Large Language Models without relying on external APIs. +## Create a local vLLM server compatible with OpenAI + +To run Large Language Models (LLMs) without relying on external APIs, create an OpenAI-compatible server. Running a local LLM offers several advantages: -* Cost-effective - it avoids the costs associated with using external APIs, especially for high-usage scenarios. +* Cost-effectiveness - it avoids the costs associated with using external APIs, especially for high-usage scenarios. * Privacy - it keeps your data and prompts within your local environment, which enhances privacy and security. -* Offline Capability - it enables operation without an internet connection, making it ideal for scenarios with limited or unreliable network access. +* Offline capability - it enables operation without an internet connection, making it ideal for scenarios with limited or unreliable network access. -OpenAI compatibility means that you can reuse existing software which was designed to communicate with OpenAI and use it to communicate with your local vLLM service. +OpenAI compatibility means that you can reuse existing software to communicate with your local vLLM service. Run vLLM with the same `Qwen/Qwen2.5-0.5B-Instruct` model: @@ -22,7 +25,7 @@ Run vLLM with the same `Qwen/Qwen2.5-0.5B-Instruct` model: python3 -m vllm.entrypoints.openai.api_server --model Qwen/Qwen2.5-0.5B-Instruct --dtype float16 --max-num-batched-tokens 32768 ``` -The server output displays that it is ready for requests: +The output is similar to: ```output INFO 12-12 22:54:40 cpu_executor.py:186] # CPU blocks: 21845 @@ -51,7 +54,7 @@ INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) You can submit requests to the server using the `curl` command. -For example, run the command below using another terminal on the same server: +For example, run the following command using another terminal on the same server: ```bash curl http://0.0.0.0:8000/v1/chat/completions \ @@ -72,12 +75,16 @@ curl http://0.0.0.0:8000/v1/chat/completions \ }' ``` -The server processes the request, and the output prints the results: +The server processes the request, and the output is similar to: ```output "id":"chatcmpl-6677cb4263b34d18b436b9cb8c6a5a65","object":"chat.completion","created":1734044182,"model":"Qwen/Qwen2.5-0.5B-Instruct","choices":[{"index":0,"message":{"role":"assistant","content":"Certainly! Here is a simple \"Hello, World!\" program in C:\n\n```c\n#include \n\nint main() {\n printf(\"Hello, World!\\n\");\n return 0;\n}\n```\n\nThis program defines a function called `main` which contains the body of the program. Inside the `main` function, it calls the `printf` function to display the text \"Hello, World!\" to the console. The `return 0` statement indicates that the program was successful and the program has ended.\n\nTo compile and run this program:\n\n1. Save the code above to a file named `hello.c`.\n2. Open a terminal or command prompt.\n3. Navigate to the directory where you saved the file.\n4. Compile the program using the following command:\n ```\n gcc hello.c -o hello\n ```\n5. Run the compiled program using the following command:\n ```\n ./hello\n ```\n Or simply type `hello` in the terminal.\n\nYou should see the output:\n\n```\nHello, World!\n```","tool_calls":[]},"logprobs":null,"finish_reason":"stop","stop_reason":null}],"usage":{"prompt_tokens":26,"total_tokens":241,"completion_tokens":215,"prompt_tokens_details":null},"prompt_logprobs":null} ``` -There are many other experiments you can try. Most Hugging Face models have a **Use this model** button on the top-right of the model card with the instructions for vLLM. You can now use these instructions on your Arm Linux computer. +## What you've accomplished + +You've now set up a local OpenAI-compatible server and tested sending requests to the server. + +You can use the instructions in this Learning Path to experiment with other models on your Arm Linux computer. Most Hugging Face models include a **Use this model** button with instructions for vLLM. You can also try out OpenAI-compatible chat clients to connect to the served model. diff --git a/content/learning-paths/servers-and-cloud-computing/vllm/vllm-setup.md b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-setup.md index 4f5a8d9b85..309bbc93a5 100644 --- a/content/learning-paths/servers-and-cloud-computing/vllm/vllm-setup.md +++ b/content/learning-paths/servers-and-cloud-computing/vllm/vllm-setup.md @@ -1,5 +1,6 @@ --- -title: Build a vLLM from Source Code +title: Build a vLLM from source code on Arm Linux +description: Prepare an Arm Ubuntu server for vLLM by checking BFloat16 support, installing dependencies, and building the CPU backend from source. weight: 2 ### FIXED, DO NOT MODIFY @@ -8,35 +9,33 @@ layout: learningpathall ## Before you begin -To follow the instructions for this Learning Path, you will need an Arm server running Ubuntu 24.04 LTS with at least 8 cores, 16GB of RAM, and 50GB of disk storage. You also need a system which supports BFloat16. +[Virtual Large Language Model (vLLM)](https://github.com/vllm-project/vllm) is a fast and easy-to-use library for inference and model serving. -To check if your system includes BFloat16, use the `lscpu` command: +You can use vLLM in batch mode, or by running an OpenAI-compatible server. + +In this Learning Path, you'll learn how to build vLLM from source and run inference on an Arm-based server. + +Start by checking if your system includes BFloat16 using the `lscpu` command: ```console lscpu | grep bf16 ``` -If the `Flags` are printed, you have a processor with BFloat16. +If you have a processor with BFloat16, the output is similar to: ```output Flags: fp asimd evtstrm aes pmull sha1 sha2 crc32 atomics fphp asimdhp cpuid asimdrdm jscvt fcma lrcpc dcpop sha3 asimddp sha512 sve asimdfhm dit uscat ilrcpc flagm sb paca pacg dcpodp sve2 sveaes svepmull svebitperm svesha3 flagm2 frint svei8mm svebf16 i8mm bf16 dgh rng bti ``` -If the result is blank, you do not have a processor with BFloat16. +If the output is blank, you don't have a processor with BFloat16. -BFloat16 provides improved performance and smaller memory footprint with the same dynamic range. You might experience a drop in model inference accuracy with BFloat16, but the impact is acceptable for the majority of applications. +BFloat16 provides improved performance and smaller memory footprint with the same dynamic range. You might experience a drop in model inference accuracy with BFloat16, but the tradeoff is acceptable for the majority of applications. -The instructions have been tested on an AWS Graviton3 `m7g.2xlarge` instance. +The instructions in this Learning Path have been tested on an AWS Graviton3 `m7g.2xlarge` instance. -## What is vLLM? +## Install dependencies to build vLLM -[vLLM](https://github.com/vllm-project/vllm) stands for Virtual Large Language Model, and is a fast and easy-to-use library for inference and model serving. - -You can use vLLM in batch mode, or by running an OpenAI-compatible server. - -In this Learning Path, you will learn how to build vLLM from source and run inference on an Arm-based server, highlighting its effectiveness. - -### What software do I need to install to build vLLM? +After validating that your system supports BFloat16, install vLLM dependencies. First, ensure your system is up-to-date and install the required tools and libraries: @@ -45,16 +44,16 @@ sudo apt-get update -y sudo apt-get install -y curl ccache git wget vim numactl gcc g++ python3 python3-pip python3-venv python-is-python3 libtcmalloc-minimal4 libnuma-dev ffmpeg libsm6 libxext6 libgl1 libssl-dev pkg-config ``` -Next, install Rust. For more information, see the [Rust install guide](/install-guides/rust/). +Next, install Rust. For installation steps, see the [Rust install guide](/install-guides/rust/). ```bash curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source "$HOME/.cargo/env" ``` -Four environment variables are required. You can enter these at the command line or add them to your `$HOME/.bashrc` file and source the file. +Next, set up required environment variables. You can either enter the variables at the command line or add them to your `$HOME/.bashrc` file and source the file. -To add them at the command line, use the following: +To add the environment variables at the command line, run: ```bash export CCACHE_DIR=/home/ubuntu/.cache/ccache @@ -72,14 +71,14 @@ source env/bin/activate Your command-line prompt is prefixed by `(env)`, which indicates that you are in the Python virtual environment. -Now update Pip and install Python packages: +Now update `pip` and install Python packages: ```bash pip install --upgrade pip pip install py-cpuinfo ``` -### How do I download vLLM and build it? +## Download and build vLLM First, clone the vLLM repository from GitHub: @@ -90,9 +89,9 @@ git checkout releases/v0.11.0 ``` {{% notice Note %}} -The Git checkout specifies a specific hash known to work for this example. +The Git checkout specifies a version known to work for this example. -Omit this command to use the latest code on the main branch. +Omit this checkout command to use the latest code on the main branch. {{% /notice %}} Install the Python packages for vLLM: @@ -102,7 +101,7 @@ pip install -r requirements/build.txt pip install -v -r requirements/cpu.txt ``` -Build vLLM using Pip: +Build vLLM using `pip`: ```bash VLLM_TARGET_DEVICE=cpu python3 setup.py bdist_wheel @@ -116,4 +115,8 @@ rm -rf dist cd .. ``` -You are now ready to download a large language model (LLM) and run vLLM. +## What you've accomplished and what's next + +You've now verified BFloat16 support, installed the build dependencies, configured the required environment variables, and built vLLM from source for the CPU backend. + +Next, you'll use vLLM with a Hugging Face model to run batch inference on your Arm server. diff --git a/themes/arm-design-system-hugo-theme/layouts/index.html b/themes/arm-design-system-hugo-theme/layouts/index.html index 7dd4fdd9f4..f81c1fc29b 100644 --- a/themes/arm-design-system-hugo-theme/layouts/index.html +++ b/themes/arm-design-system-hugo-theme/layouts/index.html @@ -65,7 +65,7 @@

Arm Learning Paths

- +

{{ replace .Title "and" "&" }}

@@ -79,7 +79,7 @@

{{ replace .Ti
- +

AI

diff --git a/themes/arm-design-system-hugo-theme/layouts/partials/head/head.html b/themes/arm-design-system-hugo-theme/layouts/partials/head/head.html index 6969f026b3..e6b24dd365 100644 --- a/themes/arm-design-system-hugo-theme/layouts/partials/head/head.html +++ b/themes/arm-design-system-hugo-theme/layouts/partials/head/head.html @@ -39,11 +39,7 @@ {{ partial "head/jsonld.html" . }} - - - - - +