These macros have AFAICT never been used at all. It's also far from
clear what purpose it could serve - for one thing, what _type would
one pass, other than void perhaps? The example using "struct
my_sub_cmd" seems misplaced, as how could one know that the first
linker list consists of those, and moreover, how would one know how
many there are?

The linker list concept is fragile enough on its own, there is no need
to have unused functionality lying around that may or may not bitrot
and certainly will confuse readers of linker_lists.h.

Signed-off-by: Rasmus Villemoes <ravi@prevas.dk>
Reviewed-by: Simon Glass <sjg@chromium.org>

A limitation of most linker_list macros is that they cannot easily be
used in data structures. This is because they include code inside their
expressions.

Provide a way to support this, with new ll_start_decl() and
ll_end_decl() macros.

Signed-off-by: Simon Glass <sjg@chromium.org>

Per the GCC bug listed below, the way we do linker lists is relying on
undefined behavior that seems to work in gcc, but doesn't always work in
clang. Andrew suggests rewriting our start/end macros in a different way
(as implemented here, from what he said in comment 1) to avoid these
problems.

Reported-by: AdityaK <appujee@google.com>
Suggested-by: Andrew Pinski <apinski@marvell.com>
Link: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=108915
Signed-off-by: Tom Rini <trini@konsulko.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Andrew Pinski <apinski@marvell.com>

Rename the sections used to implement linker lists so they begin with
'__u_boot_list' rather than '.u_boot_list'. The double underscore at the
start is still distinct from the single underscore used by the symbol
names.

Having a '.' in the section names conflicts with clang's ASAN
instrumentation which tries to add redzones between the linker list
elements, causing expected accesses to fail. However, clang doesn't try
to add redzones to user sections, which are names with all alphanumeric
and underscore characters.

Signed-off-by: Andrew Scull <ascull@google.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

This commit does the same thing as Linux commit 33def8498fdd.

Use a more generic form for __section that requires quotes to avoid
complications with clang and gcc differences.

Remove the quote operator # from compiler_attributes.h __section macro.

Convert all unquoted __section(foo) uses to quoted __section("foo").
Also convert __attribute__((section("foo"))) uses to __section("foo")
even if the __attribute__ has multiple list entry forms.

Signed-off-by: Marek Behún <marek.behun@nic.cz>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>

Avoid 'make htmldocs' build warnings:

    ./include/linker_lists.h:224: warning:
    Function parameter or member '_type' not described in 'll_entry_ref'
    ./include/linker_lists.h:224: warning:
    Function parameter or member '_name' not described in 'll_entry_ref'
    ./include/linker_lists.h:224: warning:
    Function parameter or member '_list' not described in 'll_entry_ref'

Fixes: 851144350b6f ("linker_lists: Allow use in data structures")
Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>

Add macros which work with instantiated devices and uclasses, as created
at build time by dtoc. Include variants that can be used in data
structures.

These are mostly used by dtoc but it is worth documenting them fully for
the occasional case where they might come up in user code.

Signed-off-by: Simon Glass <sjg@chromium.org>
Signed-off-by: Simon Glass <sjg@chromium.org>

At present linker lists are designed for use in code. They make use of
statements within expressions ({...}), for example.

It is possible to generate a reference to a linker_list entry that can
be used in data structures, where such features are not permitted. It
requires that the reference first be declared as extern. In other
words the existing macro needs to be split into two parts.

Add new macros to support this.

Signed-off-by: Simon Glass <sjg@chromium.org>
Signed-off-by: Simon Glass <sjg@chromium.org>

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>

The Linux kernel moved to sphinx-based documentation and got rid of the
DocBook based documentation quite a while ago. Hence, the DocBook
documentation for U-Boot should be converted as well.

To achieve this, import the necessary files from Linux v4.17, and
convert the current DocBook documentation (three files altogether) to
sphinx/reStructuredText.

For now, all old DocBook documentation was merged into a single
handbook, tentatively named "U-Boot Hacker Manual".

For some source files, the documentation style was changed to comply
with kernel-doc; no functional changes were applied.

Signed-off-by: Mario Six <mario.six@gdsys.cc>