BSP MAC Address Project

The Problem

Although most (if not all) targets which use a pre-bootloader (such as U-Boot) have been set up to persist individual MAC addresses per board, there have still been instances where MAC addresses have been set incorrectly when a target boots.

Ideally, MAC addresses should all be set on each target board such that they are:

• persistent across power cycles
• consistent for U-Boot and bare metal (where both could be used)
• not needed in lwip.config (at least when u-boot is the primary boot path)

See Target-MAC-Address-Problem-Recommendations.odt for the original write-up on the current MAC address problem for BSPs, possible solutions, and initial proposal of recommended paths forward.

Proposed Changes and Path Forward

1. Modify the xilinx-gem driver to use lwip.config ethernet parameter as a fallback (unless FORCEMAC is used). (See PCR 15734)
2. Check all network drivers in use to make sure they have implemented reading from hardware, then checking if any provided MAC address in lwip.config is a fallback or forced address update, before writing to the hardware address register.
3. Confirm that the imx8 family of BSPs no longer requires the MAC address to be set in lwip.config. If not required, update the common BSP User Guide portion to reflect fallback and FORCEMAC usage in lwip.config. Also comment out (or remove) the ethernet parameter line from lwip.config for the imx8 under the fec-andretti network driver. (See PCR 15736)
4. Update the Target Farm wiki to identify which targets (and under what conditions) require a MAC address configuration parameter in lwip.config.
   1. Indicate which targets are bare-metal boot and/or require unique lwip MAC address configuration. Reference the lwIP User Guide and give some example lwip.config content for the target as guidance and a reminder where setting the MAC address may be required.
   2. Indicate which targets have a MAC address set by U-Boot, grub, slimboot, or other pre-deosBoot loader.
   3. Add a reminder that the lwip.config ethernet parameter should act as a fallback unless FORCEMAC (or other parameters for specific drivers) is used to override the U-Boot ethaddr MAC address.
   4. Add a short tutorial for setting or checking U-Boot ethaddr using the serial console. Also add general troubleshooting guidance for using the u-boot console to spot startup issues for any given target. The tutorial should cover how to check tftp symbolic links used, ethaddr and ipaddr checking, and confirmation that tftp loading succeeded.
   5. Update x9 and tftp-update as needed to manage targets with more than one independent accessible processor set, providing automated test access to any specific processor for tftp access. (This might follow the fix implemented for DeosMCP1048-2 with the addition of DeosMCP1048-2b in x9.)
   6. Leverage the staged boot development project:
5. Create a boot data structure with data pointers to be populated by a boot NVM data loader. The data could be made globally visible as needed.
   • This data structure could be a Boot Information Object (BIO), or Platform-specific BIO (PSBIO). The data structure definition is yet to be defined, but should be intended to allow for expansion, possibly by using metadata. String parsing is not preferred, but a key-length-value (KLV) method with enumerated key identifiers could be used to allow for the content to evolve. For always required fields it would be simpler to maintain fixed fields without metadata.
6. Create a board provisioning approach (tools) to store board-specific information in a boot data object in non-volatile memory, accessible in the boot data structure via a pointer, allowing boot to read the stored data without requiring compile-time constants or use of lwip.config.
7. Develop variants of the boot board data loader to allow interaction with the different forms of NVM used by different targets and boards. A tftp loader variant could be used for initial development on reference boards, then replaced with a NVM specific version once the memory type and location is defined for the target.
   • Create a data loader stage component using tftp for all reference BSPs which can get a board-specific binary file containing the assigned MAC address to use on the board. The tftp server would have individual files for each board in this case to preserve the MAC address outside of U-Boot and available directly to deosBoot.
   • Create variants of this data loader boot stage component tailored to read from NVM types (EEPROM, Flash, SATA, SPI, I2C, etc.) Variants for this approach rely on the board provisioning tool for writing unique MAC addresses and other data to individual boards at locations known to the data loader stage. Each variant would be required to have some basic form of driver to interact with the chosen NVM type.
   • Other possible data loader variants could read a stored device tree or access U-Boot environment variables, have reliance on an inetaddr library, or use some other approach yet to be considered.
8. Create a generic inetaddr library for lwip to access. This library would read a specified memory location (RAM or memory-mapped I/O or memory-mapped NVM of some sort).
   • MAC address(es) could be stored in memory-mapped NVM or I/O locations using an emulator, U-Boot, or other means. Or the MAC addresses could be placed in RAM by U-Boot before starting deosBoot.
   • Some targets might require custom inetaddr library development to read stored data (GPIO, SD card, SPI device, I2C device, ...)
     • The custom versions would use other drivers (dynamically loaded?) to read and interpret stored data as MAC addresses.

Using inetaddr

See the lwIP User Guide for information on using inetaddr libraries, and an example version.

Advantages:

• By using an inetaddr shared object, board MAC address(es) can be stored outside of lwip.config and Deos boot. inetaddr would run after the kernel starts, interacting with lwIP.
• A generic inetaddr could be developed for reference boards, and possibly for some bare-metal platforms.
• Custom inetaddr versions would have access to other drivers to read from non-memory-mapped locations.

Process:

1. inetaddr would be added to the image that will be used on a platform, with a platform-specific configuration file indicating the board memory location inetaddr will access to get the board MAC address(es).
2. Either
   • The MAC address(es) to be used by a given board are stored in a memory-mapped non-volatile memory location known to the inetaddr library using a platform specific memory address.
   • Or the MAC addresses are stored in U-Boot environment variables, then U-Boot places the MAC address(es) in a RAM location known to the inetaddr library using a platform specific memory address before starting Deos boot.
3. Boot starts the kernel, then lwip access the inetaddr library to get the board-specific MAC address for the network driver to use.

Platform-Specific Boot Information Object (PSBIO)

The persistent boot data could be stored in the same NVM as the boot executable. This would work for bare metal boot setups since the memory location and sizing, as well as a means to store files to the board, are already established.

• Requirements would have to be established to allow a minimum dedicated NVM space of the maximum expected size of the boot executable in sectors plus the maximum expected number of sectors for PSBIO data storage.
• The First Boot Stage (and possibly others) would need to know the location of the PSBIO data.

For a tftp loaded boot variant, the U-boot tftp load would be addressed to place deosBoot.bin after the PSBIO data.

A proposed layout of a PSBIO, based on a size in sectors (a minimum of one sector, but expandable if needed for small sector sizes). The PSBIO would start with a jump to the first boot stage, allowing the data structure to be placed at the reset vector. The executable boot binary would begin immediately after the PSBIO data, allowing it to be updated independently of the PSBIO.

Staged Boot and Data Loader Variants Concept Sketch

This is a rough UML style sketch of the staged boot approach using the PSBIO (preferred) method, and having variant data loader stages...

Feedback, Questions, Thoughts

Another approach that has come up in BSP Team discussions is to focus on using the inetaddr library approach.

1. Create a generic inetaddr.so which targets would use to read a specified memory location to get the MAC address(es) to use.
   • Custom inetaddr libraries could be created where the memory location is not populated by a preloader (like U-Boot) or a memory mapped storage location.
   • Custom inetaddr versions might need to use drivers to access non-volatile memory (SD card, SPI Flash, I2C device, ...)

Another approach might be to use makeboot extension to prompt for MAC address to insert into bytes at the end of (or other location in) the boot binary.

• This MAC address value would be outside the CRC calculation, allowing it to be customized per board for an otherwise unmodified boot binary file.