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.3.1 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 --- boot/bootdev-uclass.c | 8 +++++--- common/usb_storage.c | 2 +- doc/develop/bootstd.rst | 4 ++-- drivers/mmc/mmc-uclass.c | 2 +- drivers/nvme/nvme.c | 2 +- drivers/scsi/scsi.c | 2 +- drivers/virtio/virtio-uclass.c | 2 +- include/bootdev.h | 10 +++++----- 8 files changed, 17 insertions(+), 15 deletions(-) (limited to 'doc/develop') diff --git a/boot/bootdev-uclass.c b/boot/bootdev-uclass.c index 3f2c8d7153a..1c16ca1b8d7 100644 --- a/boot/bootdev-uclass.c +++ b/boot/bootdev-uclass.c @@ -262,7 +262,7 @@ static int bootdev_get_suffix_start(struct udevice *dev, const char *suffix) return len; } -int bootdev_setup_sibling_blk(struct udevice *blk, const char *drv_name) +int bootdev_setup_for_sibling_blk(struct udevice *blk, const char *drv_name) { struct udevice *parent, *dev; char dev_name[50]; @@ -305,7 +305,9 @@ int bootdev_get_sibling_blk(struct udevice *dev, struct udevice **blkp) if (device_get_uclass_id(dev) != UCLASS_BOOTDEV) return -EINVAL; - /* This should always work if bootdev_setup_sibling_blk() was used */ + /* + * This should always work if bootdev_setup_for_sibling_blk() was used + */ len = bootdev_get_suffix_start(dev, ".bootdev"); ret = device_find_child_by_namelen(parent, dev->name, len, &blk); if (ret) { @@ -335,7 +337,7 @@ static int bootdev_get_from_blk(struct udevice *blk, struct udevice **bootdevp) if (device_get_uclass_id(blk) != UCLASS_BLK) return -EINVAL; - /* This should always work if bootdev_setup_sibling_blk() was used */ + /* This should always work if bootdev_setup_for_sibling_blk() was used */ len = bootdev_get_suffix_start(blk, ".blk"); snprintf(dev_name, sizeof(dev_name), "%.*s.%s", len, blk->name, "bootdev"); diff --git a/common/usb_storage.c b/common/usb_storage.c index ac642757737..85774220ef2 100644 --- a/common/usb_storage.c +++ b/common/usb_storage.c @@ -246,7 +246,7 @@ static int usb_stor_probe_device(struct usb_device *udev) if (ret) return ret; - ret = bootdev_setup_sibling_blk(dev, "usb_bootdev"); + ret = bootdev_setup_for_sibling_blk(dev, "usb_bootdev"); if (ret) { int ret2; 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); diff --git a/drivers/mmc/mmc-uclass.c b/drivers/mmc/mmc-uclass.c index 01d9b0201f2..0e157672eae 100644 --- a/drivers/mmc/mmc-uclass.c +++ b/drivers/mmc/mmc-uclass.c @@ -421,7 +421,7 @@ int mmc_bind(struct udevice *dev, struct mmc *mmc, const struct mmc_config *cfg) mmc->cfg = cfg; mmc->priv = dev; - ret = bootdev_setup_sibling_blk(bdev, "mmc_bootdev"); + ret = bootdev_setup_for_sibling_blk(bdev, "mmc_bootdev"); if (ret) return log_msg_ret("bootdev", ret); diff --git a/drivers/nvme/nvme.c b/drivers/nvme/nvme.c index a7add66ab4d..20dc910d8a3 100644 --- a/drivers/nvme/nvme.c +++ b/drivers/nvme/nvme.c @@ -910,7 +910,7 @@ int nvme_init(struct udevice *udev) if (ret) goto free_id; - ret = bootdev_setup_sibling_blk(ns_udev, "nvme_bootdev"); + ret = bootdev_setup_for_sibling_blk(ns_udev, "nvme_bootdev"); if (ret) return log_msg_ret("bootdev", ret); diff --git a/drivers/scsi/scsi.c b/drivers/scsi/scsi.c index 6caeb3fcdd0..0a3420b7fbc 100644 --- a/drivers/scsi/scsi.c +++ b/drivers/scsi/scsi.c @@ -607,7 +607,7 @@ static int do_scsi_scan_one(struct udevice *dev, int id, int lun, bool verbose) /* TODO: undo create */ return log_msg_ret("pro", ret); - ret = bootdev_setup_sibling_blk(bdev, "scsi_bootdev"); + ret = bootdev_setup_for_sibling_blk(bdev, "scsi_bootdev"); if (ret) return log_msg_ret("bd", ret); diff --git a/drivers/virtio/virtio-uclass.c b/drivers/virtio/virtio-uclass.c index f2b3ef1d8b9..c5420162735 100644 --- a/drivers/virtio/virtio-uclass.c +++ b/drivers/virtio/virtio-uclass.c @@ -248,7 +248,7 @@ static int virtio_uclass_post_probe(struct udevice *udev) device_set_name_alloced(vdev); if (uc_priv->device == VIRTIO_ID_BLOCK && !IS_ENABLED(CONFIG_SANDBOX)) { - ret = bootdev_setup_sibling_blk(vdev, "virtio_bootdev"); + ret = bootdev_setup_for_sibling_blk(vdev, "virtio_bootdev"); if (ret) return log_msg_ret("bootdev", ret); } diff --git a/include/bootdev.h b/include/bootdev.h index 1533adfe506..848233187f8 100644 --- a/include/bootdev.h +++ b/include/bootdev.h @@ -371,7 +371,7 @@ int bootdev_next_prio(struct bootflow_iter *iter, struct udevice **devp); /** * bootdev_setup_for_dev() - Bind a new bootdev device (deprecated) * - * Please use bootdev_setup_sibling_blk() instead since it supports multiple + * Please use bootdev_setup_for_sibling_blk() instead since it supports multiple * (child) block devices for each media device. * * Creates a bootdev device as a child of @parent. This should be called from @@ -386,7 +386,7 @@ int bootdev_next_prio(struct bootflow_iter *iter, struct udevice **devp); int bootdev_setup_for_dev(struct udevice *parent, const char *drv_name); /** - * bootdev_setup_for_blk() - Bind a new bootdev device for a blk device + * bootdev_setup_for_sibling_blk() - Bind a new bootdev device for a blk device * * Creates a bootdev device as a sibling of @blk. This should be called from * the driver's bind() method or its uclass' post_bind() method, at the same @@ -398,7 +398,7 @@ int bootdev_setup_for_dev(struct udevice *parent, const char *drv_name); * @drv_name: Name of bootdev driver to bind * Return: 0 if OK, -ve on error */ -int bootdev_setup_sibling_blk(struct udevice *blk, const char *drv_name); +int bootdev_setup_for_sibling_blk(struct udevice *blk, const char *drv_name); /** * bootdev_get_sibling_blk() - Locate the block device for a bootdev @@ -428,8 +428,8 @@ static inline int bootdev_setup_for_dev(struct udevice *parent, return 0; } -static inline int bootdev_setup_sibling_blk(struct udevice *blk, - const char *drv_name) +static inline int bootdev_setup_for_sibling_blk(struct udevice *blk, + const char *drv_name) { return 0; } -- cgit v1.3.1 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.3.1 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.3.1 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 --- Makefile | 2 +- doc/develop/release_cycle.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/develop') diff --git a/Makefile b/Makefile index 3954d86a26e..9b90204bfe6 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ VERSION = 2023 PATCHLEVEL = 10 SUBLEVEL = -EXTRAVERSION = -rc2 +EXTRAVERSION = -rc3 NAME = # *DOCUMENTATION* 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.3.1