u-boot.git/doc/api, branch v2023.01-rc2

doc: documentation of EFI driver binding protocol

2022-10-06T20:54:57+00:00

* Convert code comments in include/efi_driver.h to Sphinx style.
* Add include/efi_driver.h to the HTML documentation.

Signed-off-by: Heinrich Schuchardt 
Reviewed-by: Ilias Apalodimas

linker_lists: Rename sections to remove . prefix

2022-06-23T16:58:18+00:00

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 
Reviewed-by: Simon Glass

misc: Add support for nvmem cells

2022-06-08T18:00:22+00:00

This adds support for "nvmem cells" as seen in Linux. The nvmem device
class in Linux is used for various assorted ROMs and EEPROMs. In this
sense, it is similar to UCLASS_MISC, but also includes
UCLASS_I2C_EEPROM, UCLASS_RTC, and UCLASS_MTD. New drivers corresponding
to a Linux-style nvmem device should be implemented as one of the
previously-mentioned uclasses. The nvmem API acts as a compatibility
layer to adapt the (slightly different) APIs of these uclasses. It also
handles the lookup of nvmem cells.

While nvmem devices can be accessed directly, they are most often used
by reading/writing contiguous values called "cells". Cells typically
hold information like calibration, versions, or configuration (such as
mac addresses).

nvmem devices can specify "cells" in their device tree:

	qfprom: eeprom@700000 {
		#address-cells = <1>;
		#size-cells = <1>;
		reg = <0x00700000 0x100000>;

		/* ... */

		tsens_calibration: calib@404 {
			reg = <0x404 0x10>;
		};
	};

which can then be referenced like:

	tsens {
		/* ... */
		nvmem-cells = <&tsens_calibration>;
		nvmem-cell-names = "calibration";
	};

The tsens driver could then read the calibration value like:

	struct nvmem_cell cal_cell;
	u8 cal[16];
	nvmem_cell_get_by_name(dev, "calibration", &cal_cell);
	nvmem_cell_read(&cal_cell, cal, sizeof(cal));

Because nvmem devices are not all of the same uclass, supported uclasses
must register a nvmem_interface struct. This allows CONFIG_NVMEM to be
enabled without depending on specific uclasses. At the moment,
nvmem_interface is very bare-bones, and assumes that no initialization
is necessary. However, this could be amended in the future.

Although I2C_EEPROM and MISC are quite similar (and could likely be
unified), they present different read/write function signatures. To
abstract over this, NVMEM uses the same read/write signature as Linux.
In particular, short read/writes are not allowed, which is allowed by
MISC.

The functionality implemented by nvmem cells is very similar to that
provided by i2c_eeprom_partition. "fixed-partition"s for eeproms does
not seem to have made its way into Linux or into any device tree other
than sandbox. It is possible that with the introduction of this API it
would be possible to remove it.

Signed-off-by: Sean Anderson

doc/efi: add firmware management protocol to the documentation

2022-05-28T08:59:27+00:00

The firmware management protocol can be used to manage device firmware.
U-Boot can be configured to provide an implementation.

Document the related functions in the API section.

Signed-off-by: Vincent Stehlé 
Reviewed-by: Heinrich Schuchardt

clk: Add driver API to HTML docs

2022-02-25T06:41:04+00:00

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 
Tested-by: Heinrich Schuchardt 
Reviewed-by: Simon Glass 
Link: https://lore.kernel.org/r/20211222171114.3091780-5-seanga2@gmail.com

clk: Add client API to HTML docs

2022-02-25T06:41:04+00:00

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 
Tested-by: Heinrich Schuchardt 
Reviewed-by: Simon Glass 
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

doc: add include/dm/fdtaddr.h to the HTML documentation

2022-01-15T09:57:21+00:00

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 
Reviewed-by: Heinrich Schuchardt

doc: add include/dm/of*.h to the HTML documentation

2022-01-15T09:57:21+00:00

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 
Reviewed-by: Heinrich Schuchardt

doc: add include/dm/read.h to the HTML documentation

2022-01-15T09:57:21+00:00

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 
Reviewed-by: Heinrich Schuchardt

doc: add include/dm/devres.h to the HTML documentation

2022-01-15T09:57:21+00:00

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 
Reviewed-by-by: Heinrich Schuchardt