pw_kernel: Add cheat sheet docs

Change-Id: Ie251c923a3f6af401558746579d69c304f6ed343 Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/267232 Pigweed-Auto-Submit: Erik Gilling <[email protected]> Reviewed-by: Alexei Frolov <[email protected]> Lint: Lint 🤖 <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Commit-Queue: Auto-Submit <[email protected]>
google · Feb 11, 2025 · 63fde05 · 63fde05
1 parent 6aeb739
commit 63fde05
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 1 deletion.
diff --git a/pw_kernel/BUILD.bazel b/pw_kernel/BUILD.bazel
@@ -33,6 +33,7 @@ alias(
 sphinx_docs_library(
     name = "docs",
     srcs = [
+        "cheat_sheet.rst",
         "docs.rst",
     ],
     prefix = "pw_kernel/",

diff --git a/pw_kernel/BUILD.gn b/pw_kernel/BUILD.gn
@@ -22,5 +22,8 @@ pw_test_group("tests") {
 }
 
 pw_doc_group("docs") {
-  sources = [ "docs.rst" ]
+  sources = [
+    "cheat_sheet.rst",
+    "docs.rst",
+  ]
 }
diff --git a/pw_kernel/cheat_sheet.rst b/pw_kernel/cheat_sheet.rst
@@ -0,0 +1,94 @@
+.. _module-pw_kernel-cheat-sheet:
+
+===========
+Cheat Sheet
+===========
+.. pigweed-module-subpage::
+   :name: pw_kernel
+
+.. _module-pw_kernel-build:
+
+-------------
+rust_analyzer
+-------------
+
+Generating rust-project.json
+============================
+
+For a given ``$CONFIG`` in:
+
+* k_host
+* k_qemu_lm3s6965evb
+* k_rp2350
+
+.. code-block:: shell
+
+   bazelisk run @rules_rust//tools/rust_analyzer:gen_rust_project -- --config $CONFIG //pw_kernel/...
+
+
+Errors and warnings in VSCode
+=============================
+
+Add this to Pigweed's ``.vscode/settings.json``.  Note that it only builds the
+kernel targets to limit the amount of time that it takes to run.  Substitute
+``$CONFIG`` for the config chosen above.
+
+.. code-block:: json
+
+   "rust-analyzer.check.overrideCommand": [
+     "bazelisk",
+     "build",
+     "--config=$CONFIG",
+     "--@rules_rust//:error_format=json",
+     "//pw_kernel/..."
+   ],
+
+--------------
+Build and Test
+--------------
+
+Host
+====
+
+Test
+----
+
+.. code-block:: shell
+
+   bazelisk test --config k_host //pw_kernel/...
+
+QEMU
+====
+
+Test
+----
+
+.. code-block:: shell
+
+   bazelisk test --config k_qemu_lm3s6965evb //pw_kernel/...
+
+Run
+---
+
+^A-x to exit qemu
+
+.. code-block:: shell
+
+   bazelisk run --config k_qemu_lm3s6965evb //pw_kernel/kernel/entry:kernel
+
+RP2350 Target Board
+===================
+
+Build
+-----
+
+.. code-block:: shell
+
+   bazelisk build --config k_rp2350 //pw_kernel/kernel/entry:kernel
+
+Flash
+-----
+
+.. code-block:: shell
+
+   probe-rs download --chip rp2350 bazel-bin/pw_kernel/kernel/entry/kernel && probe-rs reset
diff --git a/pw_kernel/docs.rst b/pw_kernel/docs.rst
@@ -7,3 +7,11 @@ pw_kernel
    :name: pw_kernel
 
 This module contains a highly experimental sandbox for an embedded kernel.
+
+:ref:`module-pw_kernel-cheat-sheet`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   cheat_sheet