Merge branch 'develop' into edit_this_page

Alasdair Allan · web-flow · commit ff94109b1e02 · 2021-08-18T08:34:45.000+01:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,35 +1,23 @@
 # Contributing to Raspberry Pi Documentation
 
-Although you won't be able to directly change documentation on the official repository, you can take a look at all the source files and see how everything is arranged. The sources files and folders follow the hierarchical documentation as found on the Raspberry Pi website.
+The Raspberry Pi Documentation website is built from Asciidoc source using a Jekyll and Python toolchain. The website is automatically deployed to the raspberrypi.org site — pushed to production — using GitHub Actions when a push to the `master` branch occurs.
 
-In order to submit new or corrected documentation, you have to create a GitHub account (if you don't already have one) and **fork** the original repository to your account. You make changes as you see fit, save them in your repository, then make something called a **pull request** to the original Raspberry Pi repository. This pull request (**PR**) then appears in the Raspberry Pi repository where it can be assessed by the maintainers, copy edited, and, if appropriate, merged with the official repository.
+Full instructions for building and running the documentation website locally can be found in the top-level [README.md](README.md) file.
 
-The documentation which appears on the Raspberry Pi website is generated from the GitHub repository, and is updated approximately hourly.
+In order to contribute new or updated documentation, you must first create a GitHub account and fork the original repository to your own account. You can make changes, save them in your repository, then [make a pull request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) against this repository. The pull request will appear [in the repository](https://github.com/raspberrypi/documentation/pulls) where it can be assessed by the maintainers, copy edited, and if appropriate, merged with the official repository.
 
-You will need a GitHub account to perform any of the following operations. 
+**NOTE:** Unless you are opening a pull request which will only make small corrections, for instance to correct a typo, you are more likely to get traction for your changes if you [open an issue](https://github.com/raspberrypi/documentation/issues) first to discuss the proposed changes.
 
-## Forking a repository
+## Type of Content
 
-This is easy. Go to the Raspberry Pi repository, https://github.com/raspberrypi/documentation, and look at the top right of the page. There should be a button labelled **Fork**, which will fork a copy of the repository to your own GitHub account. 
+We welcome contributions from the community, ranging from correcting small typos all the way through to adding entire new sections to the documentation. However going forward we're going to be fairly targetted about what sort of content we add to the documentation. We are looking to keep the repository, and the documentation, focussed on Raspberry Pi-specific things, rather than having generic Linux or computing content.
 
-## Make Changes
+**NOTE:** We are willing to consider toolchain-related contributions, but changes to the toolchain may have knock-on effects in other places so it is possible that apparently benign pull requests that make toolchain changes could be refused for fairly opaque reasons. 
 
-In your own copy of the repo, you can now alter or add files. 
+## Third-Party Services
 
-To edit a file, first find the file in the filename tree, and click on it. This displays the page in fully rendered markup, and on the toolbar at the top of the document (not top of the page) is a small icon of a pencil. This is the edit button. Click on it and the file will appear in the Github editor. You can now edit away to your heart's content. You can click on **Preview changes** to see the fully rendered file with your edits.  
+In general we will not accept content that is specific to an individual third-party service or product. We will also not embed, or add links, to YouTube videos showing tutorials on how to configure your Raspberry Pi.
 
-At the end of the page is a box called **Commit Changes**. You can either commit your changes directly to your own master branch or create a new branch for use as a pull request. Use the master option, as this means you are making changes to your master copy. Using the branch option will create a new branch in your own repository, but that's a little more complicated to deal with so it won't be described here. If you are making a lot of independent changes over time before pushing the changes to Raspberry Pi, you may wish to investigate the branch option. Update the commit title and enter a description of the change at this point. 
-
-Selecting **Commit changes** will make the change to your master branch. You now need to take that change and make a pull request from it.
-
-## Opening a Pull Request
-
-This is pretty easy. Click on the **Pull Requests** tab on the toolbar. Afterwards, there should be a green button just below the toolbar that is labelled **New pull request**. Click it, and a page should appear that asks you to compare changes. This PR page is actually on the Raspberry Pi GitHub page, not the contributor's, because a PR requests the Raspberry Pi repository maintainers to 'pull' from the contributor's repository. The left-hand side should be the `raspberrypi/documentation` repository, and the branch should be the master one. The right-hand side is where the PR is coming from: your GitHub account, and your master branch. Further down the page you should see a list of the commits you want to have in the PR, and, below that, the actual changes. 
-
-If you are happy for the PR to be created, click on **Create pull request**.
-
-And that's it! The Raspberry Pi documentation PR list will now have your entry in it. It will be read, assessed for technical correctness, passed to copy editors for final checking, and finally merged to the main documentation tree.
-
-
-This is a very quick guide to contributing via GitHub, but it will get you started and enable you to make a difference!
+## Licensing 
 
+The documentation is under a [Creative Commons Attribution-Sharealike](https://creativecommons.org/licenses/by-sa/4.0/) (CC BY-SA 4.0) license. By contributing content to this repository you are agreeing to place your contributions under this license.
diff --git a/Gemfile b/Gemfile
@@ -32,4 +32,3 @@ end
 
 # Performance-booster for watching directories on Windows
 gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
-
diff --git a/README.md b/README.md
@@ -105,3 +105,7 @@ To build without an active internet connection, run
 $ OFFLINE_MODE=1 make
 ```
 which will copy the `fonts.html` and `header.html` files from `offline_includes` (instead of downloading them from esi.raspberrypi.org).
+
+## License
+
+The Raspberry Pi documentation is [licensed](https://github.com/raspberrypi/documentation/blob/develop/LICENSE.md) under a Creative Commons Attribution 4.0 International Licence.
diff --git a/documentation/asciidoc/computers/configuration/headless.adoc b/documentation/asciidoc/computers/configuration/headless.adoc
@@ -53,4 +53,4 @@ network={
 
 NOTE: Some older Raspberry Pi boards and some USB wireless dongles do not support 5GHz networks.
 
-NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc#remote-access[remotely accessing] your headless Raspberry Pi. 
+NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc#remote-access[remotely accessing] your headless Raspberry Pi. For headless setup, SSH can be enabled by placing a file named `ssh`, without any extension, onto the boot folder of the SD Card. For more information see the section on xref:remote-access.adoc#ssh[setting up an SSH server].
diff --git a/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc b/documentation/asciidoc/computers/configuration/kernel-command-line-config.adoc
@@ -6,7 +6,7 @@ The Linux kernel accepts a command line of parameters during boot. On the Raspbe
 sudo nano /boot/cmdline.txt
 ----
 
-Note that we have to use `sudo` to edit anything in the boot partition, and that all parameters in `cmdline.txt` must be on the same line (no carriage returns).
+NOTE: We have to use `sudo` to edit anything in the boot partition, and all parameters in `cmdline.txt` must be on the same line (no carriage returns).
 
 The command line that was passed to the kernel at boot time can be displayed using `cat /proc/cmdline`. It will not be exactly the same as that in `cmdline.txt` as the firmware can make changes to it prior to launching the kernel.
 
@@ -68,7 +68,11 @@ Possible options for the display type, the first part of the `video=` entry,  ar
 
 * splash: tells the boot to use a splash screen via the Plymouth module.
 * plymouth.ignore-serial-consoles: normally if the Plymouth module is enabled it will prevent boot messages from appearing on any serial console which may be present. This flag tells Plymouth to ignore all serial consoles, making boot messages visible again, as they would be if Plymouth was not running.
-* dwc_otg.lpm_enable: turns off Link Power Management (LPM) in the dwc_otg driver; the dwc_otg driver is the driver for the USB controller built into the Raspberry Pi.
-* dwc_otg.speed: sets the speed of the USB controller. `dwc_otg.speed=1` will set it to full speed (USB 1.0), which is slower than high speed (USB 2.0). This option should not be set except during troubleshooting of problems with USB devices.
+* dwc_otg.lpm_enable=0: turns off Link Power Management (LPM) in the dwc_otg driver; the dwc_otg driver is the driver for the USB controller built into the processor used on Raspberry Pi computers.
++
+NOTE: On Raspberry Pi 4 this controller is disabled by default, and is only connected to the type C power input jack; the type A USB ports on Pi 4 are driven by a separate USB controller which is not affected by this setting.
+* dwc_otg.speed: sets the speed of the USB controller built into the processor on Raspberry Pi computers. `dwc_otg.speed=1` will set it to full speed (USB 1.0), which is slower than high speed (USB 2.0). This option should not be set except during troubleshooting of problems with USB devices.
++
+NOTE: On Raspberry Pi 4 this controller is disabled by default, and is only connected to the type C power input connector; the type A USB ports on Pi 4 are driven by a separate USB controller which is not affected by this setting.
 * smsc95xx.turbo_mode: enables/disables the wired networking driver turbo mode. `smsc95xx.turbo_mode=N` turns turbo mode off.
 * usbhid.mousepoll: specifies the mouse polling interval. If you have problems with a slow or erratic wireless mouse, setting this to 0 might help: `usbhid.mousepoll=0`.
diff --git a/documentation/asciidoc/computers/linux_kernel/building.adoc b/documentation/asciidoc/computers/linux_kernel/building.adoc
@@ -71,7 +71,7 @@ KERNEL=kernel7
 make bcm2709_defconfig
 ----
 
-For Raspberry Pi 4 default build configuration
+For Raspberry Pi 4 default build configuration (32 bit)
 
 [,bash]
 ----
@@ -80,7 +80,15 @@ KERNEL=kernel7l
 make bcm2711_defconfig
 ----
 
-===== Customising the Kernel version using `LOCALVERSION`
+For Raspberry Pi 4 default build configuration (64 bit)
+[,bash]
+----
+cd linux
+KERNEL=kernel8
+make bcm2711_defconfig
+----
+
+===== Customising the Kernel Version Using `LOCALVERSION`
 
 In addition to your kernel configuration changes, you may wish to adjust the `LOCALVERSION` to ensure your new kernel does not receive the same version string as the upstream kernel. This both clarifies you are running your own kernel in the output of `uname` and ensures existing modules in `/lib/modules` are not overwritten.
 
@@ -94,7 +102,7 @@ You can also change that setting graphically as shown in xref:linux_kernel.adoc#
 
 ==== Building the Kernel
 
-Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Pi model in use:
+Build and install the kernel, modules, and Device Tree blobs; this step can take a *long* time depending on the Pi model in use.  For the 32-bit kernel:
 
 [,bash]
 ----
@@ -106,6 +114,18 @@ sudo cp arch/arm/boot/dts/overlays/README /boot/overlays/
 sudo cp arch/arm/boot/zImage /boot/$KERNEL.img
 ----
 
+For the 64-bit kernel:
+
+[,bash]
+----
+make -j4 Image modules dtbs
+sudo make modules_install
+sudo cp arch/arm64/boot/dts/*.dtb /boot/
+sudo cp arch/arm64/boot/dts/overlays/*.dtb* /boot/overlays/
+sudo cp arch/arm64/boot/dts/overlays/README /boot/overlays/
+sudo cp arch/arm64/boot/zImage /boot/$KERNEL.img
+----
+
 NOTE: On a Raspberry Pi 2/3/4, the `-j4` flag splits the work between all four cores, speeding up compilation significantly.
 
 === Cross-Compiling the Kernel
@@ -115,7 +135,7 @@ also a Debian distribution, it means many aspects are similar, such as the comma
 
 You can either do this using VirtualBox (or VMWare) on Windows, or install it directly onto your computer. For reference, you can follow instructions online http://www.wikihow.com/Install-Ubuntu-on-VirtualBox[at Wikihow].
 
-==== Install required dependencies and toolchain
+==== Install Required Dependencies and Toolchain
 
 To build the sources for cross-compilation, make sure you have the dependencies needed on your machine by executing:
 
@@ -126,21 +146,21 @@ sudo apt install git bc bison flex libssl-dev make libc6-dev libncurses5-dev
 
 If you find you need other things, please submit a pull request to change the documentation.
 
-===== Install the 32-bit toolchain for a 32-bit kernel
+===== Install the 32-bit Toolchain for a 32-bit Kernel
 
 [,bash]
 ----
 sudo apt install crossbuild-essential-armhf
 ----
 
-===== Or, install the 64-bit toolchain for a 64-bit kernel
+===== Install the 64-bit Toolchain for a 64-bit Kernel
 
 [,bash]
 ----
 sudo apt install crossbuild-essential-arm64
 ----
 
-==== Get sources
+==== Get the Kernel Sources
 
 To download the minimal source tree for the current branch, run:
 
@@ -155,7 +175,7 @@ See <<choosing_sources,*Choosing sources*>> above for instructions on how to cho
 
 Enter the following commands to build the sources and Device Tree files:
 
-===== 32-bit configs
+===== 32-bit Configs
 
 For Pi 1, Pi Zero, Pi Zero W, or Compute Module:
 
@@ -184,7 +204,7 @@ KERNEL=kernel7l
 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- bcm2711_defconfig
 ----
 
-===== 64-bit configs
+===== 64-bit Configs
 
 For Pi 3, Pi 3+ or Compute Module 3:
 
@@ -204,18 +224,18 @@ KERNEL=kernel8
 make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcm2711_defconfig
 ----
 
-===== Build with configs
+===== Build with Configs
 
 NOTE: To speed up compilation on multiprocessor systems, and get some improvement on single processor ones, use `-j n`, where n is the number of processors * 1.5. Alternatively, feel free to experiment and see what works!
 
-====== For all 32-bit builds
+====== For all 32-bit Builds
 
 [,bash]
 ----
 make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- zImage modules dtbs
 ----
 
-====== For all 64-bit builds
+====== For all 64-bit Builds
 
 NOTE: Note the difference between Image target between 32 and 64-bit.
 
@@ -224,7 +244,7 @@ NOTE: Note the difference between Image target between 32 and 64-bit.
 make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- Image modules dtbs
 ----
 
-==== Install directly onto the SD card
+==== Install Directly onto the SD Card
 
 Having built the kernel, you need to copy it onto your Raspberry Pi and install the modules; this is best done directly using an SD card reader.
 
diff --git a/documentation/asciidoc/computers/remote-access/secure-shell.adoc b/documentation/asciidoc/computers/remote-access/secure-shell.adoc
@@ -1,5 +1,5 @@
 [[ssh]]
-== Setting up a SSH Server
+== Setting up an SSH Server
 
 You can access the command line of a Raspberry Pi remotely from another computer or device on the same network using Secure Shell (SSH).
 
diff --git a/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc b/documentation/asciidoc/microcontrollers/microcontroller_docs.adoc
@@ -24,4 +24,9 @@ https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-c-sdk.pdf[Raspberry Pi
 
 https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-python-sdk.pdf[Raspberry Pi Pico Python SDK]:: A MicroPython environment for RP2040 microcontrollers
 
-The API level Doxygen documentation for the Raspberry Pi Pico C/C++ SDK is also available https://rptl.io/pico-doxygen[as a micro-site].
+The API level Doxygen documentation for the Raspberry Pi Pico C/C++ SDK is also available https://rptl.io/pico-doxygen[as a micro-site].
+
+[NOTE]
+======
+If you are building applications with the C/C++ SDK and targetting boards other than the Raspberry Pi Pico, you will need to pass `-DPICO_BOARD=boardname` to CMake. Here `boardname` is the name of your board, e.g. for the Adafruit Feather RP2040 you should pass `-DPICO_BOARD=adafruit_feather_rp2040`. See the https://github.com/raspberrypi/pico-sdk/tree/master/src/boards[`boards/` directory] in the Pico SDK, and the https://www.raspberrypi.org/forums/viewtopic.php?f=147&t=304393[forums], for more information.
+======
diff --git a/documentation/asciidoc/microcontrollers/rp2040/rp2040_based_boards.adoc b/documentation/asciidoc/microcontrollers/rp2040/rp2040_based_boards.adoc
@@ -60,3 +60,6 @@ image::images/micromod.jpg[]
 
 https://www.sparkfun.com/products/17720[MicroMod RP2040 Processor]:: The SparkFun MicroMod Pi RP2040 Processor Board is part of SparkFun’s MicroMod modular interface system. The MicroMod M.2 connector makes it a breeze to connect your MicroMod Pi RP2040 Processor with the MicroMod carrier board that gives you the inputs and outputs you need for your project.
 
+=== Other Boards
+
+Discussions around other RP2040-based boards can be found on the https://www.raspberrypi.org/forums/viewforum.php?f=147[forums].
diff --git a/jekyll-assets/_includes/copyright.html b/jekyll-assets/_includes/copyright.html
@@ -1,6 +1,6 @@
 <div class="legal">
   <div class="legal-inner">
-    <p id="copyright">The Raspberry Pi Documentation is Copyright (c) 2012-{{ site.time | date: '%Y' }} Raspberry Pi Trading (Ltd) and is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International</a> (CC BY-SA) Licence.</p>
-    <p id="copyright">Some content originates from the <a href="http://elinux.org/">eLinux wiki</a>, and is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported</a> license.</p>
+    <p id="copyright">The Raspberry Pi Documentation is Copyright (c) 2012-{{ site.time | date: '%Y' }} Raspberry Pi (Trading) Ltd and is licensed under a <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International</a> (CC BY-SA) licence.</p>
+    <p id="copyright">Some content originates from the <a href="http://elinux.org/">eLinux wiki</a>, and is licensed under the <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-ShareAlike 3.0 Unported</a> licence.</p>
   </div>
-</div>
+</div>
diff --git a/jekyll-assets/css/style.css b/jekyll-assets/css/style.css
@@ -253,6 +253,9 @@ ul#tocify-header1 > ul.tocify-subheader {
   font-size: 30px;
   color: var(--pink);
   margin-bottom: 60px;
+  position: relative;
+  margin-left: -1rem;
+  padding-left: 1rem;
 }
 
 #content h2 {
@@ -261,6 +264,9 @@ ul#tocify-header1 > ul.tocify-subheader {
   color: #343434;
   margin-top: 40px;
   margin-bottom: 0px;
+  position: relative;
+  margin-left: -1rem;
+  padding-left: 1rem;
 }
 
 #content h3 {
@@ -269,6 +275,9 @@ ul#tocify-header1 > ul.tocify-subheader {
   color: #343434;
   margin-top: 40px;
   margin-bottom: 15px;
+  position: relative;
+  margin-left: -1rem;
+  padding-left: 1rem;
 }
 
 #content h4 {
@@ -277,11 +286,67 @@ ul#tocify-header1 > ul.tocify-subheader {
   color: #343434;
   margin-top: 40px;
   margin-bottom: 15px;
+  position: relative;
+  margin-left: -1rem;
+  padding-left: 1rem;
 }
 
-#content h4 {
-  margin-top: 40px;
-  margin-bottom: 15px;
+#content h5, 
+#content h6 {
+  position: relative;
+  margin-left: -1rem;
+  padding-left: 1rem;
+}
+
+h1 .anchor, 
+h2 .anchor, 
+h3 .anchor, 
+h4 .anchor, 
+h5 .anchor, 
+h6 .anchor {
+  position: absolute;
+  top: 0px;
+  text-decoration: none;
+  width: 1.75ex;
+  margin-left: -1.5ex;
+  visibility: hidden;
+  font-size: .8em;
+  font-weight: 400;
+  padding-top: .05em;
+}
+
+h1 .anchor, 
+h2 .anchor {
+  top: -5px;
+}
+
+h3 .anchor {
+  top: -3px;
+}
+
+h4 .anchor, 
+h5 .anchor, 
+h6 .anchor {
+  top: -2px;
+}
+
+h1:hover .anchor, 
+h2:hover .anchor, 
+h3:hover .anchor, 
+h4:hover .anchor, 
+h5:hover .anchor, 
+h6:hover .anchor {
+  color: var(--pink);
+  visibility: visible;
+}
+
+h1 .anchor::before, 
+h2 .anchor::before, 
+h3 .anchor::before, 
+h4 .anchor::before, 
+h5 .anchor::before, 
+h6 .anchor::before {
+  content: "\00a7";
 }
 
 #content p {
diff --git a/scripts/create_build_adoc.py b/scripts/create_build_adoc.py
@@ -60,6 +60,7 @@
 :includedir: {}
 :doctitle: {}
 :page-sub_title: {}
+:sectanchors:
 
 {}
 """.format(output_subdir, build_dir, '{} - {}'.format(site_config['title'], index_title), index_title, new_contents))

Original file line number	Diff line number	Diff line change
`@@ -32,4 +32,3 @@ end`
`32`	`32`
`33`	`33`	`# Performance-booster for watching directories on Windows`
`34`	`34`	`gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?`
`35`		`-`
Original file line number	Diff line number	Diff line change
`@@ -53,4 +53,4 @@ network={`
`53`	`53`
`54`	`54`	`NOTE: Some older Raspberry Pi boards and some USB wireless dongles do not support 5GHz networks.`
`55`	`55`
`56`		`-NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc#remote-access[remotely accessing] your headless Raspberry Pi.`
	`56`	+NOTE: With no keyboard or monitor, you will need some way of xref:remote-access.adoc#remote-access[remotely accessing] your headless Raspberry Pi. For headless setup, SSH can be enabled by placing a file named `ssh`, without any extension, onto the boot folder of the SD Card. For more information see the section on xref:remote-access.adoc#ssh[setting up an SSH server].