dany/u-boot-megous
1
0
Fork 0
mirror of https://xff.cz/git/u-boot/ synced 2025-09-01 08:42:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: Replace DocBook with sphinx-based docs

Browse Source 
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>
This commit is contained in:
Mario Six
2018-07-10 08:40:17 +02:00
committed by Tom Rini
parent 5448ff33f2
commit 78a88f7930
26 changed files with 4392 additions and 2421 deletions
Download Patch File Download Diff File Expand all files Collapse all files

164
include/linker_lists.h
View File

@@ -19,87 +19,6 @@
#if !defined(__ASSEMBLY__)
/**
* A linker list is constructed by grouping together linker input
* sections, each containing one entry of the list. Each input section
* contains a constant initialized variable which holds the entry's
* content. Linker list input sections are constructed from the list
* and entry names, plus a prefix which allows grouping all lists
* together. Assuming _list and _entry are the list and entry names,
* then the corresponding input section name is
*
* .u_boot_list_ + 2_ + @_list + _2_ + @_entry
*
* and the C variable name is
*
* _u_boot_list + _2_ + @_list + _2_ + @_entry
*
* This ensures uniqueness for both input section and C variable name.
*
* Note that the names differ only in the first character, "." for the
* section and "_" for the variable, so that the linker cannot confuse
* section and symbol names. From now on, both names will be referred
* to as
*
* %u_boot_list_ + 2_ + @_list + _2_ + @_entry
*
* Entry variables need never be referred to directly.
*
* The naming scheme for input sections allows grouping all linker lists
* into a single linker output section and grouping all entries for a
* single list.
*
* Note the two '_2_' constant components in the names: their presence
* allows putting a start and end symbols around a list, by mapping
* these symbols to sections names with components "1" (before) and
* "3" (after) instead of "2" (within).
* Start and end symbols for a list can generally be defined as
*
* %u_boot_list_2_ + @_list + _1_...
* %u_boot_list_2_ + @_list + _3_...
*
* Start and end symbols for the whole of the linker lists area can be
* defined as
*
* %u_boot_list_1_...
* %u_boot_list_3_...
*
* Here is an example of the sorted sections which result from a list
* "array" made up of three entries : "first", "second" and "third",
* iterated at least once.
*
* .u_boot_list_2_array_1
* .u_boot_list_2_array_2_first
* .u_boot_list_2_array_2_second
* .u_boot_list_2_array_2_third
* .u_boot_list_2_array_3
*
* If lists must be divided into sublists (e.g. for iterating only on
* part of a list), one can simply give the list a name of the form
* 'outer_2_inner', where 'outer' is the global list name and 'inner'
* is the sub-list name. Iterators for the whole list should use the
* global list name ("outer"); iterators for only a sub-list should use
* the full sub-list name ("outer_2_inner").
*
* Here is an example of the sections generated from a global list
* named "drivers", two sub-lists named "i2c" and "pci", and iterators
* defined for the whole list and each sub-list:
*
* %u_boot_list_2_drivers_1
* %u_boot_list_2_drivers_2_i2c_1
* %u_boot_list_2_drivers_2_i2c_2_first
* %u_boot_list_2_drivers_2_i2c_2_first
* %u_boot_list_2_drivers_2_i2c_2_second
* %u_boot_list_2_drivers_2_i2c_2_third
* %u_boot_list_2_drivers_2_i2c_3
* %u_boot_list_2_drivers_2_pci_1
* %u_boot_list_2_drivers_2_pci_2_first
* %u_boot_list_2_drivers_2_pci_2_second
* %u_boot_list_2_drivers_2_pci_2_third
* %u_boot_list_2_drivers_2_pci_3
* %u_boot_list_2_drivers_3
*/
/**
* llsym() - Access a linker-generated array entry
* @_type: Data type of the entry
@@ -134,16 +53,19 @@
* a subsection of this section is declared and contains some elements,
* it is imperative that the elements are of the same type.
*
* 4) In case an outer section is declared that contains some array elements
* 3) In case an outer section is declared that contains some array elements
* AND an inner subsection of this section is declared and contains some
* elements, then when traversing the outer section, even the elements of
* the inner sections are present in the array.
*
* Example:
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* .x = 3,
* .y = 4,
* };
*
* ::
*
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* .x = 3,
* .y = 4,
* };
*/
#define ll_entry_declare(_type, _name, _list) \
_type _u_boot_list_2_##_list##_2_##_name __aligned(4) \
@@ -160,18 +82,20 @@
* This is like ll_entry_declare() but creates multiple entries. It should
* be assigned to an array.
*
* ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* { .x = 3, .y = 4 },
* { .x = 8, .y = 2 },
* { .x = 1, .y = 7 }
* };
* ::
*
* ll_entry_declare_list(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* { .x = 3, .y = 4 },
* { .x = 8, .y = 2 },
* { .x = 1, .y = 7 }
* };
*/
#define ll_entry_declare_list(_type, _name, _list) \
_type _u_boot_list_2_##_list##_2_##_name[] __aligned(4) \
__attribute__((unused, \
section(".u_boot_list_2_"#_list"_2_"#_name)))
/**
/*
* We need a 0-byte-size type for iterator symbols, and the compiler
* does not allow defining objects of C type 'void'. Using an empty
* struct is allowed by the compiler, but causes gcc versions 4.4 and
@@ -185,7 +109,7 @@
* @_type: Data type of the entry
* @_list: Name of the list in which this entry is placed
*
* This function returns (_type *) pointer to the very first entry of a
* This function returns ``(_type *)`` pointer to the very first entry of a
* linker-generated array placed into subsection of .u_boot_list section
* specified by _list argument.
*
@@ -193,7 +117,10 @@
* must be 2 and its rightmost index must be 1.
*
* Example:
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
*
* ::
*
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
*/
#define ll_entry_start(_type, _list) \
({ \
@@ -208,7 +135,7 @@
* @_list: Name of the list in which this entry is placed
* (with underscores instead of dots)
*
* This function returns (_type *) pointer after the very last entry of
* This function returns ``(_type *)`` pointer after the very last entry of
* a linker-generated array placed into subsection of .u_boot_list
* section specified by _list argument.
*
@@ -216,7 +143,10 @@
* must be 2 and its rightmost index must be 3.
*
* Example:
* struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
*
* ::
*
* struct my_sub_cmd *msc = ll_entry_end(struct my_sub_cmd, cmd_sub);
*/
#define ll_entry_end(_type, _list) \
({ \
@@ -234,11 +164,14 @@
* argument. The result is of an unsigned int type.
*
* Example:
* int i;
* const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
* for (i = 0; i < count; i++, msc++)
* printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
*
* ::
*
* int i;
* const unsigned int count = ll_entry_count(struct my_sub_cmd, cmd_sub);
* struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub);
* for (i = 0; i < count; i++, msc++)
* printf("Entry %i, x=%i y=%i\n", i, msc->x, msc->y);
*/
#define ll_entry_count(_type, _list) \
({ \
@@ -259,12 +192,15 @@
* and it's name.
*
* Example:
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* .x = 3,
* .y = 4,
* };
* ...
* struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
*
* ::
*
* ll_entry_declare(struct my_sub_cmd, my_sub_cmd, cmd_sub) = {
* .x = 3,
* .y = 4,
* };
* ...
* struct my_sub_cmd *c = ll_entry_get(struct my_sub_cmd, my_sub_cmd, cmd_sub);
*/
#define ll_entry_get(_type, _name, _list) \
({ \
@@ -278,14 +214,17 @@
* ll_start() - Point to first entry of first linker-generated array
* @_type: Data type of the entry
*
* This function returns (_type *) pointer to the very first entry of
* This function returns ``(_type *)`` pointer to the very first entry of
* the very first linker-generated array.
*
* Since this macro defines the start of the linker-generated arrays,
* its leftmost index must be 1.
*
* Example:
* struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
*
* ::
*
* struct my_sub_cmd *msc = ll_start(struct my_sub_cmd);
*/
#define ll_start(_type) \
({ \
@@ -298,14 +237,17 @@
* ll_end() - Point after last entry of last linker-generated array
* @_type: Data type of the entry
*
* This function returns (_type *) pointer after the very last entry of
* This function returns ``(_type *)`` pointer after the very last entry of
* the very last linker-generated array.
*
* Since this macro defines the end of the linker-generated arrays,
* its leftmost index must be 3.
*
* Example:
* struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
*
* ::
*
* struct my_sub_cmd *msc = ll_end(struct my_sub_cmd);
*/
#define ll_end(_type) \
({ \