1# cbfstool: Handling memory mapped boot media 2 3`cbfstool` is a utility used for managing coreboot file system (CBFS) 4components in a ROM image. x86 platforms are special since they have 5the SPI flash boot media memory mapped into host address space at 6runtime. This requires `cbfstool` to deal with two separate address 7spaces for any CBFS components that are eXecute-In-Place (XIP) - one 8is the SPI flash address space and other is the host address space 9where the SPI flash gets mapped. 10 11By default, all x86 platforms map a maximum of 16MiB of SPI flash at 12the top of 4G in host address space. If the flash is greater than 1316MiB, then only the top 16MiB of the flash is mapped in the host 14address space. If the flash is smaller than 16MiB, then the entire SPI 15flash is mapped at the top of 4G and the rest of the space remains 16unused. 17 18In more recent platforms like Tiger Lake (TGL), it is possible to map 19more than 16MiB of SPI flash. Since the host address space has legacy 20fixed device addresses mapped below `4G - 16M`, the SPI flash is split 21into separate windows when being mapped to the host address space. 22Default decode window of maximum 16MiB size still lives just below the 234G boundary. The additional decode window is free to live in any 24available MMIO space that the SoC chooses. 25 26Following diagram shows different combinations of SPI flash being 27mapped into host address space when using multiple windows: 28 29![MMAP window combinations with different flash sizes][mmap_windows] 30 31*(a) SPI flash of size 16MiB (b) SPI flash smaller than 16MiB (c) SPI flash 32of size (16MiB+ext window size) (d) SPI flash smaller than (16MiB+ext 33window size)* 34 35The location of standard decode window is fixed in host address space 36`(4G - 16M) to 4G`. However, the platform is free to choose where the 37extended window lives in the host address space. Since `cbfstool` 38needs to know the exact location of the extended window, it allows the 39platform to pass in two parameters `ext-win-base` and `ext-win-size` 40that provide the base and the size of the extended window in host 41address space. 42 43`cbfstool` creates two memory map windows using the knowledge about the 44standard decode window and the information passed in by the platform 45about the extended decode window. These windows are useful in 46converting addresses from one space to another (flash space and host 47space) when dealing with XIP components. 48 49## Assumptions 50 511. Top 16MiB is still decoded in the fixed decode window just below 4G 52 boundary. 531. Rest of the SPI flash below the top 16MiB is mapped at the top of 54 the extended window. Even though the platform might support a 55 larger extended window, the SPI flash part used by the mainboard 56 might not be large enough to be mapped in the entire window. In 57 such cases, the mapping is assumed to be in the top part of the 58 extended window with the bottom part remaining unused. 59 60## Example 61 62If the platform supports extended window and the SPI flash size is 63greater, then `cbfstool` creates a mapping for the extended window as 64well. 65 66``` 67ext_win_base = 0xF8000000 68ext_win_size = 32 * MiB 69ext_win_limit = ext_win_base + ext_win_size - 1 = 0xF9FFFFFF 70``` 71 72If SPI flash is 32MiB, then top 16MiB is mapped from `0xFF000000 - 730xFFFFFFFF` whereas the bottom 16MiB is mapped from `0xF9000000 - 740xF9FFFFFF`. The extended window `0xF8000000 - 0xF8FFFFFF` remains 75unused. 76 77[mmap_windows]: mmap_windows.svg 78
