add a simple description on how to add a new platform

Add a small manual on how to add support for a new platform, under the
assumption that the platform is supported by ONL and SONIC.

Signed-off-by: Jonas Gorski <[email protected]>

developer_guide.md

@@ -0,0 +1,222 @@
+---
+title: Basebox
+nav_order: 12
+---
+
+# Developer Guide
+
+## BISDN Linux build system
+
+See the [BISDN Linux](https://github.com/bisdn/bisdn-linux#readme) repository
+for information on how to build bisdn linux.
+
+## Adding new platform support
+
+To add support for a plaform, there are three places that need to be changed:
+
+* Enable the platform for ONL so its ONL platform support gets built
+* Add a platform init script to platform-onl-init based on the ONL init code
+* Add a configuration file for the installer
+* Add configuration files to ofdpa-platform
+
+### Enabling a platform for ONL
+
+First, you will need to determine the ONIE platform name. To do that, enter the
+ONIE shell, and issue the following command:
+
+```
+onie-sysinfo -p
+```
+
+This will print platform name according to ONIE, which is used for identifying
+the platform in various places.
+
+In the best case, all you then need is to extend [`ONL_PLATFORM_SUPPORT`](https://github.com/bisdn/meta-open-network-linux/blob/main/conf/machine/generic-x86-64.conf#L21) with this ONIE device
+name, and add the platform kernel modules to [`MACHINE_EXTRA_RDEPENDS`](https://github.com/bisdn/meta-open-network-linux/blob/main/conf/machine/generic-x86-64.conf#L35).
+
+More likely you will encounter build issues due to kernel modules written for
+older kernels, or the platform code having issues newer GCC versions complain
+about.
+
+### Patching ONL
+
+Start by checking out [OpenNetworkLinux](github.com/opencomputeproject/OpenNetworkLinux) based on [the revision mentioned in the recipe](https://github.com/bisdn/meta-open-network-linux/blob/main/recipes-extended/onl/onl_git.bb#L11).
+
+Then locate the platform support directory for the platform you want add. You
+can usually find it at
+
+```
+packages/platforms/<vendor>/<arch>/<short-name>
+```
+
+For some of the common issues we [provide coccinelle semantic patches](https://github.com/bisdn/meta-open-network-linux/tree/main/scripts/coccinelle) which can fix up various code issues.
+
+You can apply them via
+
+```
+spatch --sp-file .cocci --in-place --dir packages/platforms/path/to/platform
+```
+
+Then, create a patch for the code changes by first committing them, adding [nice
+commit message](https://www.kernel.org/doc/html/v4.10/process/submitting-patches.html#describe-your-changes) (don't forget to sign them off!), then add them to the ONL recipe,
+like [here](https://github.com/bisdn/meta-open-network-linux/commit/f1546428eac52b2391ad496ffa3f0f71b35863fa).
+
+If you encounter additional issue, fix them similarly with appropriate patches.
+
+### Adding a a platform init script
+
+ONL uses a python2 based initialization code, but python2 is EOL, so the
+platform init code needs to be adapted. We chose to use simple bash scripts for
+that.
+
+The package providing them is [platform-onl-init](https://github.com/bisdn/meta-open-network-linux/tree/main/recipes-core/platform-onl-init), which automatically calls a
+script named after its ONL platform name, which is similar to the above ONIE
+platform name, except it replaces all underscores with dashes.
+
+First, locate the platform init code for your platform. It is usually found at
+
+```
+packages/platforms/path/to/platform/platform-config/r0/src/python/<platform>/__init__.py
+```
+
+Then take the ONL platform init code and transcribe it to bash. There are a few
+things to look out for:
+
+We do not load any of the i2c drivers on x86 platforms automatically, so you
+will need to manually do that in your script. Due to the way the ONL platform
+code works, the load order is important,as it influcenes the numbers assigned
+to the busses.
+
+The most common way for that is to start the code with the following:
+
+```
+# make sure i2c-i801 is present
+modprobe i2c-i801
+wait_for_file /sys/bus/i2c/devices/i2c-0
+
+# load modules
+modprobe i2c-ismt
+```
+
+After that you can add the platform init code following what ONL does.
+
+We do have some [helper functions](https://github.com/bisdn/meta-open-network-linux/blob/main/recipes-core/platform-onl-init/files/platform-onl-init.sh) for reducing the verbosity needed for the
+bash code.
+
+`create_i2c_dev` can be used as replacement for `new_i2c_device`. It takes the
+same arguments. E.g.
+
+```
+self.new_i2c_device('pca9548', 0x77, 1)
+```
+
+then becomes
+
+```
+create_i2c_dev 'pca9548' 0x77 1
+```
+
+For initialzing optoe devices, there is the helper `add_port` which can be used
+to easily create the device and set its name to port\<portnum\>.
+
+E.g.
+
+```
+for port in range(49, 53):
+    self.new_i2c_device('optoe2', 0x50, port-31)
+    subprocess.call('echo port%d > /sys/bus/i2c/devices/%d-0050/port_name' % (port, port-31), shell=True)
+```
+
+can be rewritten as
+
+```
+for port in {49..52}; do
+	add_port 'optoe2' $port $((port - 31))
+done
+```
+
+Be aware that ranges in bash are inclusive for the limit, while they are
+exclusive in python.
+
+As we are adding devices for the (Q)SFP ports, we do not need to pass any
+addresses, as the SFF standards mandate the address to 0xA0 (0x50), so
+`add_port` will automatically use this address.
+
+### Enabling the platform in the installer
+
+The installer needs to know it supports the platform, and needs to know a few
+things about that.
+
+For that you can transcribe the platform information found in ONL at as an
+appropriate configuration file at
+
+```
+packages/platforms/path/to/platform/platform-config/r0/src/lib/<platform-name>.yml
+```
+
+The file should look like this:
+
+```
+######################################################################
+#
+# platform-config for AS5835
+#
+######################################################################
+
+x86-64-accton-as5835-54x-r0:
+
+  grub:
+
+    serial: >-
+      --port=0x3f8
+      --speed=115200
+      --word=8
+      --parity=no
+      --stop=1
+
+    kernel:
+      <<: *kernel-4-14
+
+    args: >-
+      nopat
+      console=ttyS0,115200n8
+      intel_iommu=off
+
+  ##network
+  ##  interfaces:
+  ##    ma1:
+  ##      name: ~
+  ##      syspath: pci0000:00/0000:00:14.0
+```
+
+Using this, create a new file named `platform.conf`in a directory named like the
+ONIE machine name [here](https://github.com/bisdn/meta-switch/tree/main/scripts/installer/machine).
+
+The contents of the platform.conf should look like this:
+
+```
+GRUB_CMDLINE_LINUX="console=tty0 console=ttyS0,115200n8"
+GRUB_SERIAL_COMMAND="serial --port=0x3f8 --speed=115200 --word=8 --parity=no --stop=1"
+EXTRA_CMDLINE_LINUX="nopat intel_iommu=off"
+```
+
+### Adding ASIC configuration to ofdpa-platform
+
+OF-DPA takes its switch configuration from the [ofdpa-platform](https://github.com/bisdn/meta-ofdpa/tree/main/recipes-ofdpa/ofdpa/ofdpa-platform) package. There it
+loads its configuration based on the [ONL platform name](https://github.com/bisdn/meta-ofdpa/tree/main/recipes-ofdpa/ofdpa/ofdpa-platform/platform). See the README.md in the repository for a
+detailed description of its format and expected file names and locations.
+
+For platforms supported by [SONIC](https://github.com/sonic-net/sonic-buildimage/tree/master/device), you may be able to use the configuration from
+there, else you will need to request one from the device manufacturer.
+
+If the device is supported by SONIC, you can use the device's
+`led_proc_init.soc` as `rc.soc`, and `<Device-Name>/<something>.bcm` as
+ `config.bcm`.
+
+Be aware that using also taking over the `custom_led.bin` used by Trident 3
+devices is currently not possible due to unresolved licencing issues, so you
+may need to uncomment the command for loading it in the rc.soc:
+
+```
+# m0 load 0 0x3800 /usr/share/ofdpa/platform/x86-64-accton-as5835-54x-r0/custom_led.bin
+```

license.md

@@ -1,6 +1,6 @@
 ---
 title: License
-nav_order: 12
+nav_order: 13
 has_children: true
 ---