diff --git a/developer_guide.md b/developer_guide.md new file mode 100644 index 0000000..b667098 --- /dev/null +++ b/developer_guide.md @@ -0,0 +1,284 @@ +--- +title: Basebox +nav_order: 12 +--- + +# Developer Guide + +## BISDN Linux build system + +BISDN Linux is based on the [Yocto Buildsystem], using a the [repo tool] for +setting up its source tree. + +For information on how to build BISN Linux, see the [BISDN Linux](https://github.com/bisdn/bisdn-linux#readme) +repository. + +For information on how to work with Yocto, see the [Yocto Documentation](https://docs.yoctoproject.org/4.0.10/). + +## Adding new platform support for ONL supported platforms + +To add support for a plaform, you need add changes to four places: + +* 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 the 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 the platform name according to ONIE, which is used for +identifying the running platform by the installer. + +While at it, also write down the ONIE version, as you will need that information +later. + +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 platform 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). + +Depending on the platform, you may also need to extend [`ONL_MODULE_VENDORS`](https://github.com/bisdn/meta-open-network-linux/blob/main/conf/machine/generic-x86-64.conf#L33), +as some vendors share kernel modules across platforms. + +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. + +The following section will give an overview how to add patches to fix these +issues. + +### 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/// +``` + +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 automatically. + +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 a [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 issues, fix them similarly with appropriate patches. + +It is also a good idea to check the [open pull requests at ONL](https://github.com/opencomputeproject/OpenNetworkLinux/pulls) +for any pending updates or fixes for the platform you want to add. + +### Adding a platform init script + +ONL uses a python 2 based initialization code, but python 2 is EOL, so the +platform init code would need to be updated, or python 2 provided in our images. + +Since shipping python 2 would be potential security issue, and updating the ONL +code for python 3 would be a huge task, we chose to instead rewrite the +individual platform init codes to simple bash scripts. + +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//__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 bus 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 influences the numbers assigned +to the buses. + +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) +``` + +becomes + +``` +create_i2c_dev 'pca9548' 0x77 1 +``` + +For initializing optoe devices, there is the helper `add_port` which can be used +to easily create the device and set its name to port\. + +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 +``` + +Note that the limit in ranges is inclusive in bash, but exclusive in python, so +you need to substract one. + +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/.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 `/.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 licensing 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 +``` + +### Testing the changes + +Once you are done with all steps, you are now ready for testing your changes. +After building an image with your changes, you should be now able to install it +via ONIE. + +Once it successfully installed, check that it works as expected: + +* Does `onlpdump` show all expected information, without any errors? +* Are all port interfaces present? +* Do the port interfaces come up when you connect a cable and set the up? +* Do the port interfaces transmit packets when up? +* Do the port LEDs light up as expected? + +Play around with it, and maybe follow some of the configuration examples in this +documentation. + +### Update the documentation + +To tell the world that the new model is now supported, the documentation needs +to be updated at several places: + +* Add the previously written down ONIE version to the [supported ONIE versions](getting_started/install_onie.md#supported-onie-versions). +* Update the [OF-DPA Table sizes table](platform_configuration/ofdpa_table_sizes.md#resulting-table-sizes) + with the new model. +* Finally, add the switch model to the [List of supported platforms](download_images.md). + +### Create pull requests for your changes + +Finally, after you have verified the new platform works, you are now ready to +create pull requests for your changes. + +Please make sure to mark any dependencies between them, and describe your +changes and testing method/results properly. + +You may need to update the pull requests based on review comments. In this case, +please do not close them and create new ones, but rebase and squash in fixes +into the commits as necessary. + +Note that the documentation changes will likely be merged only when the release +containing the support is released. diff --git a/license.md b/license.md index 8ac8e37..c05d354 100644 --- a/license.md +++ b/license.md @@ -1,6 +1,6 @@ --- title: License -nav_order: 12 +nav_order: 13 has_children: true ---