Commit graph

30 commits

Author SHA1 Message Date
Sean Anderson
a0abea867a clk: Add driver API to HTML docs
This converts the existing driver API docs (clk-uclass.h) to kernel doc
format and adds them to the HTML documentation. Because the kernel doc
sphinx converter does not handle functions in structs very well, the
individual methods are documented separately. This is primarily inspired by
the phylink documentation [1], which uses this trick extensively.

[1] https://www.kernel.org/doc/html/latest/networking/kapi.html#c.phylink_mac_ops

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Tested-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
Link: https://lore.kernel.org/r/20211222171114.3091780-5-seanga2@gmail.com
2022-02-25 01:41:04 -05:00
Sean Anderson
9c88b13a90 clk: Add client API to HTML docs
This converts the existing client (aka clk.h) documentation to kernel doc
format, and adds it to the HTML docs. I have tried to preserve existing
comments as much as possible, refraining from semantic changes.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Tested-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
Link: https://lore.kernel.org/r/20211222171114.3091780-4-seanga2@gmail.com
[rebased onto u-boot/master and resolved conflicts]
Signed-off-by: Sean Anderson <seanga2@gmail.com>
2022-02-25 01:41:04 -05:00
Patrick Delaunay
5ebb52702e doc: add include/dm/fdtaddr.h to the HTML documentation
Correct Sphinx style comments in include/dm/fdtaddr.h
and add the devfdt API to the HTML documentation;
these functions are NOT compatible with live tree.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
be74f71a67 doc: add include/dm/of*.h to the HTML documentation
Correct Sphinx style comments in include/dm/ofnode.h
and add the device tree node API to the HTML documentation;
the ofnode functions are compatible with Live tree or with flat
device tree.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
6de6a615f8 doc: add include/dm/read.h to the HTML documentation
Correct Sphinx style comments in include/dm/read.h
and add the device read from device tree API to the HTML
documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
494bc8e6f0 doc: add include/dm/devres.h to the HTML documentation
Correct Sphinx style comments in include/dm/devres.h
and add the driver model device resource API, devres_*(),
to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
9fb1c77ef6 doc: add include/dm/device.h to the HTML documentation
Correct Sphinx style comments in include/dm/device.h
and add the driver model device API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
ca4ca43e2f doc: add include/dm/platdata.h to the HTML documentation
Correct Sphinx style comments in include/dm/platdata.h
and add the associated API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
cbb14ac92c doc: add include/dm/lists.h to the HTML documentation
Correct Sphinx style comments in include/dm/lists.h
and add the list API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
0cdd7ded88 doc: add include/dm/root.h to the HTML documentation
Correct Sphinx style comments in include/dm/devres.h
and add the associated driver model API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Patrick Delaunay
797b2a2ed4 doc: add include/dm/uclass.h to the HTML documentation
Correct Sphinx style comments in include/dm/uclass.h
and add the driver model UCLASS API to the HTML documentation.

Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2022-01-15 10:57:21 +01:00
Heinrich Schuchardt
4ad4c2daeb doc: add include/lmb.h to the HTML documentation
Correct Sphinx style comments in include/lmb.h

Add the logical memory block API to the HTML documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Acked-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
2021-11-20 10:53:00 +01:00
Heinrich Schuchardt
1da0b6ab2a doc: add system reset to API documentation
Complete the Sphinx documentation in include/sysreset.h
Add the include to the generated HTML documentation of the U-Boot API.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
2021-10-21 03:46:03 +02:00
Heinrich Schuchardt
a6aaeb2a91 doc: fix doc/develop/logging.rst
Sphinx 3 builds fail due to doc/develop/logging.rst producing duplicate
labels.

Include logging.h only once in the API section and use cross-references for
the enums log_level_t and log_category_t.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2021-01-27 12:52:57 +01:00
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
Heinrich Schuchardt
0ae9bc3c42 doc: add sandbox API
Add sandbox API to generated HTML documentation

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Reviewed-by: Simon Glass <sjg@chromium.org>
2020-11-05 09:11:31 -07:00
Sean Anderson
72eda5074b lib: Add getopt
Some commands can get very unweildy if they have too many positional
arguments. Adding options makes them easier to read, remember, and
understand.

This implementation of getopt has been taken from barebox, which has had
option support for quite a while. I have made a few modifications to their
version, such as the removal of opterr in favor of a separate getopt_silent
function. In addition, I have moved all global variables into struct
getopt_context.

The getopt from barebox also re-orders the arguments passed to it so that
non-options are placed last. This allows users to specify options anywhere.
For example, `ls -l foo/ -R` would be re-ordered to `ls -l -R foo/` as
getopt parsed the options. However, this feature conflicts with the const
argv in cmd_tbl->cmd. This was originally added in 54841ab50c ("Make sure
that argv[] argument pointers are not modified."). The reason stated in
that commit is that hush requires argv to stay unmodified. Has this
situation changed? Barebox also uses hush, and does not have this problem.
Perhaps we could use their fix?

I have assigned maintenance of getopt to Simon Glass, as it is currently
only used by the log command. I would also be fine maintaining it.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
2020-10-30 10:56:11 -04:00
Sean Anderson
aff60aba6c doc: Document timer API
This adds kerneldocs for <timer.h>.

I don't know who should maintain doc/api/timer.rst, since the timer
subsystem seems to be maintained by SoC maintainers. MAINTAINERS is left
un-updated for the moment.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
2020-10-22 09:54:53 -04:00
Sean Anderson
5eee93e5b1 pinctrl: Reformat documentation in dm/pinctrl.h
This normalizes the documentation to conform to kernel-doc style [1]. It
also moves the documentation for pinctrl_ops inline, and adds argument and
return-value documentation. I have kept the usual function style for these
comments. I could not find any existing examples of function documentation
inside structs.

[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html

Signed-off-by: Sean Anderson <seanga2@gmail.com>
Reviewed-by: Simon Glass <sjg@chromium.org>
2020-10-08 11:42:36 -04:00
Heinrich Schuchardt
f2d2b3a11c efi_loader: prepare for read only OP-TEE variables
We currently have two implementations of UEFI variables:

* variables provided via an OP-TEE module
* variables stored in the U-Boot environment

Read only variables are up to now only implemented in the U-Boot
environment implementation.

Provide a common interface for both implementations that allows handling
read-only variables.

As variable access is limited to very few source files put variable
related definitions into new include efi_variable.h instead of efi_loader.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-07-11 23:14:16 +02:00
Heinrich Schuchardt
c7ff87e0ae doc: random number generation
Add random number generation APIs to the HTML documentation.
Fix style issues.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-06-14 21:07:20 +02:00
Heinrich Schuchardt
f39c8454b5 doc: dfu: add DFU to HTML documentation
Add the device firmware update functions to the generated HTML
documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Acked-by: Lukasz Majewski <lukma@denx.de>
2020-05-25 11:54:53 -04:00
Heinrich Schuchardt
de699187b5 doc: add Unicode functions to API description
Add include/charset.h to generated HTML documentation

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-05-09 09:30:28 +02:00
Heinrich Schuchardt
7fec249bb7 efi_selftest: add unit test functions to HTML documentation
Add the UEFI unit test helper functions to the generated HTML
documentation.

Correct some documentation texts in include/efi_selftest.h.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-05-09 09:30:28 +02:00
Heinrich Schuchardt
540faca8a1 efi_loader: function descriptions efi_watchdog.c
Correct function descriptions in efi_watchdog.c.
Add the descriptions to the generated HTML documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-04-16 08:10:02 +02:00
Heinrich Schuchardt
76956556fc efi_loader: function descriptions efi_unicode_collation.c
Correct function descriptions in efi_unicode_collation.c
Add the Unicode collation protocol to the generated HTML documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-04-16 08:10:01 +02:00
Heinrich Schuchardt
71a7de4467 doc/efi: add load file 2 protocol to HTML documentation
The load file 2 protocol can be used by the Linux kernel to load the initial
RAM disk. U-Boot can be configured to provide an implementation.

Add a description to the UEFI overview and document the related functions
in the API section.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-02-28 19:37:14 +01:00
Heinrich Schuchardt
d417b94e57 efi_loader: document functions in efi_rng.c
Add the missing Sphinx documentation.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2020-01-15 00:51:51 +01:00
Heinrich Schuchardt
fe1a81c1a4 doc: UEFI API documentation
Add some more files to the UEFI API documentation.

Correct some Sphinx comments.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2019-09-05 23:18:52 +02:00
Bin Meng
c8fe916c91 doc: Move existing rst files into api sub-directory
Currently the Sphinx doc only contains API descriptions of several
U-Boot subsystems. For future extension, group these existing docs
into an API sub-directory.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>
Reviewed-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
2019-07-24 10:07:24 -04:00