u-boot/doc/api
Simon Glass 0b2fa98aa5 linker_lists: Fix alignment issue
The linker script uses alphabetic sorting to group the different linker
lists together. Each group has its own struct and potentially its own
alignment. But when the linker packs the structs together it cannot ensure
that a linker list starts on the expected alignment boundary.

For example, if the first list has a struct size of 8 and we place 3 of
them in the image, that means that the next struct will start at offset
0x18 from the start of the linker_list section. If the next struct has
a size of 16 then it will start at an 8-byte aligned offset, but not a
16-byte aligned offset.

With sandbox on x86_64, a reference to a linker list item using
ll_entry_get() can force alignment of that particular linker_list item,
if it is in the same file as the linker_list item is declared.

Consider this example, where struct driver is 0x80 bytes:

	ll_entry_declare(struct driver, fred, driver)

...

	void *p = ll_entry_get(struct driver, fred, driver)

If these two lines of code are in the same file, then the entry is forced
to be aligned at the 'struct driver' alignment, which is 16 bytes. If the
second line of code is in a different file, then no action is taken, since
the compiler cannot update the alignment of the linker_list item.

In the first case, an 8-byte 'fill' region is added:

 .u_boot_list_2_driver_2_testbus_drv
                0x0000000000270018       0x80 test/built-in.o
                0x0000000000270018                _u_boot_list_2_driver_2_testbus_drv
 .u_boot_list_2_driver_2_testfdt1_drv
                0x0000000000270098       0x80 test/built-in.o
                0x0000000000270098                _u_boot_list_2_driver_2_testfdt1_drv
 *fill*         0x0000000000270118        0x8
 .u_boot_list_2_driver_2_testfdt_drv
                0x0000000000270120       0x80 test/built-in.o
                0x0000000000270120                _u_boot_list_2_driver_2_testfdt_drv
 .u_boot_list_2_driver_2_testprobe_drv
                0x00000000002701a0       0x80 test/built-in.o
                0x00000000002701a0                _u_boot_list_2_driver_2_testprobe_drv

With this, the linker_list no-longer works since items after testfdt1_drv
are not at the expected address.

Ideally we would have a way to tell gcc not to align structs in this way.
It is not clear how we could do this, and in any case it would require us
to adjust every struct used by the linker_list feature.

One possible fix is to force each separate linker_list to start on the
largest possible boundary that can be required by the compiler. However
that does not seem to work on x86_64, which uses 16-byte alignment in this
case but needs 32-byte alignment.

So add a Kconfig option to handle this. Set the default value to 4 so
as to avoid changing platforms that don't need it.

Update the ll_entry_start() accordingly.

Signed-off-by: Simon Glass <sjg@chromium.org>
2020-12-18 20:32:21 -07:00
..
dfu.rst doc: dfu: add DFU to HTML documentation 2020-05-25 11:54:53 -04:00
efi.rst efi_loader: prepare for read only OP-TEE variables 2020-07-11 23:14:16 +02:00
getopt.rst lib: Add getopt 2020-10-30 10:56:11 -04:00
index.rst doc: add sandbox API 2020-11-05 09:11:31 -07:00
linker_lists.rst linker_lists: Fix alignment issue 2020-12-18 20:32:21 -07:00
pinctrl.rst pinctrl: Reformat documentation in dm/pinctrl.h 2020-10-08 11:42:36 -04:00
rng.rst doc: random number generation 2020-06-14 21:07:20 +02:00
sandbox.rst doc: add sandbox API 2020-11-05 09:11:31 -07:00
serial.rst doc: Move existing rst files into api sub-directory 2019-07-24 10:07:24 -04:00
timer.rst doc: Document timer API 2020-10-22 09:54:53 -04:00
unicode.rst doc: add Unicode functions to API description 2020-05-09 09:30:28 +02:00