Merging upstream version 127.0.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

6 files changed, 113 insertions, 8 deletions

diff --git a/tools/profiler/docs/code-overview.rst b/tools/profiler/docs/code-overview.rst
index 3ca662e141..bb9db364de 100644
--- a/tools/profiler/docs/code-overview.rst
+++ b/tools/profiler/docs/code-overview.rst
@@ -2,7 +2,7 @@ Profiler Code Overview
 ######################
 
 This is an overview of the code that implements the Profiler inside Firefox
-with dome details around tricky subjects, or pointers to more detailed
+with some details around tricky subjects, or pointers to more detailed
 documentation and/or source code.
 
 It assumes familiarity with Firefox development, including Mercurial (hg), mach,
diff --git a/tools/profiler/docs/index.rst b/tools/profiler/docs/index.rst
index 53920e7d2f..02eb9f6839 100644
--- a/tools/profiler/docs/index.rst
+++ b/tools/profiler/docs/index.rst
@@ -23,13 +23,13 @@ while the profiler.firefox.com interface is documented at `profiler.firefox.com/
    buffer
    instrumenting-javascript
    instrumenting-rust
+   instrumenting-android
    markers-guide
    memory
 
 The following areas still need documentation:
 
  * LUL
- * Instrumenting Java
  * Registering Threads
  * Samples and Stack Walking
  * Triggering Gecko Profiles in Automation
diff --git a/tools/profiler/docs/instrumenting-android.rst b/tools/profiler/docs/instrumenting-android.rst
new file mode 100644
index 0000000000..fdd96613b4
--- /dev/null
+++ b/tools/profiler/docs/instrumenting-android.rst
@@ -0,0 +1,102 @@
+Instrumenting Android
+========================
+
+There are multiple ways to use the profiler with Android. There is the "Java"
+profiler feature (via about:profiling), which enables profiling for JVM code.
+This is most likely turned on already for the preset if you are profiling an
+Android device.
+
+In addition to sampling, markers can be created to specifically mark an instant
+in time, or a duration. This can be helpful to make sense of a particular piece
+of the front-end, or record events that normally wouldn't show up in samples.
+
+.. note::
+    This guide explains Android markers in depth. To learn more about how to add a
+    marker in C++, JavaScript or Rust, please take a look at their documentation
+    in :doc:`markers-guide`, :doc:`instrumenting-javascript` or
+    :doc:`instrumenting-rust` respectively.
+
+Markers in the GeckoView Java codebase
+**************************************
+
+If you are in the GeckoView codebase, then you should have access to ``GeckoRuntime``.
+``GeckoRuntime`` has a ``getProfilerController`` method to get the ``ProfilerController``.
+See the `ProfilerController Java file`_ (`javadoc`_) to find which methods you can use to
+instrument your source code.
+
+Here's an example:
+
+.. code-block:: java
+
+    // Simple marker
+    sGeckoRuntime.getProfilerController().addMarker("Marker Name");
+
+    // Simple marker with additional information
+    sGeckoRuntime.getProfilerController().addMarker("Marker Name", "info");
+
+    // Duration marker
+    Double startTime = sGeckoRuntime.getProfilerController().getProfilerTime();
+    // ...some code you want to measure...
+    sGeckoRuntime.getProfilerController().addMarker("Marker Name", startTime);
+
+    // Duration marker with additional information
+    sGeckoRuntime.getProfilerController().addMarker("Marker Name", startTime, "info");
+
+There are various overloads of ``addMarker`` you can choose depending on your need.
+
+If you need to compute some information before adding it to a marker, it's
+recommended to wrap that code with a `isProfilerActive` if check to make sure
+that it's only executed while the profiler is active. Here's an example:
+
+.. code-block:: java
+
+  ProfilerController profilerController = runtime.getProfilerController();
+  if (profilerController.isProfilerActive()) {
+    // Compute the information you want to include.
+    String info = ...
+    sGeckoRuntime.getProfilerController().addMarker("Marker Name", info);
+  }
+
+Markers in the Fenix codebase
+*****************************
+
+If you are in the Fenix codebase, then you should have access to the Android
+components. The Android components includes a `Profiler interface here`_, with
+its corresponding `implementation here`_. You should be able to do everything
+you can do with the ``ProfilerController``. Here's an example on how to call them:
+
+.. code-block:: kotlin
+
+    // Simple marker
+    components.core.engine.profiler?.addMarker("Marker Name");
+
+    // Simple marker with additional information
+    components.core.engine.profiler?.addMarker("Marker Name", "info");
+
+    // Duration marker
+    val startTime = components.core.engine.profiler?.getProfilerTime()
+    // ...some code you want to measure...
+    components.core.engine.profiler?.addMarker("Marker Name", startTime, "additional info")
+
+    // Duration marker with additional information
+    components.core.engine.profiler?.addMarker("Marker Name", startTime, "info");
+
+Similarly, there are various overloads of ``addMarker`` you can choose depending on your needs.
+
+Like for the GeckoView example above, if you need to compute some information
+before adding it to a marker, it's recommended to wrap that code with a
+`isProfilerActive` if check to make sure that it's only executed while the
+profiler is active. Here's an example:
+
+.. code-block:: kotlin
+
+  if (components.core.engine.profiler?.isProfilerActive() == true) {
+    // Compute the information you want to include.
+    var info = ...
+    components.core.engine.profiler?.addMarker("Marker Name", info)
+  }
+
+.. _ProfilerController Java file: https://searchfox.org/mozilla-central/source/mobile/android/geckoview/src/main/java/org/mozilla/geckoview/ProfilerController.java
+.. _javadoc: https://mozilla.github.io/geckoview/javadoc/mozilla-central/org/mozilla/geckoview/ProfilerController.html
+.. _Profiler interface here: https://searchfox.org/mozilla-central/source/mobile/android/android-components/components/concept/base/src/main/java/mozilla/components/concept/base/profiler/Profiler.kt
+.. _implementation here: https://searchfox.org/mozilla-central/source/mobile/android/android-components/components/browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/profiler/Profiler.kt
diff --git a/tools/profiler/docs/instrumenting-javascript.rst b/tools/profiler/docs/instrumenting-javascript.rst
index 928d94781e..4ad5118256 100644
--- a/tools/profiler/docs/instrumenting-javascript.rst
+++ b/tools/profiler/docs/instrumenting-javascript.rst
@@ -11,8 +11,9 @@ or record events that normally wouldn't show up in samples.
 
 .. note::
     This guide explains JavaScript markers in depth. To learn more about how to add a
-    marker in C++ or Rust, please take a look at their documentation
-    in :doc:`markers-guide` or :doc:`instrumenting-rust` respectively.
+    marker in C++, Rust or JVM please take a look at their documentation
+    in :doc:`markers-guide`, :doc:`instrumenting-rust` or :doc:`instrumenting-android`
+    respectively.
 
 Markers in Browser Chrome
 *************************
diff --git a/tools/profiler/docs/instrumenting-rust.rst b/tools/profiler/docs/instrumenting-rust.rst
index c3e12f42dc..603c008b6c 100644
--- a/tools/profiler/docs/instrumenting-rust.rst
+++ b/tools/profiler/docs/instrumenting-rust.rst
@@ -124,8 +124,9 @@ and an optional payload of a specific type (containing arbitrary data relevant t
 
 .. note::
     This guide explains Rust markers in depth. To learn more about how to add a
-    marker in C++ or JavaScript, please take a look at their documentation
-    in :doc:`markers-guide` or :doc:`instrumenting-javascript` respectively.
+    marker in C++, JavaScript or JVM, please take a look at their documentation
+    in :doc:`markers-guide` or :doc:`instrumenting-javascript`,
+    :doc:`instrumenting-android` respectively.
 
 Examples
 ^^^^^^^^
diff --git a/tools/profiler/docs/markers-guide.rst b/tools/profiler/docs/markers-guide.rst
index ed18b35867..ac0e4430b9 100644
--- a/tools/profiler/docs/markers-guide.rst
+++ b/tools/profiler/docs/markers-guide.rst
@@ -9,8 +9,9 @@ and an optional payload of a specific type (containing arbitrary data relevant t
 
 .. note::
     This guide explains C++ markers in depth. To learn more about how to add a
-    marker in JavaScript or Rust, please take a look at their documentation
-    in :doc:`instrumenting-javascript` or :doc:`instrumenting-rust` respectively.
+    marker in JavaScript, Rust or JVM, please take a look at their documentation
+    in :doc:`instrumenting-javascript`, :doc:`instrumenting-rust` or
+    :doc:`instrumenting-android` respectively.
 
 Example
 -------