drivers/periph/spi: add doc about multiple SPI buses

doc/guides/advanced_tutorials/creating_application.mdx

@@ -5,6 +5,12 @@ description: How to create your own application for RIOT
 
 import FileTree from '@components/FileTree.astro';
 
+:::note
+This is an advanced tutorial, if you are looking for a beginner introduction
+about RIOT applications, take a look at
+[Creating a Project](/c_tutorials/create_project).
+:::
+
 To create your own application you need to create a directory containing one or
 multiple C file(s) with your source code and a Makefile. A template Makefile is
 available in the `dist` folder of the
@@ -188,6 +194,37 @@ ifneq (,$(filter native native32 native64,$(BOARD)))
 endif
 ```
 
+## Modifying Board-Defaults of Peripherals
+
+Sometimes the default configuration of CPU peripherals from the board's
+`periph_conf.h` file does not fit the need of the application. This can be due
+to custom pin mapping or collosions, additional or different controllers
+required, or other reasons.
+
+Usually it is not desirable to modify the default board configuration in the
+RIOT folder, but rather to keep the custom configuration close to the
+application itself.
+Therefore, a custom `periph_conf.h` file can be created in the base directory
+of the application, as shown in the file tree below.
+
+<FileTree>
+- apps
+    - my_app
+        - Makefile
+        - main.c
+        - periph_conf.h
+- RIOT/
+    - boards
+        - specific_board
+            - include
+                - periph_conf.h
+</FileTree>
+
+It is usually a good idea to copy the `periph_conf.h` file from the board you
+are working with as a starting point and then applying the modifications. This
+ensures that all the other peripherals are still working as intended and gives
+you a reliable starting point.
+
 ## Helper Tools
 
 To help you start writing an application within RIOT, the build system provides

doc/guides/c_tutorials/create_project.mdx

@@ -11,9 +11,14 @@ Now that we have played around with the examples and have a basic understanding
 let's create a new project from scratch.
 We will create a simple hello world program that will print "Hello World!" to the console.
 
-Lets start with the basic git setup,
-if you already have a git repository set up,
-you can skip to the next section.
+:::note
+This is a beginner tutorial, if you are looking for more advanced information
+about RIOT applications, take a look at
+[Creating an Application](/advanced_tutorials/creating_application).
+:::
+
+Lets start with the basic git setup, if you already have a git repository set
+up, you can skip to the next section.
 
 ## Step 1: The Basics of Git and Submodules
 

drivers/include/periph/spi.h

@@ -23,7 +23,7 @@
  * `spi_release()` functions.
  *
  * This interface supports both software and hardware chip select lines. This is
- * reflected by the cpi_cs_t type, which overloads the gpio_t type with platform
+ * reflected by the spi_cs_t type, which overloads the gpio_t type with platform
  * specific values for defining platform dependent hardware chip select lines.
  *
  * Some devices have however very uncommon requirements on the usage and the
@@ -46,6 +46,31 @@
  *    configures the bus with specific parameters (clock, mode) for the duration
  *    of that transaction.
  *
+ * # Default Configuration and Dealing with Multiple SPI Buses
+ *
+ * Many advanced microcontrollers feature multiple SPI buses and some devices,
+ * such as the Nordic Semiconductor nRF52 family, even allow arbitrary pin
+ * assignments for the SPI peripherals.
+ *
+ * RIOT boards provide sane defaults for bus and pin assignments on Development
+ * Boards. The first SPI controller `SPI_DEV(0)` is assigned to
+ * the SPI pins marked on the board. Often that corresponds to the
+ * Arduino headers or other manufacturer standardized pinouts.
+ *
+ * If there are additional devices such as a display, flash memory, sensor,
+ * etc. present on the board, a higher number SPI controller will be selected,
+ * e.g. `SPI_DEV(1)` or `SPI_DEV(2)`.
+ * The exact assignment depends on the number of SPI controllers and
+ * organization of peripherals as well as the capabilities of the individual
+ * controller. Some controllers support faster transfer rate or special
+ * operating modes. More details are documented in the
+ * `periph_conf.h` file of the specific board.
+ *
+ * If you wish to modify the default configuration for your application,
+ * take a look at the
+ * [guides page](https://doc.riot-os.org/advanced_tutorials/creating_application/#modifying-board-defaults-of-peripherals)
+ * about creating applications.
+ *
  * # (Low-) Power Implications
  *
  * As SPI buses are shared peripherals and the interfaces implements a