reis-mobile 0.3.6 → 0.5.0

package/skills/mobile-android/references/build-and-performance/android-cli/references/interact.md

@@ -0,0 +1,113 @@
+Run `android layout --help` and `android screen --help`.
+
+## UI Dump
+
+`android layout` returns a flat JSON list of the UI elements on screen. `android
+layout --diff` returns a flat JSON list of the UI elements that have changed
+since the last call to `layout` or `layout --diff`
+
+Each JSON object represents a UI element in the Android app. The following
+properties may be present:
+
+- `text` - any literal text the element contains
+- `resourceId` - the Android resource id used to refer to the element
+- `contentDesc` - a description of a UI element for use by accessibility tools
+- `interactions` - the set of user interactions the element supports. May contain one or more of: `checkable`, `clickable`, `focusable`, `scrollable`, `long-clickable`, `password`
+- `state` - the set of states the element is in. May contain one or more of `checked`, `focused`, `selected`
+- `bounds` - the screen coordinates of the bounding rectangle of the element, in the format `[min X,min Y][max X, max Y]`
+- `center` - the screen coordinates of the center of the element, in the format `[x,y]`
+- `off-screen` - if true, the element is in the UI hierarchy but not visible; it may require scrolling to view.
+
+Use `layout` as a primary means of examining an Android app. Use `layout --diff`
+to focus on changes and to keep your context small. Example: When entering
+digits into a calculator, use `layout --diff` to output only the digit readout
+element.
+
+`layout` may fail due to the app displaying a WebView or animation; in these
+cases, use `android screen capture --annotate` to inspect the app. This failure
+will likely resolve after navigating away from the current screen.
+
+## Screenshot
+
+`android screen capture -o <file path>` saves a PNG of the current device screen
+to `<file path>`
+
+Use `screen capture` as a secondary means of examining an Android app
+Examples:
+
+- Understanding the content of an on-screen image
+- Looking at a `WebView` (web content does not always appear in the ui dump)
+- Trying to find a UI element by its visual appearance
+
+**IMPORTANT** : Always *VISUALLY* examine the PNG image returned from `android
+screen` BEFORE doing anything else.
+
+## Annotated Screenshot
+
+`android screen capture --annotate -o <file path>`
+`android screen resolve --screen <path> --string <string>`
+
+The `--annotate` command adds numerical labels and bounding boxes around UI
+elements. Use this command to locate UI elements that cannot be located in the
+`layout` output.
+
+**IMPORTANT** : When using `android screen --annotate`, always *VISUALLY* examine
+the resulting PNG file.
+
+To refer to these labels in input commands, use `screen resolve` to convert
+labels into coordinates:
+
+`android screen resolve --screen <file path> --string "#3"` returns `<x coord of
+region 3> <y coord of region 3>`
+
+To save turns, you can combine shell commands:
+
+`adb shell input $(android screen resolve --screen screen.png --string "tap #34")`
+
+This command taps on region #34 from `screen.png`
+
+## Input
+
+Use `adb shell input` for interacting with Android devices. Refer to the
+`"interactions"` property of an element for what interactions can be performed
+on a particular element.
+
+Interact with UI elements with their `center` coordinate or their `bounds`
+coordinates:
+`json
+{
+"key": -248568265,
+"class": "android.widget.Button",
+"bounds": "[138,9][167,38]",
+"center": "[152,23]"
+}`
+
+To tap on this button, you would execute `adb shell input tap 152 23`. This taps
+the center.
+
+    {
+      "key": 12487234,
+      "class": "com.example.ui.ScrollableList",
+      "bounds": "[100,200][400,600]",
+      "center": "[250,400]"
+    }
+
+To scroll down on this list, you would execute `adb shell input swipe 250 400
+250 200 500`. This swipes from the center to the top over 500ms.
+
+### Text Input
+
+To enter text, ensure the field is focused and execute `adb shell input text
+"<text>"`.
+
+- **Spaces (`%s`):** Replace spaces with `%s` (Android ignores text after raw spaces): `adb shell input text "Hello%sworld"` (enters `"Hello world"`).
+- **Special characters:** Escape shell metacharacters (`&`, `$`, `(`, `)`, `!`): `adb shell input text "AT\&T"` or `adb shell input text 'Price:\$10'`.
+- **Submit / Enter:** `adb shell input keyevent 66`
+
+## Android Interaction Rules
+
+1. Always ensure text input fields have `"focused"` in their `"state"` list before entering text.
+2. If an element has `"scrollable"` in its `"interactions"` list, try scrolling it when looking for missing UI elements.
+3. Always scroll slowly when executing scroll inputs. The 5th argument to `adb
+   shell input swipe` controls scroll duration.
+4. Content may take time to load; if a `layout` is missing information after you take an action, wait a few seconds, then perform `layout --diff` to see if anything changes.

package/skills/mobile-android/references/build-and-performance/android-cli/references/journeys.md

@@ -0,0 +1,120 @@
+A journey is an XML-specified test of an Android app's behavior. It consists of
+a list of `<action>` elements. For example:
+`xml
+<journey name="My Journey">
+<description>
+A sample journey to illustrate the format
+</description>
+<actions>
+<action>
+Tap the "Home" icon
+</action>
+<action>
+Verify that the app is on its Home screen
+</action>
+</actions>
+</journey>`
+
+Evaluate a journey by proceeding through the `<actions>` list in sequential
+order. Evaluate each `<action>` block individually.
+A journey succeeds if all elements in the `<actions>` list succeed.
+
+A journey is a test case for an app. The journey XML is the source of truth; if
+the app disagrees with the journey, the app has failed.
+Additionally, if the app exits, crashes, or freezes, journey evaluation stops
+and the journey fails.
+
+**IMPORTANT** - Execute each step EXACTLY as written, and independently of other
+steps! If an action says to `"tap the first search result"`,
+you MUST find the search results and tap the first one. Do this even if you
+believe you know the intent behind the action.
+
+## Taking Actions
+
+Some `<action>` elements specify UI interactions to perform on the running
+Android app. Perform the interaction and verify that the app does
+not crash or behave in an unexpected manner. This is the *only* verification
+you should perform for an `<action>`.
+
+If the interaction cannot be performed as specified, the journey fails.
+Example:
+`<action>Click the red button</action>`
+If you determine a red button is not present in the UI, the journey fails.
+
+If the text of an `<action>` specifies a list of actions, break it into
+sub-actions and evaluate them individually:
+Example:
+`<action>Search for soda and add the first result to the cart</action>`
+This should be evaluated as:
+`<action>Search for soda</action>
+<action>Add the first result to the cart</action>`
+
+If an `<action>` contains something that is not a specification for a UI
+interaction, alert the user that the journey is malformed and exit
+early, specifying the error in question.
+
+## Verifying Expectations
+
+`<action>` elements that begin with "check" or "verify" specify expectations
+for the current state of the Android app. Determine the current
+state of the app and check if the expectations are met.
+
+Determine the current state of the app by inspecting the current screen of the
+device without interacting with it.
+Example:
+`<action>Check if "Switch 2" is visible on the screen</action>`
+This requires only inspecting the current screen, not scrolling or interacting.
+If "Switch 2" is not currently visible, the action fails.
+
+If the expectations are not met, mark the `<action>` as a failure and the
+journey evaluation ends. A single `<action>` may contain
+multiple expectations.
+Example:
+`<action>Verify that the app is on the Home screen, the Home icon is blue, and the temperature is displayed</action>`
+This `<action>` fails if ANY of the following are false:
+
+- The app is on the Home screen
+- There is a Home icon, and it is blue
+- A temperature is displayed
+
+## Handling failure
+
+When running a journey, evaluate it as a test. Failure is acceptable, and often
+expected. Proper reporting of failures is the priority.
+
+Keep debugging and troubleshooting to a minimum; assume that tools are showing
+you the correct output every time. The goal is to determine
+if the *current* Android app can correctly handle the *current* steps outlined
+in the journey. Suggestions for bug fixes, clarification, or
+other improvements should be kept to journey evaluation summary at the end.
+
+## Summarizing
+
+After evaluating the whole journey, output a markdown (.md) file describing the
+results.
+
+The file should have the following format:
+
+    # Journey: <Name of the journey>
+
+    ## Results
+
+      <!-- Append "✅" to the action header if the instruction was evaluated or "❌" if the instruction could not be evaluated -->
+    ### Action: Click the blue button ✅
+    - **Commands**:
+      <!-- A list of the ADB commands executed while evaluating the instruction -->
+      - `adb shell input swipe 490 200 500 500 500`
+      - `adb shell input tap 45 920`
+
+      <!-- Failure reasons, feedback, or other useful information -->
+    - **Comment**: The journey step doesn't specify that the button requires scrolling to see
+
+    ### Action: Check if "Switch 2" is visible on the screen ✅
+    - **Screenshot**: [switch_2_screenshot.png](path/to/screenshot)
+    - **Comment**: Confirmed both in layout and visually
+
+    ### Action: The home screen is shown ❌
+    - **Comment**: The settings page was shown
+
+    <!-- Append nothing to the action header if the action was not evaluated because the journey execution ended early -->
+    ### Action: Swipe down to view active notifications

package/skills/mobile-android/references/build-and-performance/android-profiler/GUIDE.md

@@ -0,0 +1,34 @@
+> Adapted from the `android-profiler` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
+
+# Android Profiler Orchestrator
+
+Your primary role is **Intent Disambiguation and Routing**; route the user to
+the correct workflow or prepare an execution plan for the user. Work with the
+user to finalize the plan and then proceed with the plan execution, addressing
+singular as well as composite needs.
+
+## Prerequisites and Setup
+
+Before executing any workflows, read
+[`references/env_setup.md`](references/env_setup.md) (it sits next to this file
+in the skill root). It defines what to set `$SKILL_ROOT` to - the anchor every
+other path in this skill is written against.
+
+## Intent Disambiguation
+
+Do not guess the user's intent. If the user request is not clear, **ask the
+user** what they want to do before proceeding.
+
+## Recording
+
+Route all recording requests through
+`$SKILL_ROOT/recording/recording_orchestrator.md`. This defines guidelines and
+pre-flight checks or dependency checks that apply to all recording workflows,
+and ensures you have the necessary setup to proceed. Read the orchestrator and
+execute the plan it describes based on what the user wants to record (for
+example, a system trace or a heap dump).
+
+## Analysis
+
+Route all analysis requests through
+`$SKILL_ROOT/analysis/analysis_orchestrator.md`.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/analysis_orchestrator.md

@@ -0,0 +1,32 @@
+# Analysis Orchestrator
+
+Use the guidelines below to find the right analysis workflow to execute based
+on the user intent (for example, analyzing a system trace or a heap dump).
+
+Ensure you can answer the following: "User intends to
+[analyze/query/investigate] ______". For example,
+"User intends to analyze a heap dump to investigate a memory leak".
+
+## Handling Composite Requests
+
+If the user's request involves multiple distinct analysis goals (for example,
+analyzing a trace for jank AND checking for memory leaks or GPU issues),
+do not execute them simultaneously.
+
+1. Break down the request and propose a sequential execution plan to the user.
+2. Ask the user for confirmation to start the first step.
+3. Do not proceed to the next workflow until the current one is completed.
+
+## Workflow Discovery and Routing
+
+This skill supports multiple specialized analysis workflows. To determine the
+right workflows to use:
+
+1. Use your file search tools (for example, `grep_search`) to recursively scan
+   the `$SKILL_ROOT/analysis/workflows/` directory for workflow entrypoints
+   (markdown files defining a top-level `name:` key in their frontmatter,
+   ignoring internal `references/` subdirectories).
+2. Compare the user's request and intent against the `name:`, `description:`,
+   and `keywords:` fields to identify matching workflows. If multiple are
+   found, present them as options to the user and proceed with the
+   user's selection.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-sql/perfetto_sql.md

@@ -0,0 +1,28 @@
+---
+name: perfetto-sql
+description: >
+  Translates natural language data intents into syntactically valid PerfettoSQL
+  queries and/or executes them against a trace file, if provided. Use this
+  workflow to draft, debug, or execute queries extracting slice, thread, or
+  memory data from Android Perfetto traces using trace_processor.
+keywords:
+  - Perfetto SQL
+  - SQL Guidelines
+  - SQL Best Practices
+  - Ad-hoc Query
+  - Trace Processor
+  - SPAN_JOIN
+  - Idempotency
+---
+
+# Ad-Hoc PerfettoSQL Querying
+
+Use this workflow to write, debug, or execute PerfettoSQL queries:
+
+- **Executing against a trace:** If a trace file path or URL is provided, verify
+  environment prerequisites in `$SKILL_ROOT/references/perfetto/setup.md` and
+  follow the session execution workflow in
+  `$SKILL_ROOT/references/perfetto/sql.md`.
+- **Static query authoring or debugging:** If no trace is attached, draft,
+  optimize, or debug the queries using the syntax, schema guidelines, and
+  standard library best practices in `$SKILL_ROOT/references/perfetto/sql.md`.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/perfetto_trace_analysis.md

@@ -0,0 +1,121 @@
+---
+name: perfetto-trace-analysis
+description: >
+  Analyzes Perfetto traces to find the root cause of performance issues in
+  user or system Android apps (for example, janks, app startup, memory, or
+  latency stalls).
+keywords:
+  - perfetto
+  - trace
+  - jank
+  - startup
+  - latency
+  - stall
+  - thread
+  - bottleneck
+---
+
+# Perfetto Trace Analysis
+
+Use this workflow to diagnose general Android performance issues: jank, app
+startup, latency, stall, or a thread-blocking problem.
+
+Follow these steps in order:
+
+## Step 1: Identify what to investigate first
+
+Work with the user (for example, ask questions, present options) to
+understand the following:
+
+- _What is the symptom_: Do they want to investigate frame drops, jank,
+  startup issues, app crash, system crash, ANR?
+- _Who is the victim:_ Where did they observe the symptom? For example, "a
+  frame drop in `com.example.sample`".
+
+> **Input Trace Required:** Confirm that the user has provided a trace file
+> path or URL (for example, `.pftrace`, `.perfetto-trace`, or a Perfetto UI
+> link). If none is provided, pause and ask the user to provide one before
+> proceeding.
+
+> If you do not know the symptom, pause and ask the user for clarification.
+
+> If you know the symptom but not the victim, proceed to Step 2 (Triage) to
+> discover candidates. Present the 3-5 most severe instances to the user and
+> proceed with the user selection.
+
+> **A/B Trace Comparison:** If the user provides multiple traces (for
+> example, a baseline and an issue trace), explicitly clarify which is the
+> baseline. You will pass both paths to the subagents in Step 3 so they can
+> use the baseline trace to establish expected behavior.
+
+## Step 2: Run a system-wide triage
+
+Spin off a subagent/task and instruct it to follow instructions from
+`$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/triage.md`
+to run a system-wide triage. (Do not read this file yourself. Pass this path
+in the sub-agent prompt so it loads the file and performs the triage steps).
+
+Note the output produced by the subagent to identify the filtered list of
+**candidates** that we need to investigate.
+
+> **Note:**
+> - If no candidates are found, ask the user for symptom clarification and
+>   specific timestamps.
+> - If the triage reveals multiple candidates, select the top 2 or 3 most
+>   severe, representative candidates and ask the user before proceeding
+>   which ones to investigate. The user may choose one or more.
+
+**Expected outcome:** Confirmation on which candidate(s) to investigate
+before proceeding.
+
+## Step 3: Investigate each branch in parallel
+
+For **every** candidate (one or more) identified in the previous step, spin
+off a task/subagent to investigate these tracks _in parallel_.
+
+Construct a prompt for each candidate containing:
+```markdown
+Trace path: [path]
+Baseline Trace Path: [path, if provided]
+Candidate Info: [`utid`, `upid`, thread_name, process_name, `render_thread_utid` (if applicable)]
+Symptom Window: [start_ts, end_ts, duration]
+System Vitals: [payload from Step 2]
+Budget: [expected duration, if applicable]
+Execution Protocol: Read
+`$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/per_candidate_analysis.md`
+and follow its instructions end-to-end.
+```
+
+SPAWN the subagent(s) in parallel and await completion of all subagents before
+proceeding to Step 4.
+
+## Step 4: Final report and consolidation
+
+Read the output from every spawned subagent and generate a consolidated "Trace
+Analysis Report" adhering to these instructions:
+
+1. **Summary and Root Cause:** State the findings in simple, clear language
+   and classify root causes (hardware, software/code, scheduling policy,
+   system exhaustion, or external dependency).
+2. **Dependency Chain:** Map the full path from symptom to root cause.
+   Include thread names, `UTID`s, blocking states, and exact timestamps at
+   every hop.
+3. **Evidence Tags:** Tag every single claim with `[SQL]` (backed by data),
+   `[INFERRED]` (logical deduction), or `[GAP]` (partial or missing data),
+   and briefly define these tags at the start.
+4. **Platform Context:** Explain Android system behaviors _only_ by citing
+   specific retrieved slice names, values, and timestamps.
+   **What's bad:** "SurfaceFlinger does X around vsync"
+   **What's a good explanation:** "SurfaceFlinger's composition slice at
+   `ts=142.3ms` ran `4ms` after the vsync signal at `ts=138.1ms`, consistent
+   with X".
+5. **Partial Suspects:** List all branches that were investigated but did not
+   reach a terminal root cause, ranked by evidence strength. Include what
+   was found and where verification fell short. A partial suspect can be the
+   real contributor - report it even if a terminal root cause was found
+   elsewhere.
+
+   > If evidence is evenly split between multiple potential causes, report each
+   > suspicion with its supporting data and evidence so that engineers can
+   > evaluate probabilities without false certainty. Do not arbitrarily pick
+   > a winner.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/references/guiding_principles.md

@@ -0,0 +1,51 @@
+# Guiding Principles for Trace Analysis
+
+Whether you are augmented with domain-specific knowledge or doing a standard
+workflow analysis, follow these rules.
+
+**Why:** Performance analysis is complex. It is entirely possible to end up
+identifying a root cause while the reality is different (for example, a hardware
+bottleneck causing a cascade of failures). The principles below keep your
+analysis grounded in truth and ensure that you investigate the entire causal
+chain to discover the true bottleneck.
+
+1. **Schema Validation via Intrinsic Discovery:**
+   Read `$SKILL_ROOT/references/perfetto/sql.md` and query table schemas
+   using `LIMIT 0` before drafting queries.
+   - **Why:** Trace processor schemas evolve across versions; discovering
+   schema directly prevents invalid assumptions and syntax failures.
+2. **Empirical Data Grounding:** Support every claim with tool output or
+   queried timestamps, slice durations or counter values (`[SQL]`).
+   - **Why:** General Android heuristics cannot substitute for ground-truth
+     trace metrics. When queries return empty results, broaden search
+     constraints using fuzzy matching or wider time windows.
+3. **Causation vs. Correlation:** Verify that the blocker's active execution
+   overlaps with the victim's wait interval.
+   - **Why:** Concurrent anomalies are only causally linked if their
+     execution lifetimes intersect. For example, just because thread A was busy
+     while thread B was waiting does not necessarily mean thread A caused the
+     wait.
+4. **Follow Evidence:** Follow dependency chains across thread, process and
+   kernel boundaries to the terminal root cause. Keep going as long as
+   **each hop meaningfully explains the symptom**.
+   - **Why:** Halting blocker traversal prematurely reports intermediate
+     symptoms rather than the true origin.
+5. **Explicit Uncertainty Reporting:** Categorize unverified execution paths
+   as `[GAP]` or partial suspects.
+   - **Why:** Transparent reporting of missing data enables engineers to evaluate
+     probabilities without false certainty.
+6. **Evidence-First Explanation:** Cite concrete retrieved metrics and slice
+   timestamps before asserting platform behavioral context.
+   - **Why:** Contextual explanations are only reliable when anchored in
+     empirical trace observations.
+7. **Systemic Confound Sweeps:** Before attributing a bottleneck to
+   application software, verify that thermal throttling, CPU capping
+   (`cpufreq`), scheduling (`sched_slice`), or LMKD pressure isn't uniformly
+   degrading the system. Report such confounds as root cause modifiers.
+   > To uncover short-lived anomalies that get mathematically missed by simple
+   > averages or aggregate queries, isolate and look around the symptom window
+   > and query for individual event spikes or percentiles.
+8. **Systematic Step Adherence:** At every step of your investigation, strictly
+   follow the defined investigation steps.
+   - **Why:** Structured verification prevents analytical blind spots and
+     premature conclusions on obvious but non-critical anomalies.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/domain_hints_template.md

@@ -0,0 +1,7 @@
+---
+domain: The specific domain or product.
+description: Description of the domain/subsystem for effective routing
+keywords:
+  - List of symptoms and keywords where these hints are applicable,
+    for example, 'jank', 'surfaceflinger', 'vulkan'.
+---

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_cpu.md

@@ -0,0 +1,56 @@
+---
+subsystem: cpu
+description: >
+  Expert hints for CPU scheduling, thread states, CPU contention, and
+  frequency scaling.
+keywords:
+  - cpu
+  - scheduling
+  - latency
+  - runnable
+  - running
+  - thread state
+  - governor
+  - core
+  - frequency
+---
+
+# CPU & Scheduling Expert Hints
+
+- When debugging a long slice: Examine its thread states to understand what the
+  thread was doing (running, sleeping, blocked on I/O).
+- When debugging a long slice for latency issues: Check if its duration is
+  caused by one or more long-running child slices. Apply recursively.
+- When a thread is woken up but there is a delay before it runs, check the
+  "IRQ" track for the corresponding CPU to see if an interrupt is the cause.
+- Check if kernel threads associated with hardware are running with real-time
+  priority; if not, they can be preempted.
+- When analysis of the primary application package does not reveal root cause,
+  expand to all threads and processes. Search for other runnable threads on the
+  same CPU or high-priority kernel threads.
+- When investigating app startup, use an SQL query to aggregate reasons for
+  uninterruptible sleep on the main thread.
+- Check the "cpu_frequency" counter for CPU cores that ran the main process.
+  Missing frequency data or stuck frequencies indicate a kernel-level bug in
+  the governor.
+- Query raw "ftrace" events for logs related to the governor thread (for
+  example, "su_gov").
+- To find concurrency issues, search for critical threads (for example,
+  'RenderThread') in a blocked state (`thread_state.state = 'D'`) and join with
+  scheduling data to find the waker.
+- Compare time spent in userspace functions vs kernel (slices with [k] prefix).
+- To detect a 'catch-up storm', look for threads with long gaps in
+  thread_state/cpu_slice activity immediately followed by a high-density burst.
+- Quantify scheduler contention by calculating scheduling latency (measure
+  duration of preceding 'Runnable' state using
+  `preceding_sched_slice_for_thread`). Search for maximums and high percentiles
+  (p95/p99).
+- If a task exhibits high scheduling latency, check if other CPUs were idle
+  (running swapper or idle thread).
+- Check the `cpu_id` for key threads; if consistently scheduled on slower
+  cores, it signals a potential performance gain by allowing them on big cores.
+- For a struggling thread, analyze 'Runnable' vs 'Running' state time. A large
+  'Runnable' time indicates CPU contention.
+- If a slice's wall duration increases but the percentage of 'Running' time is
+  unchanged, it strongly suggests a lower CPU frequency. Check `sched_switch`
+  to focus on the correct cores.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_graphics.md

@@ -0,0 +1,51 @@
+---
+subsystem: graphics
+description: >
+  Expert hints for graphics performance, UI jank, GPU memory, and frame
+  rendering.
+keywords:
+  - graphics
+  - ui jank
+  - gpu
+  - frame
+  - vsync
+  - render
+  - surfaceflinger
+  - texture
+  - bitmap
+---
+
+# Graphics & UI Jank Expert Hints
+
+- When investigating UI jank, check for long-running slices on the main
+  thread; if a slice like "ConstraintLayout.onMeasure" is taking a long time
+  (for example, >8ms), it is a likely cause of the jank.
+- When a `bitmap_write_to_parcel` slice takes milliseconds instead of
+  microseconds, investigate its children slices to see how time is spent. Long
+  durations often point to suboptimal kernel operations like memory mapping
+  (`mmap`) or unnecessary data zeroing.
+- For a high-level overview of graphics memory usage, track `gpu_mem_total`
+  counter for a specific process (`upid`).
+- To find the largest graphics allocations, query the `android_graphics_allocs`
+  table and sort by `size_bytes` in descending order. Compare width and height
+  against the device's display resolution.
+- To detect the "double memory cost" of an image existing on both CPU and GPU,
+  look for a large buffer in `android_graphics_allocs` and a simultaneous CPU
+  memory allocation of a similar size (`rss_anon_bytes` or `heap_graph`).
+- To find potentially costly intermediate render targets, look for large
+  buffers in `android_graphics_allocs` where `usage_bits` lack a
+  `COMPOSER_OVERLAY` flag.
+- To check if an allocation is actually presented on screen, correlate
+  `buffer_id` with SurfaceFlinger events.
+- To see if high graphics memory is causing performance issues, check the frame
+  duration in `actual_frame_timeline_slice`. Durations over vsync (for
+  example, 16.6ms) correlating with `gpu_mem_total` spikes suggest memory
+  pressure jank.
+- Within the main thread of a janky graphics application, look for frequent or
+  long-running `texture_upload` slices.
+- Analyze the duration of `eglSwapBuffersWithDamageKHR` or similar buffer-swap
+  slices in the graphics rendering thread. Consistently long durations suggest
+  a large "damage area" being redrawn every frame.
+- To identify UI jank, compare `actual_frame_timeline` against the
+  `expected_frame_timeline` on the main process; a significant deviation
+  indicates missed frames.

package/skills/mobile-android/references/build-and-performance/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_io.md

@@ -0,0 +1,46 @@
+---
+subsystem: io
+description: >
+  Expert hints for I/O and storage bottlenecks, uninterruptible sleep, and
+  page cache.
+keywords:
+  - i/o
+  - storage
+  - disk
+  - uninterruptible sleep
+  - d state
+  - page fault
+  - dm-verity
+  - file
+  - syscall
+---
+
+# I/O & Storage Expert Hints
+
+- When debugging a long, uninterruptible sleep state related to I/O: Check for
+  overlapping slices with "verity" in their name (dm-verity).
+- When a thread is stuck in an uninterruptible sleep with no `blocked_function`,
+  look for other threads that might be holding the memory lock (for example,
+  "jit-thread-pool", memory mapping ops).
+- When analyzing a long uninterruptible sleep, check the `blocked_function` in
+  the thread state details (from `sched_blocked_reason` ftrace event).
+- A lot of time spent in `do_page_fault` during app startup is a strong
+  indicator of I/O contention.
+- For file integrity mechanisms like DM-Verity, search for events like
+  `dm_verity_fec_prefetch`.
+- To find the specific kernel dependency of a stalled app thread, locate the
+  thread in state 'D', then look for kworker or kernel threads that become
+  runnable immediately after.
+- For app stalls caused by I/O, analyze the scheduling latency of the relevant
+  kworker threads handling the request.
+- To find inefficient file I/O, query the syscall table for a high frequency
+  of small, sequential `read()` or `pread()` syscalls on a single fd.
+- If a thread spends significant time in 'Uninterruptible Sleep', check if
+  `blocked_function` is `page_cache_readahead`. Correlate waking timestamps
+  with `filemap_add_to_page_cache` ftrace events.
+- Aggregate counts of `filemap_add_to_page_cache` grouping by `inode` to find
+  the specific file causing I/O pressure.
+- Inspect `nr_sector` in `block_rq_issue` ftrace events to understand file
+  read-ahead size.
+- If an I/O issue disappears on subsequent launches, it is a 'cold start'
+  problem (populating page cache).