From fa43709b8d7aa30b6d1039dce854c5eea86f122f Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Tue, 8 Aug 2023 16:36:16 -0400 Subject: doc: Begin adding a best practices document for board ports To help guide developers down the right path, begin a document that lists some best practices to follow when creating a new board port. Signed-off-by: Tom Rini Reviewed-by: Simon Glass --- doc/develop/board_best_practices.rst | 26 ++++++++++++++++++++++++++ doc/develop/index.rst | 1 + 2 files changed, 27 insertions(+) create mode 100644 doc/develop/board_best_practices.rst (limited to 'doc/develop') diff --git a/doc/develop/board_best_practices.rst b/doc/develop/board_best_practices.rst new file mode 100644 index 00000000000..f44401eab7d --- /dev/null +++ b/doc/develop/board_best_practices.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0+: + +Best Practices for Board Ports +============================== + +In addition to the regular best practices such as using :doc:`checkpatch` and +following the :doc:`docstyle` and the :doc:`codingstyle` there are some things +which are specific to creating a new board port. + +* Implement :doc:`bootstd` to ensure that most operating systems will be + supported by the platform. + +* The platform defconfig file must be generated via `make savedefconfig`. + +* The Kconfig and Kbuild infrastructure supports using "fragments" that can be + used to apply changes on top of a defconfig file. These can be useful for + many things such as: + + * Supporting different firmware locations (e.g. eMMC, SD, QSPI). + + * Multiple board variants when runtime detection is not desired. + + * Supporting different build types such as production and development. + + Kconfig fragments should reside in the board directory itself rather than in + the top-level `configs/` directory. diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 263d404b4ca..5b230d0321f 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -9,6 +9,7 @@ General .. toctree:: :maxdepth: 1 + board_best_practices codingstyle designprinciples docstyle -- cgit v1.2.3 From d7d78576bbfddd52b258771c9e926bd51b50d91e Mon Sep 17 00:00:00 2001 From: Simon Glass Date: Sun, 30 Jul 2023 11:15:14 -0600 Subject: bootstd: Rename bootdev_setup_sibling_blk() This name is a little confusing since it suggests that it sets up the sibling block device. In fact it sets up a bootdev for it. Rename the function to make this clearer. Signed-off-by: Simon Glass Reviewed-by: Bin Meng Reviewed-by: Mattijs Korpershoek --- doc/develop/bootstd.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst index 7a2a69fdfce..ec313653578 100644 --- a/doc/develop/bootstd.rst +++ b/doc/develop/bootstd.rst @@ -306,7 +306,7 @@ media device:: The bootdev device is typically created automatically in the media uclass' `post_bind()` method by calling `bootdev_setup_for_dev()` or -`bootdev_setup_sibling_blk()`. The code typically something like this:: +`bootdev_setup_for_sibling_blk()`. The code typically something like this:: /* dev is the Ethernet device */ ret = bootdev_setup_for_dev(dev, "eth_bootdev"); @@ -316,7 +316,7 @@ The bootdev device is typically created automatically in the media uclass' or:: /* blk is the block device (child of MMC device) - ret = bootdev_setup_sibling_blk(blk, "mmc_bootdev"); + ret = bootdev_setup_for_sibling_blk(blk, "mmc_bootdev"); if (ret) return log_msg_ret("bootdev", ret); -- cgit v1.2.3 From aab60a51284bce8f21e472d3e8943f76586edf42 Mon Sep 17 00:00:00 2001 From: Puhan Zhou Date: Sun, 13 Aug 2023 13:16:19 +0800 Subject: docs: fix wrong usage of proftool The usage of proftool in docs is incorrect. If proftool is used without '-o' argument, it will show the usage like following $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace >trace.dat Must provide trace data, System.map file and output file Usage: proftool [-cmtv] Change '>' to '-o' to fix it. Signed-off-by: Puhan Zhou Reviewed-by: Simon Glass --- doc/develop/trace.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/trace.rst b/doc/develop/trace.rst index 9bbe1345d2d..546862020b1 100644 --- a/doc/develop/trace.rst +++ b/doc/develop/trace.rst @@ -139,7 +139,7 @@ There is a -f option available to select a function graph: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace >trace.dat + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace -f funcgraph dump-ftrace -o trace.dat Again, you can use kernelshark or trace-cmd to look at the output. In this case you will see the time taken by each function shown against its exit record. @@ -171,7 +171,7 @@ command: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -o trace.fg $ flamegraph.pl trace.fg >trace.svg You can load the .svg file into a viewer. If you use Chrome (and some other @@ -191,7 +191,7 @@ spend in each call stack: .. code-block:: console - $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing >trace.fg + $ ./sandbox/tools/proftool -m sandbox/System.map -t trace dump-flamegraph -f timing -o trace.fg $ flamegraph.pl trace.fg >trace.svg Note that trace collection does slow down execution so the timings will be -- cgit v1.2.3 From 68886a9941557f580fb650f39a76e7416b126534 Mon Sep 17 00:00:00 2001 From: Siddharth Vadapalli Date: Mon, 14 Aug 2023 10:23:48 +0530 Subject: doc: printf() codes: Fix format specifier for unsigned int The format specifier for the "unsigned int" variable is documented as "%d". However, it should be "%u". Thus, fix it. Fixes: f5e9035043fb ("doc: printf() codes") Reported-by: Tom Rini Signed-off-by: Siddharth Vadapalli Reviewed-by: Tom Rini Reviewed-by: Heinrich Schuchardt Signed-off-by: Heinrich Schuchardt --- doc/develop/printf.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/develop') diff --git a/doc/develop/printf.rst b/doc/develop/printf.rst index 7b9aea06876..99d05061b14 100644 --- a/doc/develop/printf.rst +++ b/doc/develop/printf.rst @@ -105,19 +105,19 @@ for the individual integer types. =================== ================== Type Format specifier =================== ================== -bool %d, %x +bool %d, %x char %d, %x unsigned char %u, %x short %d, %x unsigned short %u, %x int %d, %x -unsigned int %d, %x +unsigned int %u, %x long %ld, %lx unsigned long %lu, %lx long long %lld, %llx unsigned long long %llu, %llx off_t %llu, %llx -ptr_diff_t %td, %tx +ptr_diff_t %td, %tx fdt_addr_t %pa, see pointers fdt_size_t %pa, see pointers phys_addr_t %pa, see pointers -- cgit v1.2.3 From 976fb2ffa3875a7bed9866bf5cf939a81c423ef8 Mon Sep 17 00:00:00 2001 From: Tom Rini Date: Mon, 21 Aug 2023 16:19:59 -0400 Subject: Prepare v2023.10-rc3 Signed-off-by: Tom Rini --- doc/develop/release_cycle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/develop') diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst index 752e1304d37..50d33df4211 100644 --- a/doc/develop/release_cycle.rst +++ b/doc/develop/release_cycle.rst @@ -68,7 +68,7 @@ For the next scheduled release, release candidates were made on:: * U-Boot v2023.10-rc2 was released on Mon 07 August 2023. -.. * U-Boot v2023.10-rc3 was released on Mon 21 August 2023. +* U-Boot v2023.10-rc3 was released on Mon 21 August 2023. .. * U-Boot v2023.10-rc4 was released on Mon 04 September 2023. -- cgit v1.2.3