From 273effcd60b50b0c59d255cb6bb8b3e5fa91633a Mon Sep 17 00:00:00 2001
From: Jason Kridner <jkridner@beagleboard.org>
Date: Thu, 30 Nov 2023 22:50:20 -0500
Subject: [PATCH] play: wip kernel development
@dhruva2000 I couldn't take another incomplete article as I've started
so many without finishing them myself. This seemed like an easy one, so
I've started adding some details. Once my local build completes, I'll
add a note of how long it took and add some more details to wrap up
how to boot the new kernel.
---
.../play-kernel-development.rst | 90 ++++++++++++++++---
1 file changed, 80 insertions(+), 10 deletions(-)
diff --git a/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst b/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
index 545fc2a0..ee72dcd2 100644
--- a/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
+++ b/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
@@ -1,7 +1,7 @@
.. _play-kernel-development:
-Introduction
-#############
+Introduction to BeaglePlay Kernel Development
+#############################################
This guide is for all those who want to kick start their kernel development
journey on the TI AM625x SoC Based BeaglePlay.
@@ -19,26 +19,96 @@ It is used by Linux distributions and other projects to build their own kernels.
The tree is also a popular destination for kernel developers who want to
contribute to the kernel.
-Kernel sources can directly be fetched from GIT:
+Kernel sources can directly be fetched using ``git``:
.. code-block:: bash
git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+A big advantage of using ``git`` to fetch the kernel sources is that you'll easily be able to manage your
+changes, keeping track of what you might edit. If you are looking for a quicker way to download a single
+version of the Linux kernel sources to get started, you might consider fetching a "tarball" using ``wget``.
+
+.. code-block:: bash
+
+ wget https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/snapshot/linux-6.6.tar.gz
+ tar xf linux-6.6.tar.gz
+
+.. note::
+
+ While fetching a tarball with ``wget`` might be faster than fetching the full history with ``git``,
+ the ability to track changes with ``git`` is significant.
+
+For more information on using ``git``, see :ref:`beagleboard-git-usage`.
+
Preparing to Build
******************
-.. todo::
- Add Compiler download link and env setup instructions
+These instructions should be valid on any Debian-based system, but were tested on a BeaglePlay itself.
+
+.. code-block:: bash
+
+ sudo apt update
+ sudo apt install fakeroot build-essential libncurses-dev xz-utils libssl-dev flex libelf-dev bison
Configuring the Kernel
**********************
-.. todo::
- Add steps to config kernel for play
+The easiest way to configure the kernel is to start with a configuration known to work. A running BeaglePlay
+is a great source for that configuration, as it gets compiled into the running kernel.
+
+.. note::
+
+ If you don't have a BeaglePlay booted, you can copy a known good kernel configuration from the
+ BeagleBoard.org Linux git repository at https://git.beagleboard.org/beagleboard/linux. On each release
+ branch, the last commit typically contains a ``bb.org_defconfig`` file. For BeaglePlay, you should
+ look for an ``arm64`` branch.
+
+ Example: https://git.beagleboard.org/beagleboard/linux/-/blob/f47f74d11b19d8ae2f146de92c258f40e0930d86/arch/arm64/configs/bb.org_defconfig
+
+Running on a BeaglePlay, you can configure your kernel using ``/proc/config.gz``. You'll also want
+to ``make olddefconfig`` to update your config for the newer kernel. If you want to look at configuration
+options that haven't previously been configured, then use ``make oldconfig`` instead. Once you've
+got an initial configuration, you can edit the configuration various ways including ``make menuconfig``.
+
+.. code-block:: bash
+
+ zcat /proc/config.gz > .config
+ make olddefconfig
+
+Building the Kernel
+*******************
+
+Once you're set on your configuration, you'll want to build the kernel and build any external modules.
+
+.. note::
+
+ Building the kernel on BeaglePlay might take a while.
+
+.. code-block:: bash
+
+ make
+ make modules
+
+Installing and Booting the Kernel
+*********************************
+
+.. important::
+
+ In case your new kernel fails, you'll want to be prepared to either reflash the board
+ or to use a serial cable to halt u-boot and request loading a working kernel still
+ available on the board.
+
+ See :ref:`beagleplay-serial-console` to setup access over the debug serial port.
+
+.. code-block:: bash
+
+ sudo make install modules_install
+
+References
+**********
-Sources
-*******
+For more details on the Linux kernel build system, see `The kernel build system <https://www.kernel.org/doc/html/latest/kbuild/index.html>`_ on kernel.org.
-This documentation is heavily based on the `official TI-SDK documentation for
+For additional guidance, see the `official TI-SDK documentation for
AM62X <https://software-dl.ti.com/processor-sdk-linux/esd/AM62X/08_06_00_42/exports/docs/linux/Foundational_Components_Kernel_Users_Guide.html>`_
--
GitLab