diff --git a/boards/beagleplay/02-quick-start.rst b/boards/beagleplay/02-quick-start.rst
index b346710db5f38d7b07ac637b7c99bf7c0aa87d62..990a37c74d4ab8e95e9b18bfeff40915cf14f305 100644
--- a/boards/beagleplay/02-quick-start.rst
+++ b/boards/beagleplay/02-quick-start.rst
@@ -96,3 +96,5 @@ Demos and Tutorials
* :ref:`beagleplay-oldi`
* :ref:`beagleplay-csi`
* :ref:`beagleplay-zephyr-development`
+* :ref:`play-kernel-development`
+* :ref:`play-understanding-boot`
diff --git a/boards/beagleplay/05-demos.rst b/boards/beagleplay/05-demos.rst
index 948ce50a8536a05e070a58f768fe8b02696cc5af..a4bbe5bd5beb08ad7e3d13191290692eb99b81c0 100644
--- a/boards/beagleplay/05-demos.rst
+++ b/boards/beagleplay/05-demos.rst
@@ -113,13 +113,13 @@ Demos and tutorials
+++
.. admonition:: Complexity level
- intermediate
+ advanced
.. card::
:link: greybus-host
:link-type: ref
- **Bealgplay Greybus Host**
+ **BeaglePlay Greybus Host**
+++
.. admonition:: Complexity level
@@ -143,3 +143,4 @@ Demos and tutorials
demos-and-tutorials/zephyr-cc1352-development
demos-and-tutorials/play-kernel-development
demos-and-tutorials/greybus-host
+ demos-and-tutorials/understanding-boot
diff --git a/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst b/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
index bffd967e1b63852fee02c679c92d6dcb18b7b91f..ef179fdd4f237cd12044f598423279011d2839b0 100644
--- a/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
+++ b/boards/beagleplay/demos-and-tutorials/play-kernel-development.rst
@@ -49,7 +49,7 @@ These instructions should be valid on any Debian-based system, but were tested o
.. code-block:: bash
sudo apt update
- sudo apt install fakeroot build-essential libncurses-dev xz-utils libssl-dev flex libelf-dev bison
+ sudo apt install -y fakeroot build-essential libncurses-dev xz-utils libssl-dev flex libelf-dev bison debhelper
Configuring the Kernel
**********************
@@ -73,6 +73,7 @@ got an initial configuration, you can edit the configuration various ways includ
.. code-block:: bash
+ cd linux-6.6
zcat /proc/config.gz > .config
make olddefconfig
@@ -90,7 +91,8 @@ the signed database images at https://git.kernel.org/pub/scm/linux/kernel/git/sf
Building the Kernel
*******************
-Once you're set on your configuration, you'll want to build the kernel and build any external modules.
+Once you're set on your configuration, you'll want to build the kernel and build any external modules. To
+make things simpler to install, we'll create a Debian package of the kernel.
.. note::
@@ -98,7 +100,8 @@ Once you're set on your configuration, you'll want to build the kernel and build
.. code-block:: bash
- make
+ cd ..
+ make -C ./linux-6.6 -j4 KDEB_PKGVERSION=1xross bindeb-pkg
Installing and Booting the Kernel
*********************************
@@ -113,11 +116,40 @@ Installing and Booting the Kernel
.. code-block:: bash
- sudo make install modules_install
+ sudo dpkg -i linux-image-6.6.0_1xross_arm64.deb linux-libc-dev_1xross_arm64.deb
+ sudo shutdown -r now
+
+As long as the kernel you built has no significant issues, you'll boot back into a
+running system.
+
+If there was a boot or connectivity failure, you can try an alternate connectivity method, such as
+the :ref:`beagleplay-serial-console` or Ethernet, or you can reflash the board and try again from
+a known good kernel source.
+
+For me, the linux-6.6 kernel booted fine, but the beagleplay.local (mDNS/Avahi broadcast) address
+did not show up right away. I was able to find the BeaglePlay hosted WiFi access point, the
+connection to my local WiFi network, connect over Ethernet and connect over USB network. The `/dev/play` directory
+did not exist, but the `/dev/bone` directory did, so this gives me a good starting point for
+generating some patches to update the mainline kernel. :-D
+
+See :ref:`beagleboard-linux-upstream` for more next steps by providing updates you make to the kernel
+to the upstream repository for everyone to benefit and for you to benefit from on future kernel
+versions.
+
+Kernel Debug
+************
+
+Consider reading the kernel documentation
+on `debugging via gdb <https://www.kernel.org/doc/html/latest/dev-tools/gdb-kernel-debugging.html>`_.
+
+Also, consider the the TI Linux Board Porting Series, specifically the module
+on `debugging with JTAG in CCS <https://www.ti.com/video/3874392631001?keyMatch=LINUX%20KERNEL%20DEBUG>`_.
References
**********
+To understand more about booting code on BeaglePlay, see :ref:`play-understanding-boot`.
+
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.
For additional guidance, see the `official TI-SDK documentation for
diff --git a/boards/beagleplay/demos-and-tutorials/understanding-boot.rst b/boards/beagleplay/demos-and-tutorials/understanding-boot.rst
new file mode 100644
index 0000000000000000000000000000000000000000..d141408906a6d5504ee64c1fec0fd926142e169e
--- /dev/null
+++ b/boards/beagleplay/demos-and-tutorials/understanding-boot.rst
@@ -0,0 +1,21 @@
+.. _play-understanding-boot:
+
+Understanding Boot
+##################
+
+There are several phases to BeaglePlay boot. The simplest place to take control of
+the system is using :ref:`play-distro-boot`. It is simplest because it is very generic,
+not at all specific to BeaglePlay or AM62, and was included in the earliest BeagleBoard.org Debian
+images shipping pre-installed in the on-board flash.
+
+Over time, BeaglePlay images will include `SystemReady
+support <https://www.arm.com/architecture/system-architectures/systemready-certification-program>`_ to
+provide for the most generic boot support allowing execution of
+
+.. _play-distro-boot:
+
+Distro Boot
+***********
+
+For some background on distro boot, see `the u-boot documentation on
+distro boot <https://docs.u-boot.org/en/latest/develop/distro.html>`_.
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
index c38cb1543b844f22cd55b090d26aa4a77156dcd3..fbff959823e75cff914607870990150719af2a75 100644
--- a/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
@@ -21,7 +21,7 @@ The gateware project is made up of:
All these files are found in the FPGA-design directory.
-.. figure:: media/gateware-source-dir.png
+.. figure:: media/gateware-source-dir.*
:align: center
@@ -37,7 +37,7 @@ The gateware is organized into 6 components:
- MIPI camera interface
- SYZYGY high speed interface
-.. figure:: media/gateware-components.png
+.. figure:: media/gateware-components.*
:align: center
Gateware Build Options
@@ -47,7 +47,7 @@ Each interface component may have a number of build options. For example, which
supported by the generated gateware.
-.. figure:: media/gateware-cape-options.png
+.. figure:: media/gateware-cape-options.*
:align: center
The name of the directories within the component's directory are the option names passed to the
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
index 601861654618ccb0df0fd8f9c24269600052f086..27d346cf738fbfcf4f0f216f59ea3cc5ea57ffd9 100644
--- a/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
@@ -13,7 +13,7 @@ Gateware Architecture
The diagram below is a simplified overview of the gateware's structure.
-.. figure:: media/Gateware-Flow-simplified-overview.png
+.. figure:: media/Gateware-Flow-simplified-overview.*
:align: center
:alt: BeagleV-Fire Simplified Gateware
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/media/gateware-source-dir.png b/boards/beaglev/fire/demos-and-tutorials/gateware/media/gateware-source-dir.png
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..1058f64ae9d080e65e5c39b01129e44023f709d3 100644
Binary files a/boards/beaglev/fire/demos-and-tutorials/gateware/media/gateware-source-dir.png and b/boards/beaglev/fire/demos-and-tutorials/gateware/media/gateware-source-dir.png differ
diff --git a/boards/capes/cape-interface-spec.rst b/boards/capes/cape-interface-spec.rst
index 2d168cddba9541bb503bbfd207aa864e8b5be06e..5ae81ef62fa47c85a0edff2160f74ed29287b72b 100644
--- a/boards/capes/cape-interface-spec.rst
+++ b/boards/capes/cape-interface-spec.rst
@@ -490,7 +490,7 @@ Cape interface specification provides |I2C| controller device links for userspac
|I2C| overlay example
=====================
-.. code-block:: devicetree
+.. code-block:: dts
:linenos:
:caption: Example device tree overlay to enable I2C driver
:name: bone_cape_spec_i2c_example
@@ -584,7 +584,7 @@ SPI bone bus nodes allow creating compatible overlays for Black, AI and AI-64.
Some boards may implement CS using a GPIO.
-.. code-block:: devicetree
+.. code-block:: dts
:linenos:
:caption: Example device tree overlay to enable SPI driver
:name: bone_cape_spec_spi_example
diff --git a/books/beaglebone-cookbook/02sensors/sensors.rst b/books/beaglebone-cookbook/02sensors/sensors.rst
index 627627e47378ecae531743743da617f2dfb9145b..87515f78c7312c5fec7f4deb82d18a6f3e24b20b 100644
--- a/books/beaglebone-cookbook/02sensors/sensors.rst
+++ b/books/beaglebone-cookbook/02sensors/sensors.rst
@@ -474,7 +474,7 @@ HC-SR04 to the Bone's 5 V power supply.
.. _sensors_hc-sr04_code:
.. literalinclude:: ../code/02sensors/hc-sr04-ultraSonic.js
- :language: JavaScript
+ :language: js
:caption: Driving a HC-SR04 ultrasound sensor (hc-sr04-ultraSonic.js)
:linenos:
@@ -657,7 +657,7 @@ will print the current location every time the GPS outputs it.
.. _digital_GPS_code:
.. literalinclude:: ../code/02sensors/GPS.js
- :language: JavaScript
+ :language: js
:caption: Talking to a GPS with UART 4 (GPS.js)
:linenos:
@@ -885,7 +885,7 @@ using the kernel driver. First you need to install the i2c module.
.. _js_i2ctmp101_code:
.. literalinclude:: ../code/02sensors/i2ctmp101.py
- :language: Python
+ :language: py
:caption: Reading an |I2C| device (i2cTemp.py)
:linenos:
diff --git a/books/beaglebone-cookbook/03displays/displays.rst b/books/beaglebone-cookbook/03displays/displays.rst
index fa160c28589071df7ce0d317dd7ebb7976da03ec..ce99608314e05c03c82cb68c39e426c69342f103 100644
--- a/books/beaglebone-cookbook/03displays/displays.rst
+++ b/books/beaglebone-cookbook/03displays/displays.rst
@@ -382,7 +382,7 @@ LED matrix display (matrixLEDi2c.py)
=====================================
.. literalinclude:: ../code/03displays/matrixLEDi2c.py
- :language: Python
+ :language: py
:caption: LED matrix display (matrixLEDi2c.py)
:linenos:
diff --git a/books/beaglebone-cookbook/04motors/motors.rst b/books/beaglebone-cookbook/04motors/motors.rst
index 37da5e48227c89be0da92e30500c117c00e34ff8..94bd69f1aec2a8b7c70d999b8180f5f19ce10420 100644
--- a/books/beaglebone-cookbook/04motors/motors.rst
+++ b/books/beaglebone-cookbook/04motors/motors.rst
@@ -143,7 +143,7 @@ Combine the code from :ref:`digital_rotaryEncoder_js` and :ref:`motors_servo`.
.. _py_servoEncoder_code:
.. literalinclude:: ../code/04motors/servoEncoder.py
- :language: python
+ :language: py
:caption: Code for driving a servo motor with a rotary encorder(servoEncoder.py)
:linenos:
@@ -264,7 +264,7 @@ motor with a transistor (:ref:`motors_dcMotor_code`). The additional code specif
.. _motors_h-bridge_code:
.. literalinclude:: ../code/04motors/h-bridgeMotor.js
- :language: JavaScript
+ :language: js
:caption: Code for driving a DC motor with an H-bridge (h-bridgeMotor.js)
:linenos:
@@ -305,7 +305,7 @@ Use the code in :ref:`motors_stepperMotor_code_py` to drive the motor.
.. _motors_stepperMotor_code_py:
.. literalinclude:: ../code/04motors/bipolarStepperMotor.py
- :language: Python
+ :language: py
:caption: Driving a bipolar stepper motor (bipolarStepperMotor.py)
:linenos:
diff --git a/books/beaglebone-cookbook/06iot/iot.rst b/books/beaglebone-cookbook/06iot/iot.rst
index 734316c753326c3f7c339f9db689f04e3a2a6adf..fdf32cfa9f5da13fd68427541c5ef482a06d35b9 100644
--- a/books/beaglebone-cookbook/06iot/iot.rst
+++ b/books/beaglebone-cookbook/06iot/iot.rst
@@ -207,7 +207,7 @@ function. Now, let’s create a new Python script. We will name it app1.py:
.. _flask_app1:
.. literalinclude:: ../code/06iot/flask/app1.py
- :language: Python
+ :language: py
:caption: app1.py
:linenos:
@@ -272,7 +272,7 @@ Let’s use a new Python script named *app2.py*.
.. _flask_app2:
.. literalinclude:: ../code/06iot/flask/app2.py
- :language: Python
+ :language: py
:caption: A simple Flask-based web server to read a GPIO (app2.py)
:linenos:
@@ -335,7 +335,7 @@ Create a new Python script and name it *app3.py*.
.. _flask_app3:
.. literalinclude:: ../code/06iot/flask/app3.py
- :language: Python
+ :language: py
:caption: A simple Flask-based web server to read a GPIO (app3.py)
:linenos:
@@ -480,7 +480,7 @@ plots the buffer is **analogInContinuous.py**.
.. _analog_code:
.. literalinclude:: ../code/06iot/analogInContinuous.py
- :language: Python
+ :language: py
:caption: Code to read and plot a continuous analog input(analogInContinuous.py)
:linenos:
@@ -633,7 +633,7 @@ Then add the code in :ref:`networking_nodemailer_code` to a file named ``emailTe
.. _networking_nodemailer_code:
.. literalinclude:: ../code/06iot/emailTest.py
- :language: Python
+ :language: py
:caption: Sending email using nodemailer (emailtTest.py)
:linenos:
@@ -748,7 +748,7 @@ Because your Bone is on the network, it's not hard to access the current weather
.. _networking_weather_code:
.. literalinclude:: ../code/06iot/weather.py
- :language: Python
+ :language: py
:caption: Code for getting current weather conditions (``weather.py``)
:linenos:
@@ -871,7 +871,7 @@ The code in :ref:`networking_pushbutton_code` sends a tweet whenever a button is
.. _networking_pushbutton_code:
.. literalinclude:: ../code/06iot/twitterPushbutton.js
- :language: JavaScript
+ :language: js
:caption: Tweet when a button is pushed (twitterPushbutton.js)
:linenos:
diff --git a/books/beaglebone-cookbook/11misc/misc.rst b/books/beaglebone-cookbook/11misc/misc.rst
index d6c5dce94d4417f736594209d782ee46d4157113..67a6b1f0c7c626abd4f6b6ca4b44be07cec9a48d 100644
--- a/books/beaglebone-cookbook/11misc/misc.rst
+++ b/books/beaglebone-cookbook/11misc/misc.rst
@@ -219,46 +219,60 @@ You can always sudo from debian, but sometimes it's nice to login as root.
Here's how to setup root so you can login from your host without a password.
.. code-block:: bash
-
- host$ ssh bone
+ host$ ssh bone
bone$ sudo -i
-
root@bone# nano /etc/ssh/sshd_config
Search for the line
+.. code-block:: bash
+
#PermitRootLogin prohibit-password
and change it to
+.. code-block:: bash
+
PermitRootLogin yes
(The # symbol indicates a comment and must be removed in order for the setting to take effect.)
Save the file and quit the editor. Restart ssh so it will reread the file.
+.. code-block:: bash
+
root@bone# systemctl restart sshd
And assign a password to root.
+.. code-block:: bash
+
root@bone# passwd
Now open another window on your host computer and enter:
+.. code-block:: bash
+
host$ ssh-copy-id root@bone
and enter the root password. Test it with:
+.. code-block:: bash
+
host$ ssh root@bone
You should be connected without a password.
Now go back to the Bone and turn off the root password access.
+.. code-block:: bash
+
root@bone# nano /etc/ssh/sshd_config
Restore the line:
+.. code-block:: bash
+
#PermitRootLogin prohibit-password
and restart sshd.
@@ -334,7 +348,7 @@ https://serverfault.com/questions/362529/how-can-i-sniff-the-traffic-of-remote-m
First login to the Beagle and install tcpdump. Use your Beagle's
IP address.
-.. code-block::
+.. code-block:: bash
host$ ssh 192.168.7.2
bone$ sudo apt update
@@ -343,7 +357,7 @@ IP address.
Next, create a named pipe and have wireshark read from it.
-.. code-block::
+.. code-block:: bash
host$ mkfifo /tmp/remote
host$ wireshark -k -i /tmp/remote
@@ -755,22 +769,15 @@ Run the following to download and setup Sphinx locally.
bone$ sudo apt upgrade
bone$ sudo apt install -y \
make git wget \
- doxygen graphviz librsvg2-bin\
+ doxygen librsvg2-bin\
texlive-latex-base texlive-latex-extra latexmk texlive-fonts-recommended \
python3 python3-pip \
- python3-sphinx python3-sphinx-rtd-theme python3-sphinxcontrib.svg2pdfconverter \
- python3-pil \
imagemagick-6.q16 librsvg2-bin webp \
texlive-full texlive-latex-extra texlive-fonts-extra \
fonts-freefont-otf fonts-dejavu fonts-dejavu-extra fonts-freefont-ttf
- bone$ python3 -m pip install --upgrade pip
- bone$ pip install -U sphinx_design
- bone$ pip install -U sphinxcontrib-images
- bone$ pip install -U sphinx-serve
-
-These instructions came from `lorforlinux
-<https://beagleboard.slack.com/archives/C8S7EKZC2/p1684940872699269>`_
-on the Beagleboard Slack channel.
+ bone$ ./venv-build-env.sh
+
+In case of any problems, checkout `Beagleboard Forum <https://forum.beagleboard.org/>`_.
Now go to the cloned *docs.beagleboard.io* repository folder and do the following.
To clean build directory:
diff --git a/books/pru-cookbook/05blocks/blocks.rst b/books/pru-cookbook/05blocks/blocks.rst
index d313229cfc17eaf73ea26bab414f171c00c3520a..44674a5e245f4e0578907e9ee6b66d0d0f04aa18 100644
--- a/books/pru-cookbook/05blocks/blocks.rst
+++ b/books/pru-cookbook/05blocks/blocks.rst
@@ -856,6 +856,7 @@ will make the period half as long.
Here's the code (``pwm7.pru0.c``)
.. literalinclude:: ../code/05blocks/pwm7.pru0.c
+ :language: c
:caption: pwm7.pru0.c Using Both PRUs
:linenos:
@@ -1058,6 +1059,7 @@ Configure the pins with ``input_setup.sh``.
The following code reads the input pin and writes its value to the output pin.
.. literalinclude:: ../code/05blocks/input.pru0.c
+ :language: c
:caption: input.pru0.c
:linenos:
diff --git a/conf.py b/conf.py
index 5acdb58f5c162175af2ed3380c2baec1f7b37adc..6c70e08c874116be18a1bb7b700ba7faeb75c078 100644
--- a/conf.py
+++ b/conf.py
@@ -40,6 +40,8 @@ extensions = [
"sphinx.ext.imgconverter",
"sphinx.ext.graphviz",
"sphinx.ext.todo",
+ "sphinx.ext.autodoc",
+ "sphinx.ext.autosummary",
"sphinx_tabs.tabs",
"breathe",
"sphinx_copybutton",
diff --git a/intro/beagle101/blinkLED.rst b/intro/beagle101/blinkLED.rst
index 1d66ddec45b4575021b970778d3284d3151d9e29..662f2cd7b10a0a4aa724c8e9bca22c5fc4721144 100644
--- a/intro/beagle101/blinkLED.rst
+++ b/intro/beagle101/blinkLED.rst
@@ -82,6 +82,7 @@ depends on which Beagle you have. Click on the tab for your board.
Board Power LED
For more details see: :ref:`bbai64-quick-start`
+ For more details see: :ref:`bbai64-quick-start`
.. group-tab:: Play
diff --git a/intro/contribution/git-usage.rst b/intro/contribution/git-usage.rst
index 26f24825b3ea38705d81d113891c25d30ecd4b27..253802adc47173152e2ce4b385e66ec07ef1ac48 100644
--- a/intro/contribution/git-usage.rst
+++ b/intro/contribution/git-usage.rst
@@ -452,7 +452,7 @@ If you later want to remove the reference to this particular branch:
Or, to delete the references to all of Jason's branches:
-.. code-block::
+.. code-block:: bash
git remote rm jkridner
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000000000000000000000000000000000000..767efb557c21b578eddbd908547bc6c7696fe097
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,33 @@
+alabaster==0.7.13
+Babel==2.13.1
+breathe==4.35.0
+certifi==2023.11.17
+charset-normalizer==3.3.2
+docutils==0.18.1
+graphviz==0.20.1
+idna==3.6
+imagesize==1.4.1
+Jinja2==3.1.2
+MarkupSafe==2.1.3
+packaging==23.2
+Pillow==10.1.0
+Pygments==2.17.2
+requests==2.31.0
+setuptools==69.0.2
+snowballstemmer==2.2.0
+Sphinx==7.2.6
+sphinx-copybutton==0.5.2
+sphinx-rtd-theme==2.0.0
+sphinx-serve==1.0.1
+sphinx-tabs==3.4.4
+sphinx_design==0.5.0
+sphinxcontrib-applehelp==1.0.7
+sphinxcontrib-devhelp==1.0.5
+sphinxcontrib-htmlhelp==2.0.4
+sphinxcontrib-images==0.9.4
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.6
+sphinxcontrib-serializinghtml==1.1.9
+sphinxcontrib-svg2pdfconverter==1.2.2
+urllib3==2.1.0
diff --git a/venv-build-env.sh b/venv-build-env.sh
index bcf495a0efcbcca3356069b1caf2b259e6aa189d..5993ce8fe0f73655fd882f6bd5a612b3c5867767 100755
--- a/venv-build-env.sh
+++ b/venv-build-env.sh
@@ -1,11 +1,8 @@
#!/bin/sh
# Source this script like `. ./venv-build-env.sh`
-if [ ! -e ./sphinx-env ]; then
- python3 -m venv sphinx-env
+if [ ! -e ./.venv ]; then
+ python3 -m venv .venv
fi
-source ./sphinx-env/bin/activate
-python3 -m pip install --upgrade pip
-python3 -m pip install sphinx==5.3.0 sphinx-rtd-theme sphinx_design sphinx-tabs sphinxcontrib.svg2pdfconverter sphinx-reredirects
-python3 -m pip install sphinxcontrib-images sphinx-copybutton
-python3 -m pip install breathe exhale
-python3 -m pip install graphviz
+source ./.venv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt