Documentation: Add cavium SoC and mainboard

* Add documentation for CN81XX SoC
* Add documentation for CN81XX EVB SFF mainboard
* Add documentation for BDK
* Add documentation for BOOTROM and BOOTBLOCK behaviour
* Alphabetically sort vendors

Change-Id: Ibfcd42788e31f684baed658dc3c4dfe1b8e4f354
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/27150
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: David Hendricks <david.hendricks@gmail.com>
Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>

12 files changed, 275 insertions, 2 deletions

diff --git a/Documentation/index.md b/Documentation/index.md
index 4ec45508cc..cf22dca28f 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -18,4 +18,5 @@ Contents:
 * [System on Chip-specific documentation](soc/index.md)
 * [Mainboard-specific documentation](mainboard/index.md)
 * [SuperIO-specific documentation](superio/index.md)
+* [Vendorcode-specific documentation](vendorcode/index.md)
 * [Release notes for past releases](releases/index.md)
diff --git a/Documentation/mainboard/cavium/cavium_cn81xx_sff_evb.jpg b/Documentation/mainboard/cavium/cavium_cn81xx_sff_evb.jpg
new file mode 100644
index 0000000000..0afe778cff
--- /dev/null
+++ b/Documentation/mainboard/cavium/cavium_cn81xx_sff_evb.jpg
diff --git a/Documentation/mainboard/cavium/cn8100_sff_evb.md b/Documentation/mainboard/cavium/cn8100_sff_evb.md
new file mode 100644
index 0000000000..b16a8ae19b
--- /dev/null
+++ b/Documentation/mainboard/cavium/cn8100_sff_evb.md
@@ -0,0 +1,76 @@
+# CN81xx Evaluation-board SFF
+
+## Specs
+
+* 3 mini PCIe slots
+* 4 SATA ports
+* one USB3.0 A connector
+* 20Pin JTAG
+* 4 Gigabit Ethernet
+* 2 SFP+ connectors
+* PCIe x4 slot
+* UART over USB
+* eMMC Flash or MicroSD card slot for on-board storage
+* 1 Slot with DDR-4 memory with ECC support
+* SPI flash
+* MMC and uSD-card
+
+## Flashing coreboot
+
+```eval_rst
++---------------------+----------------+
+| Type                | Value          |
++=====================+================+
+| Socketed flash      | no             |
++---------------------+----------------+
+| Model               | Micron 25Q128A |
++---------------------+----------------+
+| Size                | 8 MiB          |
++---------------------+----------------+
+| In circuit flashing | no             |
++---------------------+----------------+
+| Package             | SOIC-8         |
++---------------------+----------------+
+| Write protection    | No             |
++---------------------+----------------+
+| Dual BIOS feature   | No             |
++---------------------+----------------+
+| Internal flashing   | ?              |
++---------------------+----------------+
+```
+
+## Notes about the hardware
+
+1. Cavium connected *GPIO10* to a global reset line.
+   It's unclear which chips are connected, but at least the PHY and SATA chips
+   are connected.
+
+2. The 4 QLMs can be configured using DIP switches (SW1). That means only a
+   subset of of the available connectors is working at time.
+
+3. The boot source can be configure using DIP switches (SW1).
+
+4. The core and system clock frequency can be configured using DIP switches
+   (SW3 / SW2).
+
+5. The JTAG follows Cavium's own protocol. Support for it is missing in
+   OpenOCD. You have to use ARMs official hardware and software.
+
+## Technology
+
+```eval_rst
++---------------+----------------------------------------+
+| SoC           | :doc:`../../soc/cavium/cn81xx/index`   |
++---------------+----------------------------------------+
+| CPU           | Cavium ARMv8-Quadcore `CN81XX`_        |
++---------------+----------------------------------------+
+
+.. _CN81XX: https://www.cavium.com/product-octeon-tx-cn80xx-81xx.html
+
+```
+
+## Picture
+
+![][cn81xx_board]
+
+[cn81xx_board]: cavium_cn81xx_sff_evb.jpg
diff --git a/Documentation/mainboard/index.md b/Documentation/mainboard/index.md
index 23e1ed2d60..198211da03 100644
--- a/Documentation/mainboard/index.md
+++ b/Documentation/mainboard/index.md
@@ -2,10 +2,14 @@
 
 This section contains documentation about coreboot on specific mainboards.
 
-## SiFive
+## Cavium
 
-- [SiFive HiFive Unleashed](sifive/hifive-unleashed.md)
+- [CN81XX EVB SFF](cavium/cn8100_sff_evb.md)
 
 ## HP
 
 - [Compaq 8200 Elite SFF](hp/compaq_8200_sff.md)
+
+## SiFive
+
+- [SiFive HiFive Unleashed](sifive/hifive-unleashed.md)
diff --git a/Documentation/soc/cavium/bootflow.md b/Documentation/soc/cavium/bootflow.md
new file mode 100644
index 0000000000..70bf865447
--- /dev/null
+++ b/Documentation/soc/cavium/bootflow.md
@@ -0,0 +1,19 @@
+# Cavium bootflow
+
+The on-chip **BOOTROM** first sets up the L2 cache and the SPI controller.
+It then reads **CSIB_NBL1FW** and **CLIB_NBL1FW** configuration data to get
+the position of the bootstage in flash. It then loads 192KiB from flash into
+L2 cache to a fixed address. The boot mode is called "Non-Secure-Boot" as
+the signature of the bootstage isn't verified.
+The **BOOTROM** can do AES decryption for obfuscation or verify the signature
+of the bootstage. Both features aren't used and won't be described any further.
+
+* The typical position of bootstage in flash is at address **0x20000**.
+* The entry point in physical DRAM is at address **0x100000**.
+
+## Layout
+
+![Bootflow of Cavium CN8xxx SoCs][cavium_bootflow]
+
+[cavium_bootflow]: cavium_bootflow.png
+
diff --git a/Documentation/soc/cavium/cavium_bootflow.png b/Documentation/soc/cavium/cavium_bootflow.png
new file mode 100644
index 0000000000..1e9017353c
--- /dev/null
+++ b/Documentation/soc/cavium/cavium_bootflow.png
diff --git a/Documentation/soc/cavium/cn81xx/index.md b/Documentation/soc/cavium/cn81xx/index.md
new file mode 100644
index 0000000000..69fe7105ca
--- /dev/null
+++ b/Documentation/soc/cavium/cn81xx/index.md
@@ -0,0 +1,119 @@
+# Cavium CN81xx documentation
+
+## Reference code
+
+```eval_rst
+The Cavium reference code is called `BDK`_ (board development kit) and is part
+of the `Octeon-TX-SDK`_. Parts of the `BDK`_ have been integrated into coreoboot.
+```
+
+## SOC code
+
+The SOC folder contains functions for:
+* TWSI
+* UART
+* TIMER
+* SPI
+* MMU
+* DRAM
+* CLOCK
+* GPIO
+* Secondary CPUs
+* PCI
+
+All other hardware is initilized by the BDK code, which is invoked from
+ramstage.
+
+## Notes about the hardware
+
+Cavium SoC do **not** have embedded SRAM. The **BOOTROM** setups the
+L2 cache and loads 192KiB of firmware starting from 0x20000 to a fixed
+location. It then jumps to the firmware.
+
+```eval_rst
+For more details have a look at `Cavium CN8XXX Bootflow`_.
+```
+
+## CAR setup
+
+For Cache-as-RAM we only need to lock the cachelines which are used by bootblock
+or romstage until DRAM has been set up. At the end of romstage the cachelines
+are unlocked and the contents are flushed to DRAM.
+Locked cachelines are never evicted.
+
+The CAR setup is done in '''bootblock_custom.S''' and thus doesn't use the common
+aarch64 '''bootblock.S''' code.
+
+## DRAM setup
+
+```eval_rst
+The DRAM setup is done by the `BDK`_.
+```
+
+## PCI setup
+
+The PCI setup is done using the MMCONF mechanism.
+Besides configuring device visibility (secure/unsecure) the MSI-X interrupts
+needs to be configured.
+
+## Devicetree patching
+
+The Linux devicetree needs to be patched, depending on the available hardware
+and their configuration. Some values depends on fuses, some on user selectable
+configuration.
+
+The following SoC specific fixes are made:
+
+1. Fix SCLK
+2. Fix UUA refclock
+3. Remove unused PEM entries
+4. Remove unused QLM entries
+5. Set local MAC address
+
+## CN81xx quirks
+
+The CN81xx needs some quirks that are not documented or hidden in the code.
+
+### Violation of PCI spec
+
+**Problem:**
+
+* The PCI device 01:01.0 is disabled, but a multifunction device.
+* The PCI device 01:01.2 - 00:01.7 is enabled and can't be found by the coreboot
+  PCI allocator.
+
+**Solution:**
+
+The PCI Bus 0 and 1 are scanned manually in SOC's PCI code.
+
+
+### Crash accessing SLI memory
+
+**Problem:**
+
+The SLI memory region decodes to attached PCIe devices.
+Accessing the memory region results in 'Data Abort Exception' if the link of the
+PCIe device never had been enabled.
+
+**Solution:**
+
+Enable the PCIe link at least once. (You can disabling the link and the SLI
+memory reads as 0xffffffff.)
+
+
+### RNG Data Abort Exception
+
+**Problem:**
+
+'Data Abort Exception' on accessing the enabled RNG.
+
+**Solution**:
+
+Read the BDK_RNM_CTL_STATUS register at least once after writing it.
+
+
+```eval_rst
+.. _Octeon-TX-SDK: https://github.com/Cavium-Open-Source-Distributions/OCTEON-TX-SDK
+.. _Cavium CN8XXX Bootflow: ../bootflow.html
+.. _BDK: ../../../vendorcode/cavium/bdk.html
+```
diff --git a/Documentation/soc/cavium/index.md b/Documentation/soc/cavium/index.md
new file mode 100644
index 0000000000..5ccb47f611
--- /dev/null
+++ b/Documentation/soc/cavium/index.md
@@ -0,0 +1,8 @@
+# Cavium SOC-specific documentation
+
+This section contains documentation about coreboot on specific Cavium SOCs.
+
+## Platforms
+
+- [CN81xx series](cn81xx/index.md)
+- [CN8xxx bootflow](bootflow.md)
diff --git a/Documentation/soc/index.md b/Documentation/soc/index.md
index ca50dc85fb..04e2b2f2eb 100644
--- a/Documentation/soc/index.md
+++ b/Documentation/soc/index.md
@@ -4,4 +4,5 @@ This section contains documentation about coreboot on specific SOCs.
 
 ## Vendor
 
+- [Cavium](cavium/index.md)
 - [Intel](intel/index.md)
diff --git a/Documentation/vendorcode/cavium/bdk.md b/Documentation/vendorcode/cavium/bdk.md
new file mode 100644
index 0000000000..5763ece254
--- /dev/null
+++ b/Documentation/vendorcode/cavium/bdk.md
@@ -0,0 +1,30 @@
+# Cavium's BDK
+
+## BDK
+A part of Cavium's BDK can be found in '''src/vendorcode/cavium/bdk'''.
+It does the **DRAM init** in romstage and the **PCIe**, **QLM**, **SLI**,
+**PHY**, **BGX**, **SATA** init in ramstage.
+
+## Devicetree
+The BDK does use it's own devicetree, as coreboot's devicetree isn't
+compatible. The devicetree stores key-value pairs (see **bdk-devicetree.h**
+for implementation details), where the key and the value are stored as strings.
+
+The key-value pairs must be advertised in romstage and ramstage using the
+'''bdk_config_set_fdt()''' method.
+
+The tool '''util/cavium/devicetree_convert.py''' can be used to convert a
+devicetree to a key-value array.
+
+## Modifications
+
+* The BDK has been modified to compile under coreboot's toolchain.
+* Removed FDT devicetree support.
+* Dropped files that aren't required for SoC bringup
+* Added Kconfig values for verbose console output
+
+## Debugging
+
+You can enable verbose console output in *menuconfig*:
+
+Go to **Chipset**, **BDK** and enable one or multiple stages.
diff --git a/Documentation/vendorcode/cavium/index.md b/Documentation/vendorcode/cavium/index.md
new file mode 100644
index 0000000000..e06e2ba009
--- /dev/null
+++ b/Documentation/vendorcode/cavium/index.md
@@ -0,0 +1,8 @@
+# Cavium vendorcode-specific documentation
+
+This section contains documentation about coreboot on Cavium specific
+vendorcode.
+
+## Sections
+
+- [BDK](bdk.md)
diff --git a/Documentation/vendorcode/index.md b/Documentation/vendorcode/index.md
new file mode 100644
index 0000000000..3374eafc67
--- /dev/null
+++ b/Documentation/vendorcode/index.md
@@ -0,0 +1,7 @@
+# Vendorcode-specific documentation
+
+This section contains documentation about coreboot on specific vendorcode.
+
+## Vendor
+
+- [Cavium](cavium/index.md)