Pull request for efi-2022-04-rc1

Documentation:
 
 * Fix building HTML documentation of readthedocs.io
 * Add ARM Juno board documentation
 * Build requirements for Alpine Linux
 * Include DM headers in API documentation
 
 UEFI:
 
 * Fix section alignment of EFI binaries
 * Fix header length of RISC-V EFI binaries allowing to run them on EDK II
 * Remove kaslr-seed from device tree if the EFI_RNG_PROTOCOL is provided
 
 Other:
 
 * Let 'part list' show all 128 GPT partitions
 -----BEGIN PGP SIGNATURE-----
 
 iQIzBAABCAAdFiEEbcT5xx8ppvoGt20zxIHbvCwFGsQFAmHiqKYACgkQxIHbvCwF
 GsTrMA//XQRIS9f8pD3/FsSfVfmtxkCLG9axEe/lRQp7l7109v+m832CJV5Em7pX
 GtRGOSUdj930v1q9fZ/nUx9/IJjf/lnB0eEcMcVai2NVgyuRohGAzX9JWsVLbdOE
 MicDX7D/VZ+86lPxLRJbq61jMj7Dnj+atonJQ3Bc1eBLutUaBOr6aenA99TyLavU
 +guuQmQLpJz6VbyZIYxr7/CZVaVkXS0jmcfEoDHD8BrsBe3pZvNuUC4D9KIFWnLo
 pQYYNuIWiVCPGE/iMbUZGjJfgHnD3qW1DWOfmeWPTysALnTSxx0m8FJrOqlxZk6R
 HkEhcr/RkI2JT89C+07qsXkfvJ7YBg3r6bSNtng4i8VwSm384ffF9Y+cfoBv1285
 7wo+Vbh6LuOlp0OAo3bjAuhW7gpnUkkGoc4sXv7wr560mGOtJAPrp0T1ku17ZANd
 GP0T4TgvL15PAFbK+Yg6NxF+l26Lb5EkvC5bGFlM/5ceafD/B7qA2m8KG9+cR2/t
 UFAyI0FB3yWp1TLfdCRXR4YEHDl3nWjs8GuwdwTPFXLWFPkf73DX/r+ZAnZAY+M+
 FTGJuMZUp71aiqeAs7CHw4ePZMQCt0Hjs9kYbAMekoUncpMCFXwXmp1KxLkHBM+X
 +i6WPflTL/sOSO+3M8fcUeZI7IWerOHZqCu/RTb9W0n3Ee+odBc=
 =NZ+6
 -----END PGP SIGNATURE-----

Merge tag 'efi-2022-04-rc1' of https://source.denx.de/u-boot/custodians/u-boot-efi

Pull request for efi-2022-04-rc1

Documentation:

* Fix building HTML documentation of readthedocs.io
* Add ARM Juno board documentation
* Build requirements for Alpine Linux
* Include DM headers in API documentation

UEFI:

* Fix section alignment of EFI binaries
* Fix header length of RISC-V EFI binaries allowing to run them on EDK II
* Remove kaslr-seed from device tree if the EFI_RNG_PROTOCOL is provided

Other:

* Let 'part list' show all 128 GPT partitions

.readthedocs.yml

@@ -5,6 +5,13 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-20.04"
+  apt_packages:
+    - python3-six
+  tools:
+    python: "3.9"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: doc/conf.py
@@ -12,8 +19,6 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []
 
-# Optionally set the version of Python and requirements required to build your docs
+python:
-# python:
+  install:
-#   version: 3.7
+    - requirements: doc/sphinx/requirements.txt
-#   install:
-#     - requirements: docs/requirements.txt

MAINTAINERS

@@ -737,7 +737,6 @@ F:	test/dm/efi_media.c
 
 EFI PAYLOAD
 M:	Heinrich Schuchardt <xypron.glpk@gmx.de>
-R:	Alexander Graf <agraf@csgraf.de>
 S:	Maintained
 T:	git https://source.denx.de/u-boot/custodians/u-boot-efi.git
 F:	doc/api/efi.rst

Makefile

@@ -1781,9 +1781,9 @@ else
 quiet_cmd_u-boot__ ?= LD      $@
       cmd_u-boot__ ?= $(LD) $(KBUILD_LDFLAGS) $(LDFLAGS_u-boot) -o $@		\
 		-T u-boot.lds $(u-boot-init)					\
-		$(if $(CONFIG_EFI_APP_64BIT),,--whole-archive)			\
+		--whole-archive							\
 			$(u-boot-main)						\
-		$(if $(CONFIG_EFI_APP_64BIT),,--no-whole-archive)		\
+		--no-whole-archive						\
 		$(PLATFORM_LIBS) -Map u-boot.map;				\
 		$(if $(ARCH_POSTLINK), $(MAKE) -f $(ARCH_POSTLINK) $@, true)
 endif

arch/arm/lib/crt0_aarch64_efi.S

@@ -47,8 +47,8 @@ optional_header:
 
 extra_header_fields:
 	.quad	0				/* ImageBase */
-	.long	0x20				/* SectionAlignment */
+	.long	0x200				/* SectionAlignment */
-	.long	0x8				/* FileAlignment */
+	.long	0x200				/* FileAlignment */
 	.short	0				/* MajorOperatingSystemVersion */
 	.short	0				/* MinorOperatingSystemVersion */
 	.short	0				/* MajorImageVersion */
@@ -117,6 +117,7 @@ section_table:
 	.short	0		/* NumberOfLineNumbers  (0 for executables) */
 	.long	0xe0500020	/* Characteristics (section flags) */
 
+	.align		9
 _start:
 	stp		x29, x30, [sp, #-32]!
 	mov		x29, sp

arch/arm/lib/crt0_arm_efi.S

@@ -47,8 +47,8 @@ optional_header:
 
 extra_header_fields:
 	.long	0				/* image_base */
-	.long	0x20				/* SectionAlignment */
+	.long	0x200				/* SectionAlignment */
-	.long	0x8				/* FileAlignment */
+	.long	0x200				/* FileAlignment */
 	.short	0				/* MajorOperatingSystemVersion */
 	.short	0				/* MinorOperatingSystemVersion */
 	.short	0				/* MajorImageVersion */
@@ -115,6 +115,7 @@ section_table:
 	.short	0		/* NumberOfLineNumbers  (0 for executables) */
 	.long	0xe0500020	/* Characteristics (section flags) */
 
+	.align		9
 _start:
 	stmfd		sp!, {r0-r2, lr}
 

arch/arm/lib/elf_aarch64_efi.lds

@@ -18,7 +18,7 @@ SECTIONS
 		*(.gnu.linkonce.t.*)
 		*(.srodata)
 		*(.rodata*)
-		. = ALIGN(16);
+		. = ALIGN(512);
 	}
 	_etext = .;
 	_text_size = . - _text;
@@ -44,7 +44,7 @@ SECTIONS
 		*(.bss)
 		*(.bss.*)
 		*(COMMON)
-		. = ALIGN(16);
+		. = ALIGN(512);
 		_bss_end = .;
 		_edata = .;
 	}

arch/arm/lib/elf_arm_efi.lds

@@ -18,7 +18,7 @@ SECTIONS
 		*(.gnu.linkonce.t.*)
 		*(.srodata)
 		*(.rodata*)
-		. = ALIGN(16);
+		. = ALIGN(512);
 	}
 	_etext = .;
 	_text_size = . - _text;
@@ -44,7 +44,7 @@ SECTIONS
 		*(.bss)
 		*(.bss.*)
 		*(COMMON)
-		. = ALIGN(16);
+		. = ALIGN(512);
 		_bss_end = .;
 		_edata = .;
 	}

arch/riscv/lib/crt0_riscv_efi.S

@@ -71,8 +71,8 @@ extra_header_fields:
 #else
 	.quad	0				/* ImageBase */
 #endif
-	.long	0x20				/* SectionAlignment */
+	.long	0x200				/* SectionAlignment */
-	.long	0x8				/* FileAlignment */
+	.long	0x200				/* FileAlignment */
 	.short	0				/* MajorOperatingSystemVersion */
 	.short	0				/* MinorOperatingSystemVersion */
 	.short	1				/* MajorImageVersion */
@@ -110,16 +110,6 @@ extra_header_fields:
 	.quad	0				/* ExceptionTable */
 	.quad	0				/* CertificationTable */
 	.quad	0				/* BaseRelocationTable */
-	.quad	0				/* Debug */
-	.quad	0				/* Architecture */
-	.quad	0				/* Global Ptr */
-	.quad	0				/* TLS Table */
-	.quad	0				/* Load Config Table */
-	.quad	0				/* Bound Import */
-	.quad	0				/* IAT */
-	.quad	0				/* Delay Import Descriptor */
-	.quad	0				/* CLR Runtime Header */
-	.quad	0				/* Reserved */
 
 	/* Section table */
 section_table:
@@ -158,6 +148,7 @@ section_table:
 	.short	0		/* NumberOfLineNumbers  (0 for executables) */
 	.long	0xe0500020	/* Characteristics (section flags) */
 
+	.align	9
 _start:
 	addi		sp, sp, -(SIZE_LONG * 3)
 	SAVE_LONG(a0, 0)

arch/riscv/lib/elf_riscv32_efi.lds

@@ -20,7 +20,7 @@ SECTIONS
 		*(.gnu.linkonce.t.*)
 		*(.srodata)
 		*(.rodata*)
-		. = ALIGN(16);
+		. = ALIGN(512);
 	}
 	_etext = .;
 	_text_size = . - _text;
@@ -46,7 +46,7 @@ SECTIONS
 		*(.bss)
 		*(.bss.*)
 		*(COMMON)
-		. = ALIGN(16);
+		. = ALIGN(512);
 		_bss_end = .;
 		_edata = .;
 	}

arch/riscv/lib/elf_riscv64_efi.lds

@@ -20,7 +20,7 @@ SECTIONS
 		*(.gnu.linkonce.t.*)
 		*(.srodata)
 		*(.rodata*)
-		. = ALIGN(16);
+		. = ALIGN(512);
 	}
 	_etext = .;
 	_text_size = . - _text;
@@ -46,7 +46,7 @@ SECTIONS
 		*(.bss)
 		*(.bss.*)
 		*(COMMON)
-		. = ALIGN(16);
+		. = ALIGN(512);
 		_bss_end = .;
 		_edata = .;
 	}

arch/x86/config.mk

@@ -20,6 +20,11 @@ IS_32BIT := y
 endif
 endif
 
+EFI_IS_32BIT := $(IS_32BIT)
+ifdef CONFIG_EFI_STUB_64BIT
+EFI_IS_32BIT :=
+endif
+
 ifeq ($(IS_32BIT),y)
 PLATFORM_CPPFLAGS += -march=i386 -m32
 else
@@ -44,8 +49,14 @@ CFLAGS_EFI := -fpic -fshort-wchar
 # Compiler flags to be removed when building UEFI applications
 CFLAGS_NON_EFI := -mregparm=3 -fstack-protector-strong
 
-ifeq ($(CONFIG_EFI_STUB_64BIT),)
+ifeq ($(IS_32BIT),y)
+EFIPAYLOAD_BFDARCH = i386
+else
 CFLAGS_EFI += $(call cc-option, -mno-red-zone)
+EFIPAYLOAD_BFDARCH = x86_64
+endif
+
+ifeq ($(EFI_IS_32BIT),y)
 EFIARCH = ia32
 EFIPAYLOAD_BFDTARGET = elf32-i386
 else
@@ -53,8 +64,6 @@ EFIARCH = x86_64
 EFIPAYLOAD_BFDTARGET = elf64-x86-64
 endif
 
-EFIPAYLOAD_BFDARCH = i386
-
 LDSCRIPT_EFI := $(srctree)/arch/x86/lib/elf_$(EFIARCH)_efi.lds
 EFISTUB := crt0_$(EFIARCH)_efi.o reloc_$(EFIARCH)_efi.o
 OBJCOPYFLAGS_EFI += --target=efi-app-$(EFIARCH)

arch/x86/cpu/config.mk

@@ -9,7 +9,7 @@ LDPPFLAGS += -DRESET_VEC_LOC=$(CONFIG_RESET_VEC_LOC)
 LDPPFLAGS += -DSTART_16=$(CONFIG_SYS_X86_START16)
 
 ifdef CONFIG_X86_64
-ifndef CONFIG_SPL_BUILD
+ifeq ($(CONFIG_SPL_BUILD)$(CONFIG_EFI_APP),)
 LDSCRIPT = $(srctree)/arch/x86/cpu/u-boot-64.lds
 endif
 endif

arch/x86/cpu/efi/payload.c

@@ -51,7 +51,7 @@ ulong board_get_usable_ram_top(ulong total_size)
 
 	end = (struct efi_mem_desc *)((ulong)map + size);
 	desc = map->desc;
-	for (; desc < end; desc = efi_get_next_mem_desc(map, desc)) {
+	for (; desc < end; desc = efi_get_next_mem_desc(desc, map->desc_size)) {
 		if (desc->type != EFI_CONVENTIONAL_MEMORY ||
 		    desc->physical_start >= 1ULL << 32)
 			continue;
@@ -89,7 +89,7 @@ int dram_init(void)
 	end = (struct efi_mem_desc *)((ulong)map + size);
 	gd->ram_size = 0;
 	desc = map->desc;
-	for (; desc < end; desc = efi_get_next_mem_desc(map, desc)) {
+	for (; desc < end; desc = efi_get_next_mem_desc(desc, map->desc_size)) {
 		if (desc->type < EFI_MMAP_IO)
 			gd->ram_size += desc->num_pages << EFI_PAGE_SHIFT;
 	}
@@ -114,7 +114,7 @@ int dram_init_banksize(void)
 	desc = map->desc;
 	for (num_banks = 0;
 	     desc < end && num_banks < CONFIG_NR_DRAM_BANKS;
-	     desc = efi_get_next_mem_desc(map, desc)) {
+	     desc = efi_get_next_mem_desc(desc, map->desc_size)) {
 		/*
 		 * We only use conventional memory and ignore
 		 * anything less than 1MB.
@@ -197,7 +197,7 @@ unsigned int install_e820_map(unsigned int max_entries,
 
 	end = (struct efi_mem_desc *)((ulong)map + size);
 	for (desc = map->desc; desc < end;
-	     desc = efi_get_next_mem_desc(map, desc)) {
+	     desc = efi_get_next_mem_desc(desc, map->desc_size)) {
 		if (desc->num_pages == 0)
 			continue;
 

arch/x86/cpu/x86_64/cpu.c

@@ -45,3 +45,8 @@ int cpu_phys_address_size(void)
 {
 	return CONFIG_CPU_ADDR_BITS;
 }
+
+int x86_cpu_init_f(void)
+{
+	return 0;
+}

arch/x86/lib/Makefile

@@ -65,9 +65,8 @@ endif
 
 lib-$(CONFIG_USE_PRIVATE_LIBGCC) += div64.o
 
-ifeq ($(CONFIG_$(SPL_)X86_64),)
+obj-$(CONFIG_EFI_APP_32BIT) += crt0_ia32_efi.o reloc_ia32_efi.o
-obj-$(CONFIG_EFI_APP) += crt0_ia32_efi.o reloc_ia32_efi.o
+obj-$(CONFIG_EFI_APP_64BIT) += crt0_x86_64_efi.o reloc_x86_64_efi.o
-endif
 
 ifneq ($(CONFIG_EFI_STUB),)
 

arch/x86/lib/elf_x86_64_efi.lds

@@ -63,6 +63,7 @@ SECTIONS
 		*(.rela.data*)
 		*(.rela.got)
 		*(.rela.stab)
+                *(.rela.u_boot_list*)
 	}
 
 	. = ALIGN(4096);
@@ -70,9 +71,11 @@ SECTIONS
 	. = ALIGN(4096);
 	.dynstr : { *(.dynstr) }
 	. = ALIGN(4096);
+
+        /DISCARD/ : { *(.eh_frame) }
+
 	.ignored.reloc : {
 		*(.rela.reloc)
-		*(.eh_frame)
 		*(.note.GNU-stack)
 	}
 

arch/x86/lib/relocate.c

@@ -35,6 +35,7 @@ int copy_uboot_to_ram(void)
 	return 0;
 }
 
+#ifndef CONFIG_EFI_APP
 int clear_bss(void)
 {
 	ulong dst_addr = (ulong)&__bss_start + gd->reloc_off;
@@ -46,6 +47,7 @@ int clear_bss(void)
 
 	return 0;
 }
+#endif
 
 #if CONFIG_IS_ENABLED(X86_64)
 static void do_elf_reloc_fixups64(unsigned int text_base, uintptr_t size,

cmd/Makefile

@@ -58,7 +58,7 @@ obj-$(CONFIG_CMD_EXTENSION) += extension_board.o
 obj-$(CONFIG_CMD_ECHO) += echo.o
 obj-$(CONFIG_ENV_IS_IN_EEPROM) += eeprom.o
 obj-$(CONFIG_CMD_EEPROM) += eeprom.o
-obj-$(CONFIG_EFI_STUB) += efi.o
+obj-$(CONFIG_EFI) += efi.o
 obj-$(CONFIG_CMD_EFIDEBUG) += efidebug.o
 obj-$(CONFIG_CMD_ELF) += elf.o
 obj-$(CONFIG_HUSH_PARSER) += exit.o

cmd/bootefi.c

@@ -310,6 +310,8 @@ efi_status_t efi_install_fdt(void *fdt)
 	/* Create memory reservations as indicated by the device tree */
 	efi_carve_out_dt_rsv(fdt);
 
+	efi_try_purge_kaslr_seed(fdt);
+
 	/* Install device tree as UEFI table */
 	ret = efi_install_configuration_table(&efi_guid_fdt, fdt);
 	if (ret != EFI_SUCCESS) {

cmd/efi.c

@@ -13,6 +13,8 @@
 #include <sort.h>
 #include <asm/global_data.h>
 
+DECLARE_GLOBAL_DATA_PTR;
+
 static const char *const type_name[] = {
 	"reserved",
 	"loader_code",
@@ -75,16 +77,17 @@ static int h_cmp_entry(const void *v1, const void *v2)
 /**
  * efi_build_mem_table() - make a sorted copy of the memory table
  *
- * @map:	Pointer to EFI memory map table
+ * @desc_base:	Pointer to EFI memory map table
  * @size:	Size of table in bytes
+ * @desc_size:	Size of each @desc_base record
  * @skip_bs:	True to skip boot-time memory and merge it with conventional
  *		memory. This will significantly reduce the number of table
  *		entries.
  * Return:	pointer to the new table. It should be freed with free() by the
  *		caller.
  */
-static void *efi_build_mem_table(struct efi_entry_memmap *map, int size,
+static void *efi_build_mem_table(struct efi_mem_desc *desc_base, int size,
-				 bool skip_bs)
+				 int desc_size, bool skip_bs)
 {
 	struct efi_mem_desc *desc, *end, *base, *dest, *prev;
 	int count;
@@ -95,15 +98,16 @@ static void *efi_build_mem_table(struct efi_entry_memmap *map, int size,
 		debug("%s: Cannot allocate %#x bytes\n", __func__, size);
 		return NULL;
 	}
-	end = (struct efi_mem_desc *)((ulong)map + size);
+	end = (void *)desc_base + size;
-	count = ((ulong)end - (ulong)map->desc) / map->desc_size;
+	count = ((ulong)end - (ulong)desc_base) / desc_size;
-	memcpy(base, map->desc, (ulong)end - (ulong)map->desc);
+	memcpy(base, desc_base, (ulong)end - (ulong)desc_base);
-	qsort(base, count, map->desc_size, h_cmp_entry);
+	qsort(base, count, desc_size, h_cmp_entry);
 	prev = NULL;
 	addr = 0;
 	dest = base;
-	end = (struct efi_mem_desc *)((ulong)base + count * map->desc_size);
+	end = (struct efi_mem_desc *)((ulong)base + count * desc_size);
-	for (desc = base; desc < end; desc = efi_get_next_mem_desc(map, desc)) {
+	for (desc = base; desc < end;
+	     desc = efi_get_next_mem_desc(desc, desc_size)) {
 		bool merge = true;
 		u32 type = desc->type;
 
@@ -116,7 +120,7 @@ static void *efi_build_mem_table(struct efi_entry_memmap *map, int size,
 		if (skip_bs && is_boot_services(desc->type))
 			type = EFI_CONVENTIONAL_MEMORY;
 
-		memcpy(dest, desc, map->desc_size);
+		memcpy(dest, desc, desc_size);
 		dest->type = type;
 		if (!skip_bs || !prev)
 			merge = false;
@@ -131,7 +135,7 @@ static void *efi_build_mem_table(struct efi_entry_memmap *map, int size,
 			prev->num_pages += desc->num_pages;
 		} else {
 			prev = dest;
-			dest = efi_get_next_mem_desc(map, dest);
+			dest = efi_get_next_mem_desc(dest, desc_size);
 		}
 		addr = desc->physical_start + (desc->num_pages <<
 				EFI_PAGE_SHIFT);
@@ -143,8 +147,8 @@ static void *efi_build_mem_table(struct efi_entry_memmap *map, int size,
 	return base;
 }
 
-static void efi_print_mem_table(struct efi_entry_memmap *map,
+static void efi_print_mem_table(struct efi_mem_desc *desc, int desc_size,
-				struct efi_mem_desc *desc, bool skip_bs)
+				bool skip_bs)
 {
 	u64 attr_seen[ATTR_SEEN_MAX];
 	int attr_seen_count;
@@ -158,7 +162,7 @@ static void efi_print_mem_table(struct efi_entry_memmap *map,
 	attr_seen_count = 0;
 	addr = 0;
 	for (upto = 0; desc->type != EFI_MAX_MEMORY_TYPE;
-	     upto++, desc = efi_get_next_mem_desc(map, desc)) {
+	     upto++, desc = efi_get_next_mem_desc(desc, desc_size)) {
 		const char *name;
 		u64 size;
 
@@ -215,37 +219,53 @@ static void efi_print_mem_table(struct efi_entry_memmap *map,
 static int do_efi_mem(struct cmd_tbl *cmdtp, int flag, int argc,
 		      char *const argv[])
 {
-	struct efi_mem_desc *desc;
+	struct efi_mem_desc *orig, *desc;
-	struct efi_entry_memmap *map;
+	uint version, key;
+	int desc_size;
 	int size, ret;
 	bool skip_bs;
 
 	skip_bs = !argc || *argv[0] != 'a';
-	ret = efi_info_get(EFIET_MEMORY_MAP, (void **)&map, &size);
+	if (IS_ENABLED(CONFIG_EFI_APP)) {
-	switch (ret) {
+		ret = efi_get_mmap(&orig, &size, &key, &desc_size, &version);
-	case -ENOENT:
+		if (ret) {
-		printf("No EFI table available\n");
+			printf("Cannot read memory map (err=%d)\n", ret);
-		goto done;
+			return CMD_RET_FAILURE;
-	case -EPROTONOSUPPORT:
+		}
-		printf("Incorrect EFI table version\n");
+	} else {
-		goto done;
+		struct efi_entry_memmap *map;
+
+		ret = efi_info_get(EFIET_MEMORY_MAP, (void **)&map, &size);
+		switch (ret) {
+		case -ENOENT:
+			printf("No EFI table available\n");
+			goto done;
+		case -EPROTONOSUPPORT:
+			printf("Incorrect EFI table version\n");
+			goto done;
+		}
+		orig = map->desc;
+		desc_size = map->desc_size;
+		version = map->version;
 	}
-	printf("EFI table at %lx, memory map %p, size %x, version %x, descr. size %#x\n",
+	printf("EFI table at %lx, memory map %p, size %x, key %x, version %x, descr. size %#x\n",
-	       gd->arch.table, map, size, map->version, map->desc_size);
+	       gd->arch.table, orig, size, key, version, desc_size);
-	if (map->version != EFI_MEM_DESC_VERSION) {
+	if (version != EFI_MEM_DESC_VERSION) {
 		printf("Incorrect memory map version\n");
 		ret = -EPROTONOSUPPORT;
 		goto done;
 	}
 
-	desc = efi_build_mem_table(map, size, skip_bs);
+	desc = efi_build_mem_table(orig, size, desc_size, skip_bs);
 	if (!desc) {
 		ret = -ENOMEM;
 		goto done;
 	}
 
-	efi_print_mem_table(map, desc, skip_bs);
+	efi_print_mem_table(desc, desc_size, skip_bs);
 	free(desc);
+	if (IS_ENABLED(CONFIG_EFI_APP))
+		free(orig);
 done:
 	if (ret)
 		printf("Error: %d\n", ret);

cmd/part.c

@@ -89,10 +89,10 @@ static int do_part_list(int argc, char *const argv[])
 
 	if (var != NULL) {
 		int p;
-		char str[512] = { '\0', };
+		char str[3 * MAX_SEARCH_PARTITIONS] = { '\0', };
 		struct disk_partition info;
 
-		for (p = 1; p < MAX_SEARCH_PARTITIONS; p++) {
+		for (p = 1; p <= MAX_SEARCH_PARTITIONS; p++) {
 			char t[5];
 			int r = part_get_info(desc, p, &info);
 

disk/part_efi.c

@@ -236,9 +236,9 @@ void part_print_efi(struct blk_desc *dev_desc)
 	printf("\tPartition GUID\n");
 
 	for (i = 0; i < le32_to_cpu(gpt_head->num_partition_entries); i++) {
-		/* Stop at the first non valid PTE */
+		/* Skip invalid PTE */
 		if (!is_pte_valid(&gpt_pte[i]))
-			break;
+			continue;
 
 		printf("%3d\t0x%08llx\t0x%08llx\t\"%s\"\n", (i + 1),
 			le64_to_cpu(gpt_pte[i].starting_lba),

doc/api/dm.rst

@@ -0,0 +1,29 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Driver Model
+============
+
+Uclass and Driver
+-----------------
+
+.. kernel-doc:: include/dm/uclass.h
+.. kernel-doc:: include/dm/root.h
+.. kernel-doc:: include/dm/lists.h
+.. kernel-doc:: include/dm/platdata.h
+
+Device
+------
+
+.. kernel-doc:: include/dm/device.h
+.. kernel-doc:: include/dm/devres.h
+.. kernel-doc:: include/dm/read.h
+
+Device tree
+-----------
+
+.. kernel-doc:: include/dm/of.h
+.. kernel-doc:: include/dm/ofnode.h
+.. kernel-doc:: include/dm/of_extra.h
+.. kernel-doc:: include/dm/of_access.h
+.. kernel-doc:: include/dm/of_addr.h
+.. kernel-doc:: include/dm/fdtaddr.h

doc/api/index.rst

@@ -7,6 +7,7 @@ U-Boot API documentation
    :maxdepth: 2
 
    dfu
+   dm
    efi
    getopt
    linker_lists

doc/board/armltd/index.rst

@@ -6,4 +6,5 @@ Arm Ltd
 .. toctree::
    :maxdepth: 2
 
+   juno
    vexpress64.rst

doc/board/armltd/juno.rst

@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. Copyright (C) 2021 Arm Ltd.
+
+Arm Juno development platform
+=============================
+
+The `Juno development board`_ is an open, vendor-neutral, Armv8-A development
+platform, made by Arm Ltd. It is part of the Versatile Express family.
+There are three revisions of the board:
+
+* Juno r0, with two Cortex-A57 and four Cortex-A53 cores, without PCIe.
+* Juno r1, with two Cortex-A57 and four Cortex-A53 cores, in later silicon
+  revisions, and with PCIe slots, Gigabit Ethernet and two SATA ports.
+* Juno r2, with two Cortex-A72 and four Cortex-A53 cores, otherwise the
+  same as r1.
+
+Among other things, the motherboard contains a management controller (MCC),
+an FPGA providing I/O interfaces (IOFPGA) and 64MB of NOR flash. The provided
+platform devices resemble the VExpress peripherals.
+The actual SoC also contains a Cortex-M3 based System Control Processor (SCP).
+The `V2M-Juno TRM`_ contains more technical details.
+
+U-Boot build
+------------
+There is only one defconfig and one binary build that covers all three board
+revisions, so to generate the needed ``u-boot.bin``:
+
+.. code-block:: bash
+
+    $ make vexpress_aemv8a_juno_defconfig
+    $ make
+
+The automatic distro boot sequence looks for UEFI boot applications and
+``boot.scr`` scripts on various boot media, starting with USB, then on disks
+connected to the two SATA ports, PXE, DHCP and eventually on the NOR flash.
+
+U-Boot installation
+-------------------
+This assumes there is some firmware on the SD card or NOR flash (see below
+for more details). The U-Boot binary is included in the Trusted Firmware
+FIP image, so after building U-Boot, this needs to be repackaged or recompiled.
+
+The NOR flash will be updated by the MCC, based on the content of a micro-SD
+card, which is exported as a USB mass storage device via the rear USB-B
+socket. So to access that SD card, connect a cable to some host computer, and
+mount the FAT16 partition of the UMS device.
+If there is no device, check the upper serial port for a prompt, and
+explicitly enable the USB interface::
+
+    Cmd> usb_on
+    Enabling debug USB...
+
+Repackaging an existing FIP image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To prevent problems, it is probably a good idea to backup the existing firmware,
+for instance by just copying the entire ``SOFTWARE/`` directory, or at least
+the current ``fip.bin``, beforehand.
+
+To just replace the BL33 image in the exising FIP image, you can use
+`fiptool`_ from the Trusted Firmware repository, on the image file:
+
+.. code-block:: bash
+
+    git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+    cd trusted-firmware-a
+    make fiptool
+    tools/fiptool/fiptool update --nt-fw=/path/to/your/u-boot.bin /mnt/juno/SOFTWARE/fip.bin
+
+Unmount the USB mass storage device and reboot the board, the new ``fip.bin``
+will be automatically written to the NOR flash and then used.
+
+Rebuilding Trusted Firmware
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+You can also generate a new FIP image by compiling Arm Trusted Firmware,
+and providing ``u-boot.bin`` as the BL33 file. For that you can either build
+the required `SCP firmware`_ yourself, or just extract the existing
+version from your ``fip.bin``, using `fiptool`_ (see above):
+
+.. code-block:: bash
+
+    mkdir /tmp/juno; cd /tmp/juno
+    fiptool unpack /mnt/juno/SOFTWARE/fip.bin
+
+Then build TF-A:
+
+.. code-block:: bash
+
+    git clone https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git
+    cd trusted-firmware-a
+    make CROSS_COMPILE=aarch64-linux-gnu- PLAT=juno DEBUG=1 \
+    SCP_BL2=/tmp/juno/scp-fw.bin BL33=/path/to/your/u-boot.bin fiptool all fip
+    cp build/juno/debug/bl1.bin build/juno/debug/fip.bin /mnt/juno/SOFTWARE
+
+Then umount the USB device, and reboot, as above.
+
+Device trees
+------------
+The device tree files for the boards are maintained in the Linux kernel
+repository. They end up in the ``SOFTWARE/`` directory of the SD card, as
+``juno.dtb``, ``juno-r1.dtb``, and ``juno-r2.dtb``, respectively. The MCC
+firmware will look into the images.txt file matching the board revision, from
+the ``SITE1/`` directory. Each version there will reference its respective DTB
+file in ``SOFTWARE/``, and so the correct version will end in the NOR flash, in
+the ``board.dtb`` partition. U-Boot picks its control DTB from there, you can
+pass this on to a kernel using ``$fdtcontroladdr``.
+
+You can update the DTBs anytime, by building them using the ``dtbs`` make
+target from a Linux kernel tree, then just copying the generated binaries
+to the ``SOFTWARE/`` directory of the SD card.
+
+.. _`Juno development board`: https://developer.arm.com/tools-and-software/development-boards/juno-development-board
+.. _`V2M-Juno TRM`: https://developer.arm.com/documentation/100113/latest
+.. _`fiptool`: https://github.com/ARM-software/arm-trusted-firmware/tree/master/tools/fiptool
+.. _`SCP firmware`: https://github.com/ARM-software/SCP-firmware.git

doc/build/gcc.rst

@@ -51,6 +51,16 @@ Depending on the build targets further packages maybe needed.
     zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \
       ncurses-devel python3-devel python3-pytest swig
 
+Alpine Linux
+~~~~~~~~~~~~
+
+For building U-Boot on Alpine Linux at least the following packages are needed:
+
+.. code-block:: bash
+
+    apk add alpine-sdk bc bison dtc flex linux-headers ncurses-dev \
+      openssl-dev python3 py3-setuptools python3-dev sdl2
+
 Prerequisites
 -------------
 

doc/sphinx/requirements.txt

@@ -1,4 +1,4 @@
 docutils==0.16
-Sphinx==3.4.3
+sphinx==3.4.3
-sphinx_rtd_theme
+sphinx_rtd_theme==1.0.0
-six
+six==1.16.0

include/dm/device.h

@@ -145,7 +145,7 @@ enum {
  * @uclass_node: Used by uclass to link its devices
  * @child_head: List of children of this device
  * @sibling_node: Next device in list of all devices
- * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
+ * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
  *	model)
  * @seq_: Allocated sequence number for this device (-1 = none). This is set up
  * when the device is bound and is unique within the device's uclass. If the
@@ -193,14 +193,14 @@ struct udevice {
 };
 
 /**
- * udevice_rt - runtime information set up by U-Boot
+ * struct udevice_rt - runtime information set up by U-Boot
  *
  * This is only used with OF_PLATDATA_RT
  *
  * There is one of these for every udevice in the linker list, indexed by
  * the udevice_info idx value.
  *
- * @flags_: Flags for this device DM_FLAG_... (do not access outside driver
+ * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver
  *	model)
  */
 struct udevice_rt {
@@ -239,7 +239,7 @@ static inline void dev_bic_flags(struct udevice *dev, u32 bic)
  * dev_ofnode() - get the DT node reference associated with a udevice
  *
  * @dev:	device to check
- * @return reference of the the device's DT node
+ * Return: reference of the device's DT node
  */
 static inline ofnode dev_ofnode(const struct udevice *dev)
 {
@@ -351,7 +351,7 @@ struct udevice_id {
  * @ops: Driver-specific operations. This is typically a list of function
  * pointers defined by the driver, to implement driver functions required by
  * the uclass.
- * @flags: driver flags - see DM_FLAGS_...
+ * @flags: driver flags - see `DM_FLAGS_...`
  * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations,
  * allowing the device to add things to the ACPI tables passed to Linux
  */
@@ -378,11 +378,24 @@ struct driver {
 #endif
 };
 
-/* Declare a new U-Boot driver */
+/**
+ * U_BOOT_DRIVER() - Declare a new U-Boot driver
+ * @__name: name of the driver
+ */
 #define U_BOOT_DRIVER(__name)						\
 	ll_entry_declare(struct driver, __name, driver)
 
-/* Get a pointer to a given driver */
+/**
+ * DM_DRIVER_GET() - Get a pointer to a given driver
+ *
+ * This is useful in code for referencing a driver at build time.
+ * Before this is used, an extern U_BOOT_DRIVER() must have been
+ * declared.
+ *
+ * @__name:	Name of the driver. This must be a valid C identifier,
+ * used by the linker_list
+ * Return: struct driver * for the driver
+ */
 #define DM_DRIVER_GET(__name)						\
 	ll_entry_get(struct driver, __name, driver)
 
@@ -392,60 +405,69 @@ struct driver {
  * This is useful in data structures and code for referencing a driver at
  * build time. Before this is used, an extern U_BOOT_DRIVER() must have been
  * declared.
+ * This is like DM_DRIVER_GET, but without the extra code, so it is suitable
+ * for putting into data structures.
  *
- * For example:
+ * For example::
  *
- * extern U_BOOT_DRIVER(sandbox_fixed_clock);
+ *   extern U_BOOT_DRIVER(sandbox_fixed_clock);
+ *   struct driver *drvs[] = {
+ *       DM_DRIVER_REF(sandbox_fixed_clock),
+ *   };
  *
- * struct driver *drvs[] = {
+ * @_name:	Name of the driver. This must be a valid C identifier,
- *	DM_DRIVER_REF(sandbox_fixed_clock),
+ * used by the linker_list
- * };
+ * Return: struct driver * for the driver
- *
- * @_name: Name of the driver. This must be a valid C identifier, used by the
- *	linker_list
- * @returns struct driver * for the driver
  */
 #define DM_DRIVER_REF(_name)					\
 	ll_entry_ref(struct driver, _name, driver)
 
 /**
- * Declare a macro to state a alias for a driver name. This macro will
+ * DM_DRIVER_ALIAS() - Declare a macro to state an alias for a driver name
- * produce no code but its information will be parsed by tools like
+ *
- * dtoc
+ * This macro will produce no code but its information will be parsed by tools
+ * like dtoc
+ *
+ * @__name:	name of driver
+ * @__alias:	alias for the driver name
  */
 #define DM_DRIVER_ALIAS(__name, __alias)
 
 /**
- * Declare a macro to indicate which phase of U-Boot this driver is fore.
+ * DM_PHASE() - Declare a macro to indicate which phase of U-Boot this driver is for.
- *
  *
  * This macro produces no code but its information will be parsed by dtoc. The
  * macro can be only be used once in a driver. Put it within the U_BOOT_DRIVER()
- * declaration, e.g.:
+ * declaration, e.g.::
  *
- * U_BOOT_DRIVER(cpu) = {
+ *   U_BOOT_DRIVER(cpu) = {
- *	.name = ...
+ *       .name = ...
- *	...
+ *       ...
- *	DM_PHASE(tpl)
+ *       DM_PHASE(tpl)
- * };
+ *   };
+ *
+ * @_phase:	Associated phase of U-Boot ("spl", "tpl")
  */
 #define DM_PHASE(_phase)
 
 /**
- * Declare a macro to declare a header needed for a driver. Often the correct
+ * DM_HEADER() - Declare a macro to declare a header needed for a driver.
- * header can be found automatically, but only for struct declarations. For
+ *
- * enums and #defines used in the driver declaration and declared in a different
+ * Often the correct header can be found automatically, but only for struct
- * header from the structs, this macro must be used.
+ * declarations. For enums and #defines used in the driver declaration and
+ * declared in a different header from the structs, this macro must be used.
  *
  * This macro produces no code but its information will be parsed by dtoc. The
  * macro can be used multiple times with different headers, for the same driver.
- * Put it within the U_BOOT_DRIVER() declaration, e.g.:
+ * Put it within the U_BOOT_DRIVER() declaration, e.g.::
  *
- * U_BOOT_DRIVER(cpu) = {
+ *   U_BOOT_DRIVER(cpu) = {
- *	.name = ...
+ *       .name = ...
- *	...
+ *       ...
- *	DM_HEADER(<asm/cpu.h>)
+ *       DM_HEADER(<asm/cpu.h>)
- * };
+ *   };
+ *
+ * @_hdr:	header needed for a driver
  */
 #define DM_HEADER(_hdr)
 
@@ -454,8 +476,8 @@ struct driver {
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return platform data, or NULL if none
+ * Return: platform data, or NULL if none
  */
 void *dev_get_plat(const struct udevice *dev);
 
@@ -464,8 +486,8 @@ void *dev_get_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return parent's platform data, or NULL if none
+ * Return: parent's platform data, or NULL if none
  */
 void *dev_get_parent_plat(const struct udevice *dev);
 
@@ -474,8 +496,8 @@ void *dev_get_parent_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return uclass's platform data, or NULL if none
+ * Return: uclass's platform data, or NULL if none
  */
 void *dev_get_uclass_plat(const struct udevice *dev);
 
@@ -484,8 +506,8 @@ void *dev_get_uclass_plat(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return private data, or NULL if none
+ * Return: private data, or NULL if none
  */
 void *dev_get_priv(const struct udevice *dev);
 
@@ -498,8 +520,8 @@ void *dev_get_priv(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return parent data, or NULL if none
+ * Return: parent data, or NULL if none
  */
 void *dev_get_parent_priv(const struct udevice *dev);
 
@@ -508,16 +530,16 @@ void *dev_get_parent_priv(const struct udevice *dev);
  *
  * This checks that dev is not NULL, but no other checks for now
  *
- * @dev		Device to check
+ * @dev:	Device to check
- * @return private uclass data for this device, or NULL if none
+ * Return: private uclass data for this device, or NULL if none
  */
 void *dev_get_uclass_priv(const struct udevice *dev);
 
 /**
- * struct dev_get_parent() - Get the parent of a device
+ * dev_get_parent() - Get the parent of a device
  *
  * @child:	Child to check
- * @return parent of child, or NULL if this is the root device
+ * Return: parent of child, or NULL if this is the root device
  */
 struct udevice *dev_get_parent(const struct udevice *child);
 
@@ -529,13 +551,14 @@ struct udevice *dev_get_parent(const struct udevice *child);
  * returns the associated data value for that compatible string. This is
  * the 'data' field in struct udevice_id.
  *
- * As an example, consider this structure:
+ * As an example, consider this structure::
- * static const struct udevice_id tegra_i2c_ids[] = {
+ *
- *	{ .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
+ *  static const struct udevice_id tegra_i2c_ids[] = {
- *	{ .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
+ *      { .compatible = "nvidia,tegra114-i2c", .data = TYPE_114 },
- *	{ .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
+ *      { .compatible = "nvidia,tegra20-i2c", .data = TYPE_STD },
- *	{ }
+ *      { .compatible = "nvidia,tegra20-i2c-dvc", .data = TYPE_DVC },
- * };
+ *      { }
+ *  };
  *
  * When driver model finds a driver for this it will store the 'data' value
  * corresponding to the compatible string it matches. This function returns
@@ -544,7 +567,7 @@ struct udevice *dev_get_parent(const struct udevice *child);
  * For USB devices, this is the driver_info field in struct usb_device_id.
  *
  * @dev:	Device to check
- * @return driver data (0 if none is provided)
+ * Return: driver data (0 if none is provided)
  */
 ulong dev_get_driver_data(const struct udevice *dev);
 
@@ -555,7 +578,7 @@ ulong dev_get_driver_data(const struct udevice *dev);
  * driver's operations.
  *
  * @dev:	Device to check
- * @return void pointer to driver's operations or NULL for NULL-dev or NULL-ops
+ * Return: void pointer to driver's operations or NULL for NULL-dev or NULL-ops
  */
 const void *dev_get_driver_ops(const struct udevice *dev);
 
@@ -563,7 +586,7 @@ const void *dev_get_driver_ops(const struct udevice *dev);
  * device_get_uclass_id() - return the uclass ID of a device
  *
  * @dev:	Device to check
- * @return uclass ID for the device
+ * Return: uclass ID for the device
  */
 enum uclass_id device_get_uclass_id(const struct udevice *dev);
 
@@ -573,7 +596,7 @@ enum uclass_id device_get_uclass_id(const struct udevice *dev);
  * This checks that dev is not NULL.
  *
  * @dev:	Device to check
- * @return  pointer to the uclass name for the device
+ * Return:  pointer to the uclass name for the device
  */
 const char *dev_get_uclass_name(const struct udevice *dev);
 
@@ -583,11 +606,11 @@ const char *dev_get_uclass_name(const struct udevice *dev);
  * Returns the numbered child, 0 being the first. This does not use
  * sequence numbers, only the natural order.
  *
- * @dev:	Parent device to check
+ * @parent:	Parent device to check
  * @index:	Child index
  * @devp:	Returns pointer to device
- * @return 0 if OK, -ENODEV if no such device, other error if the device fails
+ * Return:
- *	   to probe
+ * 0 if OK, -ENODEV if no such device, other error if the device fails to probe
  */
 int device_get_child(const struct udevice *parent, int index,
 		     struct udevice **devp);
@@ -619,7 +642,7 @@ int device_get_decendent_count(const struct udevice *parent);
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one per for each seq).
  * Set to NULL if none is found
- * @return 0 if OK, -ENODEV if not found
+ * Return: 0 if OK, -ENODEV if not found
  */
 int device_find_child_by_seq(const struct udevice *parent, int seq,
 			     struct udevice **devp);
@@ -637,7 +660,7 @@ int device_find_child_by_seq(const struct udevice *parent, int seq,
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one per for each seq)
  * Set to NULL if none is found
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_child_by_seq(const struct udevice *parent, int seq,
 			    struct udevice **devp);
@@ -650,7 +673,7 @@ int device_get_child_by_seq(const struct udevice *parent, int seq,
  * @parent: Parent device
  * @of_offset: Device tree offset to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
 				   struct udevice **devp);
@@ -665,7 +688,7 @@ int device_find_child_by_of_offset(const struct udevice *parent, int of_offset,
  * @parent: Parent device
  * @of_offset: Device tree offset to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
 				  struct udevice **devp);
@@ -680,7 +703,7 @@ int device_get_child_by_of_offset(const struct udevice *parent, int of_offset,
  *
  * @node: Device tree ofnode to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 
 int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
@@ -695,7 +718,7 @@ int device_find_global_by_ofnode(ofnode node, struct udevice **devp);
  *
  * @node: Device tree ofnode to find
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
 
@@ -715,7 +738,7 @@ int device_get_global_by_ofnode(ofnode node, struct udevice **devp);
  *
  * @idx: Index number of the driver_info/udevice structure (0=first)
  * @devp: Returns pointer to device if found, otherwise this is set to NULL
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
 
@@ -724,7 +747,7 @@ int device_get_by_ofplat_idx(uint idx, struct udevice **devp);
  *
  * @parent: Parent device to search
  * @devp: Returns first child device, or NULL if none
- * @return 0
+ * Return: 0
  */
 int device_find_first_child(const struct udevice *parent,
 			    struct udevice **devp);
@@ -734,7 +757,7 @@ int device_find_first_child(const struct udevice *parent,
  *
  * @devp: Pointer to previous child device on entry. Returns pointer to next
  *		child device, or NULL if none
- * @return 0
+ * Return: 0
  */
 int device_find_next_child(struct udevice **devp);
 
@@ -749,7 +772,7 @@ int device_find_next_child(struct udevice **devp);
  * @parent:	Parent device to search
  * @uclass_id:	Uclass to look for
  * @devp:	Returns device found, if any, else NULL
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_first_inactive_child(const struct udevice *parent,
 				     enum uclass_id uclass_id,
@@ -761,7 +784,7 @@ int device_find_first_inactive_child(const struct udevice *parent,
  * @parent: Parent device to search
  * @uclass_id:	Uclass to look for
  * @devp: Returns first child device in that uclass, if any, else NULL
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_first_child_by_uclass(const struct udevice *parent,
 				      enum uclass_id uclass_id,
@@ -774,7 +797,7 @@ int device_find_first_child_by_uclass(const struct udevice *parent,
  * @name:	Name to look for
  * @len:	Length of the name
  * @devp:	Returns device found, if any
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_child_by_namelen(const struct udevice *parent, const char *name,
 				 int len, struct udevice **devp);
@@ -785,7 +808,7 @@ int device_find_child_by_namelen(const struct udevice *parent, const char *name,
  * @parent:	Parent device to search
  * @name:	Name to look for
  * @devp:	Returns device found, if any
- * @return 0 if found, else -ENODEV
+ * Return: 0 if found, else -ENODEV
  */
 int device_find_child_by_name(const struct udevice *parent, const char *name,
 			      struct udevice **devp);
@@ -798,7 +821,7 @@ int device_find_child_by_name(const struct udevice *parent, const char *name,
  *
  * @parent: Parent to check
  * @devp: Returns child that was found, if any
- * @return 0 on success, -ENODEV if no children, other -ve on error
+ * Return: 0 on success, -ENODEV if no children, other -ve on error
  */
 int device_first_child_ofdata_err(struct udevice *parent,
 				  struct udevice **devp);
@@ -811,7 +834,7 @@ int device_first_child_ofdata_err(struct udevice *parent,
  *
  * @devp: On entry, points to the previous child; on exit returns the child that
  *	was found, if any
- * @return 0 on success, -ENODEV if no children, other -ve on error
+ * Return: 0 on success, -ENODEV if no children, other -ve on error
  */
 int device_next_child_ofdata_err(struct udevice **devp);
 
@@ -822,7 +845,7 @@ int device_next_child_ofdata_err(struct udevice **devp);
  *
  * @parent:	Parent device to search
  * @devp:	Returns device found, if any
- * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
+ * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
  */
 int device_first_child_err(struct udevice *parent, struct udevice **devp);
 
@@ -833,7 +856,7 @@ int device_first_child_err(struct udevice *parent, struct udevice **devp);
  *
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next sibling if no error occurred
- * @return 0 if found, -ENODEV if not, -ve error if device failed to probe
+ * Return: 0 if found, -ENODEV if not, -ve error if device failed to probe
  */
 int device_next_child_err(struct udevice **devp);
 
@@ -841,7 +864,7 @@ int device_next_child_err(struct udevice **devp);
  * device_has_children() - check if a device has any children
  *
  * @dev:	Device to check
- * @return true if the device has one or more children
+ * Return: true if the device has one or more children
  */
 bool device_has_children(const struct udevice *dev);
 
@@ -849,7 +872,7 @@ bool device_has_children(const struct udevice *dev);
  * device_has_active_children() - check if a device has any active children
  *
  * @dev:	Device to check
- * @return true if the device has one or more children and at least one of
+ * Return: true if the device has one or more children and at least one of
  * them is active (probed).
  */
 bool device_has_active_children(const struct udevice *dev);
@@ -862,7 +885,7 @@ bool device_has_active_children(const struct udevice *dev);
  * view of devices is being displayed.
  *
  * @dev:	Device to check
- * @return true if there are no more siblings after this one - i.e. is it
+ * Return: true if there are no more siblings after this one - i.e. is it
  * last in the list.
  */
 bool device_is_last_sibling(const struct udevice *dev);
@@ -880,7 +903,7 @@ bool device_is_last_sibling(const struct udevice *dev);
  * @dev:	Device to update
  * @name:	New name (this string is allocated new memory and attached to
  *		the device)
- * @return 0 if OK, -ENOMEM if there is not enough memory to allocate the
+ * Return: 0 if OK, -ENOMEM if there is not enough memory to allocate the
  * string
  */
 int device_set_name(struct udevice *dev, const char *name);
@@ -903,7 +926,7 @@ void device_set_name_alloced(struct udevice *dev);
  * @dev:	udevice pointer for which compatible needs to be verified.
  * @compat:	Compatible string which needs to verified in the given
  *		device
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 bool device_is_compatible(const struct udevice *dev, const char *compat);
 
@@ -914,7 +937,7 @@ bool device_is_compatible(const struct udevice *dev, const char *compat);
  * This allows to check whether the machine is comaptible with the compat.
  *
  * @compat:	Compatible string which needs to verified
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 bool of_machine_is_compatible(const char *compat);
 
@@ -922,7 +945,7 @@ bool of_machine_is_compatible(const char *compat);
  * dev_disable_by_path() - Disable a device given its device tree path
  *
  * @path:	The device tree path identifying the device to be disabled
- * @return 0 on success, -ve on error
+ * Return: 0 on success, -ve on error
  */
 int dev_disable_by_path(const char *path);
 
@@ -930,7 +953,7 @@ int dev_disable_by_path(const char *path);
  * dev_enable_by_path() - Enable a device given its device tree path
  *
  * @path:	The device tree path identifying the device to be enabled
- * @return 0 on success, -ve on error
+ * Return: 0 on success, -ve on error
  */
 int dev_enable_by_path(const char *path);
 
@@ -938,7 +961,7 @@ int dev_enable_by_path(const char *path);
  * device_is_on_pci_bus - Test if a device is on a PCI bus
  *
  * @dev:	device to test
- * @return:	true if it is on a PCI bus, false otherwise
+ * Return:	true if it is on a PCI bus, false otherwise
  */
 static inline bool device_is_on_pci_bus(const struct udevice *dev)
 {
@@ -971,7 +994,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
  *
  * This stops when it gets an error, with @pos set to the device that failed to
  * read ofdata.
-
+ *
  * This creates a for() loop which works through the available children of
  * a device in order from start to end. Device ofdata is read by calling
  * device_of_to_plat() on each one. The devices are not probed.
@@ -1012,7 +1035,7 @@ static inline bool device_is_on_pci_bus(const struct udevice *dev)
  * be bound.
  *
  * @dev:	Device to scan
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_fdt_dev(struct udevice *dev);
 

include/dm/devres.h

@@ -51,7 +51,7 @@ void *_devres_alloc(dr_release_t release, size_t size, gfp_t gfp);
  * with @release.  The returned pointer can be passed to
  * other devres_*() functions.
  *
- * RETURNS:
+ * Return:
  * Pointer to allocated devres on success, NULL on failure.
  */
 #define devres_alloc(release, size, gfp) \
@@ -87,7 +87,7 @@ void devres_add(struct udevice *dev, void *res);
  * and for which @match returns 1.  If @match is NULL, it's considered
  * to match all.
  *
- * @return pointer to found devres, NULL if not found.
+ * Return: pointer to found devres, NULL if not found.
  */
 void *devres_find(struct udevice *dev, dr_release_t release,
 		  dr_match_t match, void *match_data);
@@ -103,7 +103,7 @@ void *devres_find(struct udevice *dev, dr_release_t release,
  * as @new_res and for which @match return 1.  If found, @new_res is
  * freed; otherwise, @new_res is added atomically.
  *
- * @return ointer to found or added devres.
+ * Return: pointer to found or added devres.
  */
 void *devres_get(struct udevice *dev, void *new_res,
 		 dr_match_t match, void *match_data);
@@ -120,7 +120,7 @@ void *devres_get(struct udevice *dev, void *new_res,
  * match all.  If found, the resource is removed atomically and
  * returned.
  *
- * @return ointer to removed devres on success, NULL if not found.
+ * Return: pointer to removed devres on success, NULL if not found.
  */
 void *devres_remove(struct udevice *dev, dr_release_t release,
 		    dr_match_t match, void *match_data);
@@ -140,7 +140,7 @@ void *devres_remove(struct udevice *dev, dr_release_t release,
  * only the devres-allocated data will be freed.  The caller becomes
  * responsible for freeing any other data.
  *
- * @return 0 if devres is found and freed, -ENOENT if not found.
+ * Return: 0 if devres is found and freed, -ENOENT if not found.
  */
 int devres_destroy(struct udevice *dev, dr_release_t release,
 		   dr_match_t match, void *match_data);
@@ -157,7 +157,7 @@ int devres_destroy(struct udevice *dev, dr_release_t release,
  * match all.  If found, the resource is removed atomically, the
  * release function called and the resource freed.
  *
- * @return 0 if devres is found and freed, -ENOENT if not found.
+ * Return: 0 if devres is found and freed, -ENOENT if not found.
  */
 int devres_release(struct udevice *dev, dr_release_t release,
 		   dr_match_t match, void *match_data);
@@ -173,7 +173,7 @@ int devres_release(struct udevice *dev, dr_release_t release,
  * automatically freed on driver detach.  Like all other devres
  * resources, guaranteed alignment is unsigned long long.
  *
- * @return pointer to allocated memory on success, NULL on failure.
+ * Return: pointer to allocated memory on success, NULL on failure.
  */
 void *devm_kmalloc(struct udevice *dev, size_t size, gfp_t gfp);
 static inline void *devm_kzalloc(struct udevice *dev, size_t size, gfp_t gfp)

include/dm/fdtaddr.h

@@ -19,7 +19,7 @@ struct udevice;
  *
  * @dev: Pointer to a device
  *
- * @return addr
+ * Return: addr
  */
 fdt_addr_t devfdt_get_addr(const struct udevice *dev);
 
@@ -29,7 +29,7 @@ fdt_addr_t devfdt_get_addr(const struct udevice *dev);
  *
  * @dev: Pointer to a device
  *
- * @return Pointer to addr, or NULL if there is no such property
+ * Return: Pointer to addr, or NULL if there is no such property
  */
 void *devfdt_get_addr_ptr(const struct udevice *dev);
 
@@ -39,7 +39,7 @@ void *devfdt_get_addr_ptr(const struct udevice *dev);
  *
  * @dev: Pointer to a device
  *
- * @return Pointer to addr, or NULL if there is no such property
+ * Return: Pointer to addr, or NULL if there is no such property
  */
 void *devfdt_remap_addr(const struct udevice *dev);
 
@@ -51,7 +51,7 @@ void *devfdt_remap_addr(const struct udevice *dev);
  *
  * @dev: Pointer to a device
  *
- * @return Pointer to addr, or NULL if there is no such property
+ * Return: Pointer to addr, or NULL if there is no such property
  */
 void *devfdt_remap_addr_index(const struct udevice *dev, int index);
 
@@ -64,7 +64,7 @@ void *devfdt_remap_addr_index(const struct udevice *dev, int index);
  *
  * @dev: Pointer to a device
  *
- * @return Pointer to addr, or NULL if there is no such property
+ * Return: Pointer to addr, or NULL if there is no such property
  */
 void *devfdt_remap_addr_name(const struct udevice *dev, const char *name);
 
@@ -76,8 +76,7 @@ void *devfdt_remap_addr_name(const struct udevice *dev, const char *name);
  * @dev: Pointer to device
  * @size: size of the memory to map
  *
- * @return  mapped address, or NULL if the device does not have reg
+ * Return: mapped address, or NULL if the device does not have reg property.
- *          property.
  */
 void *devfdt_map_physmem(const struct udevice *dev, unsigned long size);
 
@@ -88,7 +87,7 @@ void *devfdt_map_physmem(const struct udevice *dev, unsigned long size);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return addr
+ * Return: addr
  */
 fdt_addr_t devfdt_get_addr_index(const struct udevice *dev, int index);
 
@@ -100,7 +99,7 @@ fdt_addr_t devfdt_get_addr_index(const struct udevice *dev, int index);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return Pointer to addr, or NULL if there is no such property
+ * Return: Pointer to addr, or NULL if there is no such property
  */
 void *devfdt_get_addr_index_ptr(const struct udevice *dev, int index);
 
@@ -115,7 +114,7 @@ void *devfdt_get_addr_index_ptr(const struct udevice *dev, int index);
  * @size: Pointer to size varible - this function returns the size
  *        specified in the 'reg' property here
  *
- * @return addr
+ * Return: addr
  */
 fdt_addr_t devfdt_get_addr_size_index(const struct udevice *dev, int index,
 				      fdt_size_t *size);
@@ -128,7 +127,7 @@ fdt_addr_t devfdt_get_addr_size_index(const struct udevice *dev, int index,
  *	  'reg-names' property providing named-based identification. @index
  *	  indicates the value to search for in 'reg-names'.
  *
- * @return addr
+ * Return: addr
  */
 fdt_addr_t devfdt_get_addr_name(const struct udevice *dev, const char *name);
 
@@ -145,7 +144,7 @@ fdt_addr_t devfdt_get_addr_name(const struct udevice *dev, const char *name);
  * @size: Pointer to size variable - this function returns the size
  *        specified in the 'reg' property here
  *
- * @return addr
+ * Return: addr
  */
 fdt_addr_t devfdt_get_addr_size_name(const struct udevice *dev,
 				     const char *name, fdt_size_t *size);
@@ -154,7 +153,7 @@ fdt_addr_t devfdt_get_addr_size_name(const struct udevice *dev,
  * devfdt_get_addr_pci() - Read an address and handle PCI address translation
  *
  * @dev: Device to read from
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t devfdt_get_addr_pci(const struct udevice *dev);
 

include/dm/lists.h

@@ -19,13 +19,14 @@
  * for binding a driver given its name and plat.
  *
  * @name: Name of driver to look up
- * @return pointer to driver, or NULL if not found
+ * Return: pointer to driver, or NULL if not found
  */
 struct driver *lists_driver_lookup_name(const char *name);
 
 /**
  * lists_uclass_lookup() - Return uclass_driver based on ID of the class
- * id:		ID of the class
+ *
+ * @id:		ID of the class
  *
  * This function returns the pointer to uclass_driver, which is the class's
  * base structure based on the ID of the class. Returns NULL on error.
@@ -56,7 +57,8 @@ int lists_bind_drivers(struct udevice *parent, bool pre_reloc_only);
  * @drv: if non-NULL, force this driver to be bound
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if device was bound, -EINVAL if the device tree is invalid,
+ *
+ * Return: 0 if device was bound, -EINVAL if the device tree is invalid,
  * other -ve value on error
  */
 int lists_bind_fdt(struct udevice *parent, ofnode node, struct udevice **devp,

include/dm/of.h

@@ -58,14 +58,13 @@ struct device_node {
  * struct of_phandle_args - structure to hold phandle and arguments
  *
  * This is used when decoding a phandle in a device tree property. Typically
- * these look like this:
+ * these look like this::
  *
- * wibble {
+ *   wibble {
- *    phandle = <5>;
+ *     phandle = <5>;
- * };
+ *   };
- *
+ *   ...
- * ...
+ *   some-prop = <&wibble 1 2 3>
- * some-prop = <&wibble 1 2 3>
  *
  * Here &node is the phandle of the node 'wibble', i.e. 5. There are three
  * arguments: 1, 2, 3.

include/dm/of_access.h

@@ -44,7 +44,7 @@ static inline void of_node_put(const struct device_node *np) { }
  * which controls the given node.
  *
  * @np: Node pointer to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int of_n_addr_cells(const struct device_node *np);
 
@@ -55,7 +55,7 @@ int of_n_addr_cells(const struct device_node *np);
  * which controls the given node.
  *
  * @np: Node pointer to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int of_n_size_cells(const struct device_node *np);
 
@@ -65,7 +65,7 @@ int of_n_size_cells(const struct device_node *np);
  * This function matches fdt_address_cells().
  *
  * @np: Node pointer to check
- * @return value of #address-cells property in this node, or 2 if none
+ * Return: value of #address-cells property in this node, or 2 if none
  */
 int of_simple_addr_cells(const struct device_node *np);
 
@@ -75,7 +75,7 @@ int of_simple_addr_cells(const struct device_node *np);
  * This function matches fdt_size_cells().
  *
  * @np: Node pointer to check
- * @return value of #size-cells property in this node, or 2 if none
+ * Return: value of #size-cells property in this node, or 2 if none
  */
 int of_simple_size_cells(const struct device_node *np);
 
@@ -85,7 +85,7 @@ int of_simple_size_cells(const struct device_node *np);
  * @np: Pointer to device node holding property
  * @name: Name of property
  * @lenp: If non-NULL, returns length of property
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 struct property *of_find_property(const struct device_node *np,
 				  const char *name, int *lenp);
@@ -98,7 +98,7 @@ struct property *of_find_property(const struct device_node *np,
  * @np: Pointer to device node holding property
  * @name: Name of property
  * @lenp: If non-NULL, returns length of property
- * @return pointer to property value, or NULL if not found
+ * Return: pointer to property value, or NULL if not found
  */
 const void *of_get_property(const struct device_node *np, const char *name,
 			    int *lenp);
@@ -110,7 +110,7 @@ const void *of_get_property(const struct device_node *np, const char *name,
  * and read all the property with of_get_next_property_by_prop().
  *
  * @np: Pointer to device node
- * @return pointer to property or NULL if not found
+ * Return: pointer to property or NULL if not found
  */
 const struct property *of_get_first_property(const struct device_node *np);
 
@@ -122,7 +122,7 @@ const struct property *of_get_first_property(const struct device_node *np);
  *
  * @np: Pointer to device node
  * @property: pointer of the current property
- * @return pointer to next property or NULL if not found
+ * Return: pointer to next property or NULL if not found
  */
 const struct property *of_get_next_property(const struct device_node *np,
 					    const struct property *property);
@@ -132,11 +132,11 @@ const struct property *of_get_next_property(const struct device_node *np,
  *
  * Get value for the property identified by node and property pointer.
  *
- * @node: node to read
+ * @np: Pointer to device node
  * @property: pointer of the property to read
- * @propname: place to property name on success
+ * @name: place to property name on success
  * @lenp: place to put length on success
- * @return pointer to property value or NULL if error
+ * Return: pointer to property value or NULL if error
  */
 const void *of_get_property_by_prop(const struct device_node *np,
 				    const struct property *property,
@@ -145,7 +145,7 @@ const void *of_get_property_by_prop(const struct device_node *np,
 
 /**
  * of_device_is_compatible() - Check if the node matches given constraints
- * @device: pointer to node
+ * @np: Pointer to device node
  * @compat: required compatible string, NULL or "" for any match
  * @type: required device_type value, NULL or "" for any match
  * @name: required node name, NULL or "" for any match
@@ -154,7 +154,7 @@ const void *of_get_property_by_prop(const struct device_node *np,
  * properties of the given @device. A constraints can be skipped by
  * passing NULL or an empty string as the constraint.
  *
- * @return 0 for no match, and a positive integer on match. The return
+ * Return: 0 for no match, and a positive integer on match. The return
  * value is a relative score with larger values indicating better
  * matches. The score is weighted for the most specific compatible value
  * to get the highest score. Matching type is next, followed by matching
@@ -179,9 +179,9 @@ int of_device_is_compatible(const struct device_node *np, const char *compat,
 /**
  * of_device_is_available() - check if a device is available for use
  *
- * @device: Node to check for availability
+ * @np: Pointer to device node to check for availability
  *
- * @return true if the status property is absent or set to "okay", false
+ * Return: true if the status property is absent or set to "okay", false
  * otherwise
  */
 bool of_device_is_available(const struct device_node *np);
@@ -189,8 +189,8 @@ bool of_device_is_available(const struct device_node *np);
 /**
  * of_get_parent() - Get a node's parent, if any
  *
- * @node: Node to check
+ * @np: Pointer to device node  to check
- * @eturns a node pointer, or NULL if none
+ * Return: a node pointer, or NULL if none
  */
 struct device_node *of_get_parent(const struct device_node *np);
 
@@ -208,7 +208,7 @@ struct device_node *of_get_parent(const struct device_node *np);
  *	foo		Valid alias
  *	foo/bar		Valid alias + relative path
  *
- * @return a node pointer or NULL if not found
+ * Return: a node pointer or NULL if not found
  */
 struct device_node *of_find_node_opts_by_path(const char *path,
 					      const char **opts);
@@ -228,7 +228,7 @@ static inline struct device_node *of_find_node_by_path(const char *path)
  * @type: The type string to match "device_type" or NULL to ignore
  * @compatible:	The string to match to one of the tokens in the device
  *	"compatible" list.
- * @return node pointer or NULL if not found
+ * Return: node pointer or NULL if not found
  */
 struct device_node *of_find_compatible_node(struct device_node *from,
 				const char *type, const char *compatible);
@@ -243,7 +243,7 @@ struct device_node *of_find_compatible_node(struct device_node *from,
  * @propname: property name to check
  * @propval: property value to search for
  * @proplen: length of the value in propval
- * @return node pointer or NULL if not found
+ * Return: node pointer or NULL if not found
  */
 struct device_node *of_find_node_by_prop_value(struct device_node *from,
 					       const char *propname,
@@ -254,7 +254,7 @@ struct device_node *of_find_node_by_prop_value(struct device_node *from,
  *
  * @handle:	phandle of the node to find
  *
- * @return node pointer, or NULL if not found
+ * Return: node pointer, or NULL if not found
  */
 struct device_node *of_find_node_by_phandle(phandle handle);
 
@@ -268,7 +268,7 @@ struct device_node *of_find_node_by_phandle(phandle handle);
  * @propname:	name of the property to be searched.
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @return 0 on success, -EINVAL if the property does not exist,
+ * Return: 0 on success, -EINVAL if the property does not exist,
  * -ENODATA if property does not have a value, and -EOVERFLOW if the
  * property data isn't large enough.
  */
@@ -286,9 +286,10 @@ int of_read_u32(const struct device_node *np, const char *propname, u32 *outp);
  * @index:	index of the u32 in the list of values
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @return 0 on success, -EINVAL if the property does not exist,
+ * Return:
- * -ENODATA if property does not have a value, and -EOVERFLOW if the
+ *   0 on success, -EINVAL if the property does not exist,
- * property data isn't large enough.
+ *   -ENODATA if property does not have a value, and -EOVERFLOW if the
+ *   property data isn't large enough.
  */
 int of_read_u32_index(const struct device_node *np, const char *propname,
 		      int index, u32 *outp);
@@ -303,9 +304,10 @@ int of_read_u32_index(const struct device_node *np, const char *propname,
  * @propname:	name of the property to be searched.
  * @outp:	pointer to return value, modified only if return value is 0.
  *
- * @return 0 on success, -EINVAL if the property does not exist,
+ * Return:
- * -ENODATA if property does not have a value, and -EOVERFLOW if the
+ *   0 on success, -EINVAL if the property does not exist,
- * property data isn't large enough.
+ *   -ENODATA if property does not have a value, and -EOVERFLOW if the
+ *   property data isn't large enough.
  */
 int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
 
@@ -319,8 +321,9 @@ int of_read_u64(const struct device_node *np, const char *propname, u64 *outp);
  * @propname:	name of the property to be searched.
  * @out_values:	pointer to return value, modified only if return value is 0.
  * @sz:		number of array elements to read
- * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
+ * Return:
- * if property does not have a value, and -EOVERFLOW is longer than sz.
+ *   0 on success, -EINVAL if the property does not exist, -ENODATA
+ *   if property does not have a value, and -EOVERFLOW is longer than sz.
  */
 int of_read_u32_array(const struct device_node *np, const char *propname,
 		      u32 *out_values, size_t sz);
@@ -334,8 +337,9 @@ int of_read_u32_array(const struct device_node *np, const char *propname,
  * @np: pointer to node containing string list property
  * @propname: string list property name
  * @string: pointer to string to search for in string list
- * @return 0 on success, -EINVAL if the property does not exist, -ENODATA
+ * Return:
- * if property does not have a value, and -EOVERFLOW is longer than sz.
+ *   0 on success, -EINVAL if the property does not exist, -ENODATA
+ *   if property does not have a value, and -EOVERFLOW is longer than sz.
  */
 int of_property_match_string(const struct device_node *np, const char *propname,
 			     const char *string);
@@ -350,15 +354,17 @@ int of_property_read_string_helper(const struct device_node *np,
  * @np:		device node from which the property value is to be read.
  * @propname:	name of the property to be searched.
  * @index:	index of the string in the list of strings
- * @out_string:	pointer to null terminated return string, modified only if
+ * @output:	pointer to null terminated return string, modified only if
  *		return value is 0.
  *
  * Search for a property in a device tree node and retrieve a null
  * terminated string value (pointer to data, not a copy) in the list of strings
  * contained in that property.
- * Returns 0 on success, -EINVAL if the property does not exist, -ENODATA if
+ *
- * property does not have a value, and -EILSEQ if the string is not
+ * Return:
- * null-terminated within the length of the property data.
+ *   0 on success, -EINVAL if the property does not exist, -ENODATA if
+ *   property does not have a value, and -EILSEQ if the string is not
+ *   null-terminated within the length of the property data.
  *
  * The out_string pointer is modified only if a valid string can be decoded.
  */
@@ -377,10 +383,12 @@ static inline int of_property_read_string_index(const struct device_node *np,
  * @propname:	name of the property to be searched.
  *
  * Search for a property in a device tree node and retrieve the number of null
- * terminated string contain in it. Returns the number of strings on
+ * terminated string contain in it.
- * success, -EINVAL if the property does not exist, -ENODATA if property
+ *
- * does not have a value, and -EILSEQ if the string is not null-terminated
+ * Return:
- * within the length of the property data.
+ *   the number of strings on success, -EINVAL if the property does not exist,
+ *   -ENODATA if property does not have a value, and -EILSEQ if the string is
+ *   not null-terminated within the length of the property data.
  */
 static inline int of_property_count_strings(const struct device_node *np,
 					    const char *propname)
@@ -395,8 +403,9 @@ static inline int of_property_count_strings(const struct device_node *np,
  * @index: For properties holding a table of phandles, this is the index into
  *         the table
  *
- * Returns the device_node pointer with refcount incremented.  Use
+ * Return:
- * of_node_put() on it when done.
+ *   the device_node pointer with refcount incremented.  Use
+ *   of_node_put() on it when done.
  */
 struct device_node *of_parse_phandle(const struct device_node *np,
 				     const char *phandle_name, int index);
@@ -410,10 +419,11 @@ struct device_node *of_parse_phandle(const struct device_node *np,
  * @cells_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
+ * Return:
- *	@list_name does not exist, -EINVAL if a phandle was not found,
+ *   0 on success (with @out_args filled out if not NULL), -ENOENT if
- *	@cells_name could not be found, the arguments were truncated or there
+ *   @list_name does not exist, -EINVAL if a phandle was not found,
- *	were too many arguments.
+ *   @cells_name could not be found, the arguments were truncated or there
+ *   were too many arguments.
  *
  * This function is useful to parse lists of phandles and their arguments.
  * Returns 0 on success and fills out_args, on error returns appropriate
@@ -424,17 +434,17 @@ struct device_node *of_parse_phandle(const struct device_node *np,
  *
  * Example:
  *
- * phandle1: node1 {
+ * .. code-block::
- *	#list-cells = <2>;
- * }
  *
- * phandle2: node2 {
+ *   phandle1: node1 {
- *	#list-cells = <1>;
+ *       #list-cells = <2>;
- * }
+ *   };
- *
+ *   phandle2: node2 {
- * node3 {
+ *       #list-cells = <1>;
- *	list = <&phandle1 1 2 &phandle2 3>;
+ *   };
- * }
+ *   node3 {
+ *       list = <&phandle1 1 2 &phandle2 3>;
+ *   };
  *
  * To get a device_node of the `node2' node you may call this:
  * of_parse_phandle_with_args(node3, "list", "#list-cells", 1, &args);
@@ -451,14 +461,13 @@ int of_parse_phandle_with_args(const struct device_node *np,
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
  * @cells_count: Cell count to use if @cells_name is NULL
- * @return number of phandle found, -ENOENT if
+ * Return:
- *	@list_name does not exist, -EINVAL if a phandle was not found,
+ *   number of phandle found, -ENOENT if @list_name does not exist,
- *	@cells_name could not be found, the arguments were truncated or there
+ *   -EINVAL if a phandle was not found, @cells_name could not be found,
- *	were too many arguments.
+ *   the arguments were truncated or there were too many arguments.
  *
  * Returns number of phandle found on success, on error returns appropriate
  * errno value.
- *
  */
 int of_count_phandle_with_args(const struct device_node *np,
 			       const char *list_name, const char *cells_name,
@@ -471,7 +480,7 @@ int of_count_phandle_with_args(const struct device_node *np,
  * the lookup table with the properties.  It returns the number of alias
  * properties found, or an error code in case of failure.
  *
- * @return 9 if OK, -ENOMEM if not enough memory
+ * Return: 9 if OK, -ENOMEM if not enough memory
  */
 int of_alias_scan(void);
 
@@ -483,7 +492,7 @@ int of_alias_scan(void);
  *
  * @np:		Pointer to the given device_node
  * @stem:	Alias stem of the given device_node
- * @return alias ID, if found, else -ENODEV
+ * Return: alias ID, if found, else -ENODEV
  */
 int of_alias_get_id(const struct device_node *np, const char *stem);
 
@@ -493,14 +502,14 @@ int of_alias_get_id(const struct device_node *np, const char *stem);
  *
  * The function travels the lookup table to get the highest alias id for the
  * given alias stem.
- * @return alias ID, if found, else -1
+ * Return: alias ID, if found, else -1
  */
 int of_alias_get_highest_id(const char *stem);
 
 /**
  * of_get_stdout() - Get node to use for stdout
  *
- * @return node referred to by stdout-path alias, or NULL if none
+ * Return: node referred to by stdout-path alias, or NULL if none
  */
 struct device_node *of_get_stdout(void);
 

include/dm/of_addr.h

@@ -20,11 +20,11 @@
  * that can be mapped to a cpu physical address). This is not really specified
  * that way, but this is traditionally the way IBM at least do things
  *
- * @np: node to check
+ * @np: pointer to node to check
  * @in_addr: pointer to input address
- * @return translated address or OF_BAD_ADDR on error
+ * Return: translated address or OF_BAD_ADDR on error
  */
-u64 of_translate_address(const struct device_node *no, const __be32 *in_addr);
+u64 of_translate_address(const struct device_node *np, const __be32 *in_addr);
 
 /**
  * of_translate_dma_address() - translate a device-tree DMA address to a CPU
@@ -38,11 +38,11 @@ u64 of_translate_address(const struct device_node *no, const __be32 *in_addr);
  * that can be mapped to a cpu physical address). This is not really specified
  * that way, but this is traditionally the way IBM at least do things
  *
- * @np: node to check
+ * @np: ne
  * @in_addr: pointer to input DMA address
- * @return translated DMA address or OF_BAD_ADDR on error
+ * Return: translated DMA address or OF_BAD_ADDR on error
  */
-u64 of_translate_dma_address(const struct device_node *no, const __be32 *in_addr);
+u64 of_translate_dma_address(const struct device_node *np, const __be32 *in_addr);
 
 
 /**
@@ -51,14 +51,13 @@ u64 of_translate_dma_address(const struct device_node *no, const __be32 *in_addr
  * Get DMA ranges for a specifc node, this is useful to perform bus->cpu and
  * cpu->bus address translations
  *
- * @param blob		Pointer to device tree blob
+ * @np:		Pointer to device tree blob
- * @param node_offset	Node DT offset
+ * @cpu:	Pointer to variable storing the range's cpu address
- * @param cpu		Pointer to variable storing the range's cpu address
+ * @bus:	Pointer to variable storing the range's bus address
- * @param bus		Pointer to variable storing the range's bus address
+ * @size:	Pointer to variable storing the range's size
- * @param size		Pointer to variable storing the range's size
+ * Return: translated DMA address or OF_BAD_ADDR on error
- * @return translated DMA address or OF_BAD_ADDR on error
  */
-int of_get_dma_range(const struct device_node *dev, phys_addr_t *cpu,
+int of_get_dma_range(const struct device_node *np, phys_addr_t *cpu,
 		     dma_addr_t *bus, u64 *size);
 
 /**
@@ -72,9 +71,9 @@ int of_get_dma_range(const struct device_node *dev, phys_addr_t *cpu,
  * @index: Index of address to read (0 = first)
  * @size: place to put size on success
  * @flags: place to put flags on success
- * @return pointer to address which can be read
+ * Return: pointer to address which can be read
  */
-const __be32 *of_get_address(const struct device_node *no, int index,
+const __be32 *of_get_address(const struct device_node *np, int index,
 			     u64 *size, unsigned int *flags);
 
 struct resource;
@@ -90,9 +89,9 @@ struct resource;
  * @np: node to check
  * @index: index of address to read (0 = first)
  * @r: place to put resource information
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
-int of_address_to_resource(const struct device_node *no, int index,
+int of_address_to_resource(const struct device_node *np, int index,
 			   struct resource *r);
 
 #endif

include/dm/of_extra.h

@@ -41,11 +41,11 @@ struct fmap_entry {
 };
 
 /**
- * Read a flash entry from the fdt
+ * ofnode_read_fmap_entry() - Read a flash entry from the fdt
  *
- * @param node		Reference to node to read
+ * @node:	Reference to node to read
- * @param entry		Place to put offset and size of this node
+ * @entry:	Place to put offset and size of this node
- * @return 0 if ok, -ve on error
+ * Return: 0 if ok, -ve on error
  */
 int ofnode_read_fmap_entry(ofnode node, struct fmap_entry *entry);
 
@@ -58,11 +58,11 @@ int ofnode_read_fmap_entry(ofnode node, struct fmap_entry *entry);
  * The property must hold one address with a length. This is only tested on
  * 32-bit machines.
  *
- * @param node		ofnode to examine
+ * @node:	ofnode to examine
- * @param prop_name	name of property to find
+ * @prop_name:	name of property to find
- * @param basep		Returns base address of region
+ * @basep:	Returns base address of region
- * @param size		Returns size of region
+ * @sizep:	Returns size of region
- * @return 0 if ok, -1 on error (property not found)
+ * Return: 0 if ok, -1 on error (property not found)
  */
 int ofnode_decode_region(ofnode node, const char *prop_name, fdt_addr_t *basep,
 			 fdt_size_t *sizep);
@@ -81,14 +81,14 @@ int ofnode_decode_region(ofnode node, const char *prop_name, fdt_addr_t *basep,
  * The property value must have an offset and a size. The function checks
  * that the region is entirely within the memory bank.5
  *
- * @param node		ofnode containing the properties (-1 for /config)
+ * @config_node:	ofnode containing the properties (invalid for "/config")
- * @param mem_type	Type of memory to use, which is a name, such as
+ * @mem_type:	Type of memory to use, which is a name, such as
- *			"u-boot" or "kernel".
+ *		"u-boot" or "kernel".
- * @param suffix	String to append to the memory/offset
+ * @suffix:	String to append to the memory/offset
- *			property names
+ *		property names
- * @param basep		Returns base of region
+ * @basep:	Returns base of region
- * @param sizep		Returns size of region
+ * @sizep:	Returns size of region
- * @return 0 if OK, -ive on error
+ * Return: 0 if OK, -ive on error
  */
 int ofnode_decode_memory_region(ofnode config_node, const char *mem_type,
 				const char *suffix, fdt_addr_t *basep,
@@ -102,15 +102,15 @@ int ofnode_decode_memory_region(ofnode config_node, const char *mem_type,
  *
  * This function supports the following two DT bindings:
  * - the new DT binding, where 'fixed-link' is a sub-node of the
- *   Ethernet device
+ * Ethernet device
  * - the old DT binding, where 'fixed-link' is a property with 5
- *   cells encoding various information about the fixed PHY
+ * cells encoding various information about the fixed PHY
  *
  * If both new and old bindings exist, the new one is preferred.
  *
- * @param eth_node	ofnode containing the fixed-link subnode/property
+ * @eth_node:	ofnode containing the fixed-link subnode/property
- * @param phy_node	if fixed-link PHY detected, containing the PHY ofnode
+ * @phy_node:	if fixed-link PHY detected, containing the PHY ofnode
- * @return true if a fixed-link pseudo-PHY device exists, false otherwise
+ * Return: true if a fixed-link pseudo-PHY device exists, false otherwise
  */
 bool ofnode_phy_is_fixed_link(ofnode eth_node, ofnode *phy_node);
 
@@ -123,8 +123,8 @@ bool ofnode_phy_is_fixed_link(ofnode eth_node, ofnode *phy_node);
  * is connected to an on-board PHY or an SFP cage, and is not relevant when it
  * has a fixed link (in that case, in-band autoneg should not be used).
  *
- * @param eth_node	ofnode belonging to the Ethernet controller
+ * @eth_node:	ofnode belonging to the Ethernet controller
- * @return true if in-band autoneg should be used, false otherwise
+ * Return: true if in-band autoneg should be used, false otherwise
  */
 bool ofnode_eth_uses_inband_aneg(ofnode eth_node);
 

include/dm/ofnode.h

@@ -19,7 +19,7 @@
 struct resource;
 
 /**
- * ofnode - reference to a device tree node
+ * typedef union ofnode_union ofnode - reference to a device tree node
  *
  * This union can hold either a straightforward pointer to a struct device_node
  * in the live device tree, or an offset within the flat device tree. In the
@@ -27,7 +27,7 @@ struct resource;
  *
  * Thus we can reference nodes in both the live tree (once available) and the
  * flat tree (until then). Functions are available to translate between an
- * ofnode and either an offset or a struct device_node *.
+ * ofnode and either an offset or a `struct device_node *`.
  *
  * The reference can also hold a null offset, in which case the pointer value
  * here is NULL. This corresponds to a struct device_node * value of
@@ -61,7 +61,7 @@ struct ofnode_phandle_args {
 };
 
 /**
- * ofprop - reference to a property of a device tree node
+ * struct ofprop - reference to a property of a device tree node
  *
  * This struct hold the reference on one property of one node,
  * using struct ofnode and an offset within the flat device tree or either
@@ -91,7 +91,7 @@ struct ofprop {
  * This cannot be called if the reference contains an offset.
  *
  * @node: Reference containing struct device_node * (possibly invalid)
- * @return pointer to device node (can be NULL)
+ * Return: pointer to device node (can be NULL)
  */
 static inline const struct device_node *ofnode_to_np(ofnode node)
 {
@@ -108,7 +108,7 @@ static inline const struct device_node *ofnode_to_np(ofnode node)
  * This cannot be called if the reference contains a node pointer.
  *
  * @node: Reference containing offset (possibly invalid)
- * @return DT offset (can be -1)
+ * Return: DT offset (can be -1)
  */
 static inline int ofnode_to_offset(ofnode node)
 {
@@ -122,7 +122,8 @@ static inline int ofnode_to_offset(ofnode node)
 /**
  * ofnode_valid() - check if an ofnode is valid
  *
- * @return true if the reference contains a valid ofnode, false if it is NULL
+ * @node: Reference containing offset (possibly invalid)
+ * Return: true if the reference contains a valid ofnode, false if it is NULL
  */
 static inline bool ofnode_valid(ofnode node)
 {
@@ -136,7 +137,7 @@ static inline bool ofnode_valid(ofnode node)
  * offset_to_ofnode() - convert a DT offset to an ofnode
  *
  * @of_offset: DT offset (either valid, or -1)
- * @return reference to the associated DT offset
+ * Return: reference to the associated DT offset
  */
 static inline ofnode offset_to_ofnode(int of_offset)
 {
@@ -154,7 +155,7 @@ static inline ofnode offset_to_ofnode(int of_offset)
  * np_to_ofnode() - convert a node pointer to an ofnode
  *
  * @np: Live node pointer (can be NULL)
- * @return reference to the associated node pointer
+ * Return: reference to the associated node pointer
  */
 static inline ofnode np_to_ofnode(const struct device_node *np)
 {
@@ -173,7 +174,7 @@ static inline ofnode np_to_ofnode(const struct device_node *np)
  * is valid is not permitted.
  *
  * @node: reference to check (possibly invalid)
- * @return true if the reference is a live node pointer, false if it is a DT
+ * Return: true if the reference is a live node pointer, false if it is a DT
  * offset
  */
 static inline bool ofnode_is_np(ofnode node)
@@ -193,7 +194,9 @@ static inline bool ofnode_is_np(ofnode node)
 /**
  * ofnode_equal() - check if two references are equal
  *
- * @return true if equal, else false
+ * @ref1: first reference to check (possibly invalid)
+ * @ref2: second reference to check (possibly invalid)
+ * Return: true if equal, else false
  */
 static inline bool ofnode_equal(ofnode ref1, ofnode ref2)
 {
@@ -237,28 +240,28 @@ static inline ofnode ofnode_root(void)
  *
  * @node:	valid node reference that has to be compared
  * @name:	name that has to be compared with the node name
- * @return true if matches, false if it doesn't match
+ * Return: true if matches, false if it doesn't match
  */
 bool ofnode_name_eq(ofnode node, const char *name);
 
 /**
  * ofnode_read_u32() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u32(ofnode node, const char *propname, u32 *outp);
 
 /**
  * ofnode_read_u32_index() - Read a 32-bit integer from a multi-value property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u32_index(ofnode node, const char *propname, int index,
 			  u32 *outp);
@@ -266,47 +269,47 @@ int ofnode_read_u32_index(ofnode node, const char *propname, int index,
 /**
  * ofnode_read_s32() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 static inline int ofnode_read_s32(ofnode node, const char *propname,
-				  s32 *out_value)
+				  s32 *outp)
 {
-	return ofnode_read_u32(node, propname, (u32 *)out_value);
+	return ofnode_read_u32(node, propname, (u32 *)outp);
 }
 
 /**
  * ofnode_read_u32_default() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
-u32 ofnode_read_u32_default(ofnode ref, const char *propname, u32 def);
+u32 ofnode_read_u32_default(ofnode node, const char *propname, u32 def);
 
 /**
  * ofnode_read_u32_index_default() - Read a 32-bit integer from a multi-value
  *                                   property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
-u32 ofnode_read_u32_index_default(ofnode ref, const char *propname, int index,
+u32 ofnode_read_u32_index_default(ofnode node, const char *propname, int index,
 				  u32 def);
 
 /**
  * ofnode_read_s32_default() - Read a 32-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
 
@@ -316,17 +319,17 @@ int ofnode_read_s32_default(ofnode node, const char *propname, s32 def);
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_u64(ofnode node, const char *propname, u64 *outp);
 
 /**
  * ofnode_read_u64_default() - Read a 64-bit integer from a property
  *
- * @ref:	valid node reference to read property from
+ * @node:	valid node reference to read property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
 
@@ -336,8 +339,8 @@ u64 ofnode_read_u64_default(ofnode node, const char *propname, u64 def);
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read
  * @sizep:	if non-NULL, returns the size of the property, or an error code
-		if not found
+ *              if not found
- * @return property value, or NULL if there is no such property
+ * Return: property value, or NULL if there is no such property
  */
 const void *ofnode_read_prop(ofnode node, const char *propname, int *sizep);
 
@@ -346,7 +349,7 @@ const void *ofnode_read_prop(ofnode node, const char *propname, int *sizep);
  *
  * @node:	valid node reference to read property from
  * @propname:	name of the property to read
- * @return string from property value, or NULL if there is no such property
+ * Return: string from property value, or NULL if there is no such property
  */
 const char *ofnode_read_string(ofnode node, const char *propname);
 
@@ -357,7 +360,7 @@ const char *ofnode_read_string(ofnode node, const char *propname);
  * @propname:	name of the property to read
  * @out_values:	pointer to return value, modified only if return value is 0
  * @sz:		number of array elements to read
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  *
  * Search for a property in a device node and read 32-bit value(s) from
  * it. Returns 0 on success, -EINVAL if the property does not exist,
@@ -374,7 +377,7 @@ int ofnode_read_u32_array(ofnode node, const char *propname,
  *
  * @node:	valid node reference to read property from
  * @propname:	name of property to read
- * @return true if property is present (meaning true), false if not present
+ * Return: true if property is present (meaning true), false if not present
  */
 bool ofnode_read_bool(ofnode node, const char *propname);
 
@@ -383,7 +386,7 @@ bool ofnode_read_bool(ofnode node, const char *propname);
  *
  * @node:	valid reference to parent node
  * @subnode_name: name of subnode to find
- * @return reference to subnode (which can be invalid if there is no such
+ * Return: reference to subnode (which can be invalid if there is no such
  * subnode)
  */
 ofnode ofnode_find_subnode(ofnode node, const char *subnode_name);
@@ -429,7 +432,7 @@ static inline ofnode ofnode_next_subnode(ofnode node)
  * by default.
  *
  * @node: node to examine
- * @return false (not enabled) or true (enabled)
+ * Return: false (not enabled) or true (enabled)
  */
 bool ofnode_is_enabled(ofnode node);
 
@@ -437,7 +440,7 @@ bool ofnode_is_enabled(ofnode node);
  * ofnode_first_subnode() - find the first subnode of a parent node
  *
  * @node:	valid reference to a valid parent node
- * @return reference to the first subnode (which can be invalid if the parent
+ * Return: reference to the first subnode (which can be invalid if the parent
  * node has no subnodes)
  */
 ofnode ofnode_first_subnode(ofnode node);
@@ -446,7 +449,7 @@ ofnode ofnode_first_subnode(ofnode node);
  * ofnode_next_subnode() - find the next sibling of a subnode
  *
  * @node:	valid reference to previous node (sibling)
- * @return reference to the next subnode (which can be invalid if the node
+ * Return: reference to the next subnode (which can be invalid if the node
  * has no more siblings)
  */
 ofnode ofnode_next_subnode(ofnode node);
@@ -456,7 +459,7 @@ ofnode ofnode_next_subnode(ofnode node);
  * ofnode_get_parent() - get the ofnode's parent (enclosing ofnode)
  *
  * @node: valid node to look up
- * @return ofnode reference of the parent node
+ * Return: ofnode reference of the parent node
  */
 ofnode ofnode_get_parent(ofnode node);
 
@@ -464,7 +467,7 @@ ofnode ofnode_get_parent(ofnode node);
  * ofnode_get_name() - get the name of a node
  *
  * @node: valid node to look up
- * @return name of node
+ * Return: name of node
  */
 const char *ofnode_get_name(ofnode node);
 
@@ -474,7 +477,7 @@ const char *ofnode_get_name(ofnode node);
  * @node: valid node to look up
  * @buf: buffer to write the node path into
  * @buflen: buffer size
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_get_path(ofnode node, char *buf, int buflen);
 
@@ -482,7 +485,7 @@ int ofnode_get_path(ofnode node, char *buf, int buflen);
  * ofnode_get_by_phandle() - get ofnode from phandle
  *
  * @phandle:	phandle to look up
- * @return ofnode reference to the phandle
+ * Return: ofnode reference to the phandle
  */
 ofnode ofnode_get_by_phandle(uint phandle);
 
@@ -491,7 +494,7 @@ ofnode ofnode_get_by_phandle(uint phandle);
  *
  * @node: node to check
  * @propname: property to check
- * @return size of property if present, or -EINVAL if not
+ * Return: size of property if present, or -EINVAL if not
  */
 int ofnode_read_size(ofnode node, const char *propname);
 
@@ -504,7 +507,7 @@ int ofnode_read_size(ofnode node, const char *propname);
  * @node: node to read from
  * @index: Index of address to read (0 for first)
  * @size: Pointer to size of the address
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_size_index(ofnode node, int index,
 				       fdt_size_t *size);
@@ -521,7 +524,7 @@ phys_addr_t ofnode_get_addr_size_index(ofnode node, int index,
  * @node: node to read from
  * @index: Index of address to read (0 for first)
  * @size: Pointer to size of the address
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_size_index_notrans(ofnode node, int index,
 					       fdt_size_t *size);
@@ -533,7 +536,7 @@ phys_addr_t ofnode_get_addr_size_index_notrans(ofnode node, int index,
  *
  * @node: node to read from
  * @index: Index of address to read (0 for first)
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr_index(ofnode node, int index);
 
@@ -543,7 +546,7 @@ phys_addr_t ofnode_get_addr_index(ofnode node, int index);
  * This reads the register address from a node
  *
  * @node: node to read from
- * @return address, or FDT_ADDR_T_NONE if not present or invalid
+ * Return: address, or FDT_ADDR_T_NONE if not present or invalid
  */
 phys_addr_t ofnode_get_addr(ofnode node);
 
@@ -553,7 +556,7 @@ phys_addr_t ofnode_get_addr(ofnode node);
  * This reads the register size from a node
  *
  * @node: node to read from
- * @return size of the address, or FDT_SIZE_T_NONE if not present or invalid
+ * Return: size of the address, or FDT_SIZE_T_NONE if not present or invalid
  */
 fdt_size_t ofnode_get_size(ofnode node);
 
@@ -570,7 +573,7 @@ fdt_size_t ofnode_get_size(ofnode node);
  * @propname: name of the property containing the string list
  * @string: string to look up in the string list
  *
- * @return:
+ * Return:
  *   the index of the string in the list of strings
  *   -ENODATA if the property is not found
  *   -EINVAL on some other error
@@ -591,9 +594,9 @@ int ofnode_stringlist_search(ofnode node, const char *propname,
  * @node: node to check
  * @propname: name of the property containing the string list
  * @index: index of the string to return (cannot be negative)
- * @lenp: return location for the string length or an error code on failure
+ * @outp: return location for the string
  *
- * @return:
+ * Return:
  *   0 if found or -ve error value if not found
  */
 int ofnode_read_string_index(ofnode node, const char *propname, int index,
@@ -603,8 +606,8 @@ int ofnode_read_string_index(ofnode node, const char *propname, int index,
  * ofnode_read_string_count() - find the number of strings in a string list
  *
  * @node: node to check
- * @propname: name of the property containing the string list
+ * @property: name of the property containing the string list
- * @return:
+ * Return:
  *   number of strings in the list, or -ve error value if not found
  */
 int ofnode_read_string_count(ofnode node, const char *property);
@@ -620,11 +623,12 @@ int ofnode_read_string_count(ofnode node, const char *property);
  * changed as they point directly into the devicetree property.
  *
  * @node: node to check
+ * @property: name of the property containing the string list
  * @listp: returns an allocated, NULL-terminated list of strings if the return
  *	value is > 0, else is set to NULL
- * @return number of strings in list, 0 if none, -ENOMEM if out of memory,
+ * Return:
- *	-EINVAL if no such property, -EENODATA if property is empty
+ * number of strings in list, 0 if none, -ENOMEM if out of memory,
- * @return: NULL-terminated list of strings (NULL if no property or empty)
+ * -EINVAL if no such property, -EENODATA if property is empty
  */
 int ofnode_read_string_list(ofnode node, const char *property,
 			    const char ***listp);
@@ -641,17 +645,17 @@ int ofnode_read_string_list(ofnode node, const char *property,
  *
  * Example:
  *
- * phandle1: node1 {
+ * .. code-block::
- *	#list-cells = <2>;
- * }
  *
- * phandle2: node2 {
+ *   phandle1: node1 {
- *	#list-cells = <1>;
+ *       #list-cells = <2>;
- * }
+ *   };
- *
+ *   phandle2: node2 {
- * node3 {
+ *       #list-cells = <1>;
- *	list = <&phandle1 1 2 &phandle2 3>;
+ *   };
- * }
+ *   node3 {
+ *       list = <&phandle1 1 2 &phandle2 3>;
+ *   };
  *
  * To get a device_node of the `node2' node you may call this:
  * ofnode_parse_phandle_with_args(node3, "list", "#list-cells", 0, 1, &args);
@@ -659,13 +663,14 @@ int ofnode_read_string_list(ofnode node, const char *property,
  * @node:	device tree node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
+ * Return:
- *	@list_name does not exist, -EINVAL if a phandle was not found,
+ *   0 on success (with @out_args filled out if not NULL), -ENOENT if
- *	@cells_name could not be found, the arguments were truncated or there
+ *   @list_name does not exist, -EINVAL if a phandle was not found,
- *	were too many arguments.
+ *   @cells_name could not be found, the arguments were truncated or there
+ *   were too many arguments.
  */
 int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
 				   const char *cells_name, int cell_count,
@@ -682,10 +687,10 @@ int ofnode_parse_phandle_with_args(ofnode node, const char *list_name,
  * @node:	device tree node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
- * @return number of phandle on success, -ENOENT if @list_name does not
+ * Return:
- *      exist, -EINVAL if a phandle was not found, @cells_name could not
+ *   number of phandle on success, -ENOENT if @list_name does not exist,
- *      be found.
+ *   -EINVAL if a phandle was not found, @cells_name could not be found.
  */
 int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
 				   const char *cells_name, int cell_count);
@@ -694,7 +699,7 @@ int ofnode_count_phandle_with_args(ofnode node, const char *list_name,
  * ofnode_path() - find a node by full path
  *
  * @path: Full path to node, e.g. "/bus/spi@1"
- * @return reference to the node found. Use ofnode_valid() to check if it exists
+ * Return: reference to the node found. Use ofnode_valid() to check if it exists
  */
 ofnode ofnode_path(const char *path);
 
@@ -704,9 +709,9 @@ ofnode ofnode_path(const char *path);
  * This looks for a property within the /chosen node and returns its value
  *
  * @propname: Property name to look for
- * @sizep: Returns size of property, or FDT_ERR_... error code if function
+ * @sizep: Returns size of property, or  `FDT_ERR_...` error code if function
  *	returns NULL
- * @return property value if found, else NULL
+ * Return: property value if found, else NULL
  */
 const void *ofnode_read_chosen_prop(const char *propname, int *sizep);
 
@@ -717,7 +722,7 @@ const void *ofnode_read_chosen_prop(const char *propname, int *sizep);
  * checking that it is a valid nul-terminated string
  *
  * @propname: Property name to look for
- * @return string value if found, else NULL
+ * Return: string value if found, else NULL
  */
 const char *ofnode_read_chosen_string(const char *propname);
 
@@ -727,7 +732,8 @@ const char *ofnode_read_chosen_string(const char *propname);
  * This looks up a named property in the chosen node and uses that as a path to
  * look up a code.
  *
- * @return the referenced node if present, else ofnode_null()
+ * @propname: Property name to look for
+ * Return: the referenced node if present, else ofnode_null()
  */
 ofnode ofnode_get_chosen_node(const char *propname);
 
@@ -737,9 +743,9 @@ ofnode ofnode_get_chosen_node(const char *propname);
  * This looks for a property within the /aliases node and returns its value
  *
  * @propname: Property name to look for
- * @sizep: Returns size of property, or FDT_ERR_... error code if function
+ * @sizep: Returns size of property, or `FDT_ERR_...` error code if function
  *	returns NULL
- * @return property value if found, else NULL
+ * Return: property value if found, else NULL
  */
 const void *ofnode_read_aliases_prop(const char *propname, int *sizep);
 
@@ -749,7 +755,8 @@ const void *ofnode_read_aliases_prop(const char *propname, int *sizep);
  * This looks up a named property in the aliases node and uses that as a path to
  * look up a code.
  *
- * @return the referenced node if present, else ofnode_null()
+ * @propname: Property name to look for
+ * Return: the referenced node if present, else ofnode_null()
  */
 ofnode ofnode_get_aliases_node(const char *propname);
 
@@ -761,10 +768,10 @@ struct display_timing;
  * See doc/device-tree-bindings/video/display-timing.txt for binding
  * information.
  *
- * @node	'display-timing' node containing the timing subnodes
+ * @node:	'display-timing' node containing the timing subnodes
- * @index	Index number to read (0=first timing subnode)
+ * @index:	Index number to read (0=first timing subnode)
- * @config	Place to put timings
+ * @config:	Place to put timings
- * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_decode_display_timing(ofnode node, int index,
 				 struct display_timing *config);
@@ -775,7 +782,7 @@ int ofnode_decode_display_timing(ofnode node, int index,
  * @node: node to read
  * @propname: property to read
  * @lenp: place to put length on success
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
 
@@ -787,7 +794,7 @@ const void *ofnode_get_property(ofnode node, const char *propname, int *lenp);
  *
  * @node: node to read
  * @prop: place to put argument reference
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_get_first_property(ofnode node, struct ofprop *prop);
 
@@ -798,7 +805,7 @@ int ofnode_get_first_property(ofnode node, struct ofprop *prop);
  * and read all the property with ofnode_get_property_by_prop().
  *
  * @prop: reference of current argument and place to put reference of next one
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int ofnode_get_next_property(struct ofprop *prop);
 
@@ -810,7 +817,7 @@ int ofnode_get_next_property(struct ofprop *prop);
  * @prop: reference on property
  * @propname: If non-NULL, place to property name on success,
  * @lenp: If non-NULL, place to put length on success
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 const void *ofnode_get_property_by_prop(const struct ofprop *prop,
 					const char **propname, int *lenp);
@@ -819,7 +826,7 @@ const void *ofnode_get_property_by_prop(const struct ofprop *prop,
  * ofnode_is_available() - check if a node is marked available
  *
  * @node: node to check
- * @return true if node's 'status' property is "okay" (or is missing)
+ * Return: true if node's 'status' property is "okay" (or is missing)
  */
 bool ofnode_is_available(ofnode node);
 
@@ -832,7 +839,7 @@ bool ofnode_is_available(ofnode node);
  * @node: node to read from
  * @propname: property to read
  * @sizep: place to put size value (on success)
- * @return address value, or FDT_ADDR_T_NONE on error
+ * Return: address value, or FDT_ADDR_T_NONE on error
  */
 phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
 				 phys_size_t *sizep);
@@ -845,11 +852,12 @@ phys_addr_t ofnode_get_addr_size(ofnode node, const char *propname,
  * for the array (count bytes). It may have more, but this will be ignored.
  * The data is not copied.
  *
- * @node	node to examine
+ * @node:	node to examine
- * @propname	name of property to find
+ * @propname:	name of property to find
- * @sz		number of array elements
+ * @sz:		number of array elements
- * @return pointer to byte array if found, or NULL if the property is not
+ * Return:
- *		found or there is not enough data
+ * pointer to byte array if found, or NULL if the property is not found or
+ * there is not enough data
  */
 const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
 					size_t sz);
@@ -861,13 +869,14 @@ const uint8_t *ofnode_read_u8_array_ptr(ofnode node, const char *propname,
  * corresponds to the given type in the form of fdt_pci_addr.
  * The property must hold one fdt_pci_addr with a lengh.
  *
- * @node	node to examine
+ * @node:	node to examine
- * @type	pci address type (FDT_PCI_SPACE_xxx)
+ * @type:	pci address type (FDT_PCI_SPACE_xxx)
- * @propname	name of property to find
+ * @propname:	name of property to find
- * @addr	returns pci address in the form of fdt_pci_addr
+ * @addr:	returns pci address in the form of fdt_pci_addr
- * @return 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
+ * Return:
- *		format of the property was invalid, -ENXIO if the requested
+ * 0 if ok, -ENOENT if the property did not exist, -EINVAL if the
- *		address type was not found
+ * format of the property was invalid, -ENXIO if the requested
+ * address type was not found
  */
 int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
 			 const char *propname, struct fdt_pci_addr *addr);
@@ -878,10 +887,10 @@ int ofnode_read_pci_addr(ofnode node, enum fdt_pci_space type,
  * Look at the compatible property of a device node that represents a PCI
  * device and extract pci vendor id and device id from it.
  *
- * @param node		node to examine
+ * @node:	node to examine
- * @param vendor	vendor id of the pci device
+ * @vendor:	vendor id of the pci device
- * @param device	device id of the pci device
+ * @device:	device id of the pci device
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
 
@@ -892,7 +901,7 @@ int ofnode_read_pci_vendev(ofnode node, u16 *vendor, u16 *device);
  * which controls the given node.
  *
  * @node: Node to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int ofnode_read_addr_cells(ofnode node);
 
@@ -903,7 +912,7 @@ int ofnode_read_addr_cells(ofnode node);
  * which controls the given node.
  *
  * @node: Node to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int ofnode_read_size_cells(ofnode node);
 
@@ -912,8 +921,8 @@ int ofnode_read_size_cells(ofnode node);
  *
  * This function matches fdt_address_cells().
  *
- * @np: Node pointer to check
+ * @node: Node to check
- * @return value of #address-cells property in this node, or 2 if none
+ * Return: value of #address-cells property in this node, or 2 if none
  */
 int ofnode_read_simple_addr_cells(ofnode node);
 
@@ -922,8 +931,8 @@ int ofnode_read_simple_addr_cells(ofnode node);
  *
  * This function matches fdt_size_cells().
  *
- * @np: Node pointer to check
+ * @node: Node to check
- * @return value of #size-cells property in this node, or 2 if none
+ * Return: value of #size-cells property in this node, or 2 if none
  */
 int ofnode_read_simple_size_cells(ofnode node);
 
@@ -942,14 +951,13 @@ int ofnode_read_simple_size_cells(ofnode node);
  * There are 4 settings currently in use
  * - u-boot,dm-pre-proper: U-Boot proper pre-relocation only
  * - u-boot,dm-pre-reloc: legacy and indicates any of TPL or SPL
- *   Existing platforms only use it to indicate nodes needed in
+ * Existing platforms only use it to indicate nodes needed in
- *   SPL. Should probably be replaced by u-boot,dm-spl for
+ * SPL. Should probably be replaced by u-boot,dm-spl for new platforms.
- *   new platforms.
  * - u-boot,dm-spl: SPL and U-Boot pre-relocation
  * - u-boot,dm-tpl: TPL and U-Boot pre-relocation
  *
  * @node: node to check
- * @return true if node is needed in SPL/TL, false otherwise
+ * Return: true if node is needed in SPL/TL, false otherwise
  */
 bool ofnode_pre_reloc(ofnode node);
 
@@ -961,7 +969,7 @@ bool ofnode_pre_reloc(ofnode node);
  * @node: Node to read from
  * @index: Index of resource to read (0 = first)
  * @res: Returns resource that was read, on success
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_resource(ofnode node, uint index, struct resource *res);
 
@@ -975,7 +983,7 @@ int ofnode_read_resource(ofnode node, uint index, struct resource *res);
  * @node: Node to read from
  * @name: Name of resource to read
  * @res: Returns resource that was read, on success
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int ofnode_read_resource_byname(ofnode node, const char *name,
 				struct resource *res);
@@ -987,7 +995,7 @@ int ofnode_read_resource_byname(ofnode node, const char *name,
  *
  * @from: ofnode to start from (use ofnode_null() to start at the beginning)
  * @compat: Compatible string to match
- * @return ofnode found, or ofnode_null() if none
+ * Return: ofnode found, or ofnode_null() if none
  */
 ofnode ofnode_by_compatible(ofnode from, const char *compat);
 
@@ -998,9 +1006,11 @@ ofnode ofnode_by_compatible(ofnode from, const char *compat);
  * @propval and a length @proplen.
  *
  * @from: ofnode to start from (use ofnode_null() to start at the
- * beginning) @propname: property name to check @propval: property value to
+ * beginning)
- * search for @proplen: length of the value in propval @return ofnode
+ * @propname: property name to check
- * found, or ofnode_null() if none
+ * @propval: property value to search for
+ * @proplen: length of the value in propval
+ * Return: ofnode found, or ofnode_null() if none
  */
 ofnode ofnode_by_prop_value(ofnode from, const char *propname,
 			    const void *propval, int proplen);
@@ -1011,14 +1021,13 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
  * @node:       child node (ofnode, lvalue)
  * @parent:     parent node (ofnode)
  *
- * This is a wrapper around a for loop and is used like so:
+ * This is a wrapper around a for loop and is used like so::
  *
- *	ofnode node;
+ *   ofnode node;
- *
+ *   ofnode_for_each_subnode(node, parent) {
- *	ofnode_for_each_subnode(node, parent) {
+ *       Use node
- *		Use node
+ *       ...
- *		...
+ *   }
- *	}
  *
  * Note that this is implemented as a macro and @node is used as
  * iterator in the loop. The parent variable can be a constant or even a
@@ -1036,14 +1045,13 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
  * @node:       child node (ofnode, lvalue)
  * @compat:     compatible string to match
  *
- * This is a wrapper around a for loop and is used like so:
+ * This is a wrapper around a for loop and is used like so::
  *
- *	ofnode node;
+ *   ofnode node;
- *
+ *   ofnode_for_each_compatible_node(node, parent, compatible) {
- *	ofnode_for_each_compatible_node(node, parent, compatible) {
+ *      Use node
- *		Use node
+ *      ...
- *		...
+ *   }
- *	}
  *
  * Note that this is implemented as a macro and @node is used as
  * iterator in the loop.
@@ -1056,8 +1064,8 @@ ofnode ofnode_by_prop_value(ofnode from, const char *propname,
 /**
  * ofnode_get_child_count() - get the child count of a ofnode
  *
- * @node: valid node to get its child count
+ * @parent: valid node to get its child count
- * @return the number of subnodes
+ * Return: the number of subnodes
  */
 int ofnode_get_child_count(ofnode parent);
 
@@ -1068,10 +1076,9 @@ int ofnode_get_child_count(ofnode parent);
  * function walks up the tree and applies the various bus mappings along the
  * way.
  *
- * @ofnode: Device tree node giving the context in which to translate the
+ * @node: Device tree node giving the context in which to translate the address
- *          address
  * @in_addr: pointer to the address to translate
- * @return the translated address; OF_BAD_ADDR on error
+ * Return: the translated address; OF_BAD_ADDR on error
  */
 u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
 
@@ -1082,10 +1089,10 @@ u64 ofnode_translate_address(ofnode node, const fdt32_t *in_addr);
  * This function walks up the tree and applies the various bus mappings along
  * the way.
  *
- * @ofnode: Device tree node giving the context in which to translate the
+ * @node: Device tree node giving the context in which to translate the
- *          DMA address
+ *        DMA address
  * @in_addr: pointer to the DMA address to translate
- * @return the translated DMA address; OF_BAD_ADDR on error
+ * Return: the translated DMA address; OF_BAD_ADDR on error
  */
 u64 ofnode_translate_dma_address(ofnode node, const fdt32_t *in_addr);
 
@@ -1095,12 +1102,11 @@ u64 ofnode_translate_dma_address(ofnode node, const fdt32_t *in_addr);
  * Get DMA ranges for a specifc node, this is useful to perform bus->cpu and
  * cpu->bus address translations
  *
- * @param blob		Pointer to device tree blob
+ * @node: Device tree node
- * @param node_offset	Node DT offset
+ * @cpu: Pointer to variable storing the range's cpu address
- * @param cpu		Pointer to variable storing the range's cpu address
+ * @bus: Pointer to variable storing the range's bus address
- * @param bus		Pointer to variable storing the range's bus address
+ * @size: Pointer to variable storing the range's size
- * @param size		Pointer to variable storing the range's size
+ * Return: translated DMA address or OF_BAD_ADDR on error
- * @return translated DMA address or OF_BAD_ADDR on error
  */
 int ofnode_get_dma_range(ofnode node, phys_addr_t *cpu, dma_addr_t *bus,
 			 u64 *size);
@@ -1112,7 +1118,7 @@ int ofnode_get_dma_range(ofnode node, phys_addr_t *cpu, dma_addr_t *bus,
  *
  * @node:	Device tree node for which compatible needs to be verified.
  * @compat:	Compatible string which needs to verified in the given node.
- * @return true if OK, false if the compatible is not found
+ * Return: true if OK, false if the compatible is not found
  */
 int ofnode_device_is_compatible(ofnode node, const char *compat);
 
@@ -1127,7 +1133,7 @@ int ofnode_device_is_compatible(ofnode node, const char *compat);
  * @len:	The length of the new value of the property
  * @value:	The new value of the property (must be valid prior to calling
  *		the function)
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_write_prop(ofnode node, const char *propname, int len,
 		      const void *value);
@@ -1142,7 +1148,7 @@ int ofnode_write_prop(ofnode node, const char *propname, int len,
  * @propname:	The name of the string property to set
  * @value:	The new value of the string property (must be valid prior to
  *		calling the function)
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_write_string(ofnode node, const char *propname, const char *value);
 
@@ -1157,7 +1163,7 @@ int ofnode_write_string(ofnode node, const char *propname, const char *value);
  * @node:	The node to enable
  * @value:	Flag that tells the function to either disable or enable the
  *		node
- * @return 0 if successful, -ve on error
+ * Return: 0 if successful, -ve on error
  */
 int ofnode_set_enabled(ofnode node, bool value);
 
@@ -1168,8 +1174,8 @@ int ofnode_set_enabled(ofnode node, bool value);
  *
  * See doc/config.txt for bindings
  *
- * @prop_name	property name to look up
+ * @prop_name:	property name to look up
- * @return true, if it exists, false if not
+ * Return: true, if it exists, false if not
  */
 bool ofnode_conf_read_bool(const char *prop_name);
 
@@ -1182,7 +1188,7 @@ bool ofnode_conf_read_bool(const char *prop_name);
  *
  * @prop_name: property name to look up
  * @default_val: default value to return if the property is not found
- * @return integer value, if found, or @default_val if not
+ * Return: integer value, if found, or @default_val if not
  */
 int ofnode_conf_read_int(const char *prop_name, int default_val);
 
@@ -1194,7 +1200,7 @@ int ofnode_conf_read_int(const char *prop_name, int default_val);
  * See doc/config.txt for bindings
  *
  * @prop_name: property name to look up
- * @return string value, if found, or NULL if not
+ * Return: string value, if found, or NULL if not
  */
 const char *ofnode_conf_read_str(const char *prop_name);
 

include/dm/platdata.h

@@ -40,7 +40,7 @@ struct driver_info {
 #endif
 
 /**
- * driver_rt - runtime information set up by U-Boot
+ * struct driver_rt - runtime information set up by U-Boot
  *
  * There is one of these for every driver_info in the linker list, indexed by
  * the driver_info idx value.
@@ -51,7 +51,7 @@ struct driver_rt {
 	struct udevice *dev;
 };
 
-/**
+/*
  * NOTE: Avoid using these except in extreme circumstances, where device tree
  * is not feasible (e.g. serial driver in SPL where <8KB of SRAM is
  * available). U-Boot's driver model uses device tree for configuration.

include/dm/read.h

@@ -37,7 +37,7 @@ static inline const struct device_node *dev_np(const struct udevice *dev)
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32(const struct udevice *dev, const char *propname, u32 *outp);
 
@@ -47,7 +47,7 @@ int dev_read_u32(const struct udevice *dev, const char *propname, u32 *outp);
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int dev_read_u32_default(const struct udevice *dev, const char *propname,
 			 int def);
@@ -60,7 +60,7 @@ int dev_read_u32_default(const struct udevice *dev, const char *propname,
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32_index(struct udevice *dev, const char *propname, int index,
 		       u32 *outp);
@@ -73,7 +73,7 @@ int dev_read_u32_index(struct udevice *dev, const char *propname, int index,
  * @propname:	name of the property to read from
  * @index:	index of the integer to return
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u32 dev_read_u32_index_default(struct udevice *dev, const char *propname,
 			       int index, u32 def);
@@ -84,7 +84,7 @@ u32 dev_read_u32_index_default(struct udevice *dev, const char *propname,
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_s32(const struct udevice *dev, const char *propname, s32 *outp);
 
@@ -94,7 +94,7 @@ int dev_read_s32(const struct udevice *dev, const char *propname, s32 *outp);
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @def:	default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 int dev_read_s32_default(const struct udevice *dev, const char *propname,
 			 int def);
@@ -107,7 +107,7 @@ int dev_read_s32_default(const struct udevice *dev, const char *propname,
  * @dev:	device to read DT property from
  * @propname:	name of the property to read from
  * @outp:	place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u32u(const struct udevice *dev, const char *propname, uint *outp);
 
@@ -117,7 +117,7 @@ int dev_read_u32u(const struct udevice *dev, const char *propname, uint *outp);
  * @dev:        device to read DT property from
  * @propname:   name of the property to read from
  * @outp:       place to put value (if found)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dev_read_u64(const struct udevice *dev, const char *propname, u64 *outp);
 
@@ -127,7 +127,7 @@ int dev_read_u64(const struct udevice *dev, const char *propname, u64 *outp);
  * @dev:        device to read DT property from
  * @propname:   name of the property to read from
  * @def:        default value to return if the property has no value
- * @return property value, or @def if not found
+ * Return: property value, or @def if not found
  */
 u64 dev_read_u64_default(const struct udevice *dev, const char *propname,
 			 u64 def);
@@ -137,7 +137,7 @@ u64 dev_read_u64_default(const struct udevice *dev, const char *propname,
  *
  * @dev:	device to read DT property from
  * @propname:	name of the property to read
- * @return string from property value, or NULL if there is no such property
+ * Return: string from property value, or NULL if there is no such property
  */
 const char *dev_read_string(const struct udevice *dev, const char *propname);
 
@@ -146,7 +146,7 @@ const char *dev_read_string(const struct udevice *dev, const char *propname);
  *
  * @dev:	device to read DT property from
  * @propname:	name of property to read
- * @return true if property is present (meaning true), false if not present
+ * Return: true if property is present (meaning true), false if not present
  */
 bool dev_read_bool(const struct udevice *dev, const char *propname);
 
@@ -155,17 +155,17 @@ bool dev_read_bool(const struct udevice *dev, const char *propname);
  *
  * @dev:	device whose DT node contains the subnode
  * @subnode_name: name of subnode to find
- * @return reference to subnode (which can be invalid if there is no such
+ * Return: reference to subnode (which can be invalid if there is no such
  * subnode)
  */
-ofnode dev_read_subnode(const struct udevice *dev, const char *subbnode_name);
+ofnode dev_read_subnode(const struct udevice *dev, const char *subnode_name);
 
 /**
  * dev_read_size() - read the size of a property
  *
  * @dev: device to check
  * @propname: property to check
- * @return size of property if present, or -EINVAL if not
+ * Return: size of property if present, or -EINVAL if not
  */
 int dev_read_size(const struct udevice *dev, const char *propname);
 
@@ -176,7 +176,7 @@ int dev_read_size(const struct udevice *dev, const char *propname);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_index(const struct udevice *dev, int index);
 
@@ -188,7 +188,7 @@ fdt_addr_t dev_read_addr_index(const struct udevice *dev, int index);
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_read_addr_index_ptr(const struct udevice *dev, int index);
 
@@ -200,7 +200,7 @@ void *dev_read_addr_index_ptr(const struct udevice *dev, int index);
  *	   and @index is used to select which one is required
  * @size: place to put size value (on success)
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_size_index(const struct udevice *dev, int index,
 				    fdt_size_t *size);
@@ -213,7 +213,7 @@ fdt_addr_t dev_read_addr_size_index(const struct udevice *dev, int index,
  * @index: the 'reg' property can hold a list of <addr, size> pairs
  *	   and @index is used to select which one is required
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr_index(const struct udevice *dev, int index);
 
@@ -225,7 +225,7 @@ void *dev_remap_addr_index(const struct udevice *dev, int index);
  *	  'reg-names' property providing named-based identification. @index
  *	  indicates the value to search for in 'reg-names'.
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_name(const struct udevice *dev, const char *name);
 
@@ -238,7 +238,7 @@ fdt_addr_t dev_read_addr_name(const struct udevice *dev, const char *name);
  *	  indicates the value to search for in 'reg-names'.
  *  @size: place to put size value (on success)
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_size_name(const struct udevice *dev, const char *name,
 				   fdt_size_t *size);
@@ -252,7 +252,7 @@ fdt_addr_t dev_read_addr_size_name(const struct udevice *dev, const char *name,
  *	  'reg-names' property providing named-based identification. @index
  *	  indicates the value to search for in 'reg-names'.
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr_name(const struct udevice *dev, const char *name);
 
@@ -261,7 +261,7 @@ void *dev_remap_addr_name(const struct udevice *dev, const char *name);
  *
  * @dev: Device to read from
  *
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr(const struct udevice *dev);
 
@@ -271,7 +271,7 @@ fdt_addr_t dev_read_addr(const struct udevice *dev);
  *
  * @dev: Device to read from
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_read_addr_ptr(const struct udevice *dev);
 
@@ -291,7 +291,7 @@ void *dev_read_addr_ptr(const struct udevice *dev);
  *    fdtdec_get_addr() and friends.
  *
  * @dev: Device to read from
- * @return address or FDT_ADDR_T_NONE if not found
+ * Return: address or FDT_ADDR_T_NONE if not found
  */
 fdt_addr_t dev_read_addr_pci(const struct udevice *dev);
 
@@ -301,7 +301,7 @@ fdt_addr_t dev_read_addr_pci(const struct udevice *dev);
  *
  * @dev: Device to read from
  *
- * @return pointer or NULL if not found
+ * Return: pointer or NULL if not found
  */
 void *dev_remap_addr(const struct udevice *dev);
 
@@ -314,7 +314,7 @@ void *dev_remap_addr(const struct udevice *dev);
  * @dev: Device to read from
  * @propname: property to read
  * @sizep: place to put size value (on success)
- * @return address value, or FDT_ADDR_T_NONE on error
+ * Return: address value, or FDT_ADDR_T_NONE on error
  */
 fdt_addr_t dev_read_addr_size(const struct udevice *dev, const char *propname,
 			      fdt_size_t *sizep);
@@ -323,7 +323,7 @@ fdt_addr_t dev_read_addr_size(const struct udevice *dev, const char *propname,
  * dev_read_name() - get the name of a device's node
  *
  * @dev: Device to read from
- * @return name of node
+ * Return: name of node
  */
 const char *dev_read_name(const struct udevice *dev);
 
@@ -340,12 +340,12 @@ const char *dev_read_name(const struct udevice *dev);
  * @propname: name of the property containing the string list
  * @string: string to look up in the string list
  *
- * @return:
+ * Return:
  *   the index of the string in the list of strings
  *   -ENODATA if the property is not found
  *   -EINVAL on some other error
  */
-int dev_read_stringlist_search(const struct udevice *dev, const char *property,
+int dev_read_stringlist_search(const struct udevice *dev, const char *propname,
 			       const char *string);
 
 /**
@@ -354,9 +354,9 @@ int dev_read_stringlist_search(const struct udevice *dev, const char *property,
  * @dev: device to examine
  * @propname: name of the property containing the string list
  * @index: index of the string to return
- * @out: return location for the string
+ * @outp: return location for the string
  *
- * @return:
+ * Return:
  *   length of string, if found or -ve error value if not found
  */
 int dev_read_string_index(const struct udevice *dev, const char *propname,
@@ -367,7 +367,7 @@ int dev_read_string_index(const struct udevice *dev, const char *propname,
  *
  * @dev: device to examine
  * @propname: name of the property containing the string list
- * @return:
+ * Return:
  *   number of strings in the list, or -ve error value if not found
  */
 int dev_read_string_count(const struct udevice *dev, const char *propname);
@@ -386,8 +386,9 @@ int dev_read_string_count(const struct udevice *dev, const char *propname);
  * @propname: name of the property containing the string list
  * @listp: returns an allocated, NULL-terminated list of strings if the return
  *	value is > 0, else is set to NULL
- * @return number of strings in list, 0 if none, -ENOMEM if out of memory,
+ * Return:
- *	-ENOENT if no such property
+ * number of strings in list, 0 if none, -ENOMEM if out of memory,
+ * -ENOENT if no such property
  */
 int dev_read_string_list(const struct udevice *dev, const char *propname,
 			 const char ***listp);
@@ -404,17 +405,17 @@ int dev_read_string_list(const struct udevice *dev, const char *propname,
  *
  * Example:
  *
- * phandle1: node1 {
+ * .. code-block::
- *	#list-cells = <2>;
- * }
  *
- * phandle2: node2 {
+ *   phandle1: node1 {
- *	#list-cells = <1>;
+ *       #list-cells = <2>;
- * }
+ *   };
- *
+ *   phandle2: node2 {
- * node3 {
+ *       #list-cells = <1>;
- *	list = <&phandle1 1 2 &phandle2 3>;
+ *   };
- * }
+ *   node3 {
+ *       list = <&phandle1 1 2 &phandle2 3>;
+ *   };
  *
  * To get a device_node of the `node2' node you may call this:
  * dev_read_phandle_with_args(dev, "list", "#list-cells", 0, 1, &args);
@@ -422,10 +423,10 @@ int dev_read_string_list(const struct udevice *dev, const char *propname,
  * @dev:	device whose node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
  * @index:	index of a phandle to parse out
  * @out_args:	optional pointer to output arguments structure (will be filled)
- * @return 0 on success (with @out_args filled out if not NULL), -ENOENT if
+ * Return: 0 on success (with @out_args filled out if not NULL), -ENOENT if
  *	@list_name does not exist, -EINVAL if a phandle was not found,
  *	@cells_name could not be found, the arguments were truncated or there
  *	were too many arguments.
@@ -441,12 +442,11 @@ int dev_read_phandle_with_args(const struct udevice *dev, const char *list_name,
  * For example, this allows to allocate the right amount of memory to keep
  * clock's reference contained into the "clocks" property.
  *
- *
  * @dev:	device whose node containing a list
  * @list_name:	property name that contains a list
  * @cells_name:	property name that specifies phandles' arguments count
- * @cells_count: Cell count to use if @cells_name is NULL
+ * @cell_count: Cell count to use if @cells_name is NULL
- * @Returns number of phandle found on success, on error returns appropriate
+ * Return: number of phandle found on success, on error returns appropriate
  * errno value.
  */
 
@@ -461,7 +461,7 @@ int dev_count_phandle_with_args(const struct udevice *dev,
  * which controls the given node.
  *
  * @dev: device to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int dev_read_addr_cells(const struct udevice *dev);
 
@@ -472,7 +472,7 @@ int dev_read_addr_cells(const struct udevice *dev);
  * which controls the given node.
  *
  * @dev: device to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int dev_read_size_cells(const struct udevice *dev);
 
@@ -482,7 +482,7 @@ int dev_read_size_cells(const struct udevice *dev);
  * This function matches fdt_address_cells().
  *
  * @dev: device to check
- * @return number of address cells this node uses
+ * Return: number of address cells this node uses
  */
 int dev_read_simple_addr_cells(const struct udevice *dev);
 
@@ -492,7 +492,7 @@ int dev_read_simple_addr_cells(const struct udevice *dev);
  * This function matches fdt_size_cells().
  *
  * @dev: device to check
- * @return number of size cells this node uses
+ * Return: number of size cells this node uses
  */
 int dev_read_simple_size_cells(const struct udevice *dev);
 
@@ -500,7 +500,7 @@ int dev_read_simple_size_cells(const struct udevice *dev);
  * dev_read_phandle() - Get the phandle from a device
  *
  * @dev: device to check
- * @return phandle (1 or greater), or 0 if no phandle or other error
+ * Return: phandle (1 or greater), or 0 if no phandle or other error
  */
 int dev_read_phandle(const struct udevice *dev);
 
@@ -510,7 +510,7 @@ int dev_read_phandle(const struct udevice *dev);
  * @dev: device to check
  * @propname: property to read
  * @lenp: place to put length on success
- * @return pointer to property, or NULL if not found
+ * Return: pointer to property, or NULL if not found
  */
 const void *dev_read_prop(const struct udevice *dev, const char *propname,
 			  int *lenp);
@@ -523,7 +523,7 @@ const void *dev_read_prop(const struct udevice *dev, const char *propname,
  *
  * @dev: device to check
  * @prop: place to put argument reference
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int dev_read_first_prop(const struct udevice *dev, struct ofprop *prop);
 
@@ -534,7 +534,7 @@ int dev_read_first_prop(const struct udevice *dev, struct ofprop *prop);
  * and read all the property with dev_read_prop_by_prop().
  *
  * @prop: reference of current argument and place to put reference of next one
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 int dev_read_next_prop(struct ofprop *prop);
 
@@ -546,7 +546,7 @@ int dev_read_next_prop(struct ofprop *prop);
  * @prop: reference on property
  * @propname: If non-NULL, place to property name on success,
  * @lenp: If non-NULL, place to put length on success
- * @return 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -ve on error. -FDT_ERR_NOTFOUND if not found
  */
 const void *dev_read_prop_by_prop(struct ofprop *prop,
 				  const char **propname, int *lenp);
@@ -560,7 +560,7 @@ const void *dev_read_prop_by_prop(struct ofprop *prop,
  *
  * @dev: device to look up
  * @devnump: set to the sequence number if one is found
- * @return 0 if a sequence was found, -ve if not
+ * Return: 0 if a sequence was found, -ve if not
  */
 int dev_read_alias_seq(const struct udevice *dev, int *devnump);
 
@@ -576,7 +576,7 @@ int dev_read_alias_seq(const struct udevice *dev, int *devnump);
  * @propname:	name of the property to read
  * @out_values:	pointer to return value, modified only if return value is 0
  * @sz:		number of array elements to read
- * @return 0 on success, -EINVAL if the property does not exist, -ENODATA if
+ * Return: 0 on success, -EINVAL if the property does not exist, -ENODATA if
  * property does not have a value, and -EOVERFLOW if the property data isn't
  * large enough.
  */
@@ -587,7 +587,7 @@ int dev_read_u32_array(const struct udevice *dev, const char *propname,
  * dev_read_first_subnode() - find the first subnode of a device's node
  *
  * @dev: device to look up
- * @return reference to the first subnode (which can be invalid if the device's
+ * Return: reference to the first subnode (which can be invalid if the device's
  * node has no subnodes)
  */
 ofnode dev_read_first_subnode(const struct udevice *dev);
@@ -596,7 +596,7 @@ ofnode dev_read_first_subnode(const struct udevice *dev);
  * ofnode_next_subnode() - find the next sibling of a subnode
  *
  * @node:	valid reference to previous node (sibling)
- * @return reference to the next subnode (which can be invalid if the node
+ * Return: reference to the next subnode (which can be invalid if the node
  * has no more siblings)
  */
 ofnode dev_read_next_subnode(ofnode node);
@@ -612,8 +612,9 @@ ofnode dev_read_next_subnode(ofnode node);
  * @dev: device to look up
  * @propname: name of property to find
  * @sz: number of array elements
- * @return pointer to byte array if found, or NULL if the property is not
+ * Return:
- *		found or there is not enough data
+ * pointer to byte array if found, or NULL if the property is not found or
+ * there is not enough data
  */
 const uint8_t *dev_read_u8_array_ptr(const struct udevice *dev,
 				     const char *propname, size_t sz);
@@ -627,7 +628,7 @@ const uint8_t *dev_read_u8_array_ptr(const struct udevice *dev,
  * by default.
  *
  * @dev: device to examine
- * @return integer value 0 (not enabled) or 1 (enabled)
+ * Return: integer value 0 (not enabled) or 1 (enabled)
  */
 int dev_read_enabled(const struct udevice *dev);
 
@@ -635,9 +636,9 @@ int dev_read_enabled(const struct udevice *dev);
  * dev_read_resource() - obtain an indexed resource from a device.
  *
  * @dev: device to examine
- * @index index of the resource to retrieve (0 = first)
+ * @index: index of the resource to retrieve (0 = first)
- * @res returns the resource
+ * @res: returns the resource
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_read_resource(const struct udevice *dev, uint index,
 		      struct resource *res);
@@ -648,7 +649,7 @@ int dev_read_resource(const struct udevice *dev, uint index,
  * @dev: device to examine
  * @name: name of the resource to retrieve
  * @res: returns the resource
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_read_resource_byname(const struct udevice *dev, const char *name,
 			     struct resource *res);
@@ -662,7 +663,7 @@ int dev_read_resource_byname(const struct udevice *dev, const char *name,
  *
  * @dev: device giving the context in which to translate the address
  * @in_addr: pointer to the address to translate
- * @return the translated address; OF_BAD_ADDR on error
+ * Return: the translated address; OF_BAD_ADDR on error
  */
 u64 dev_translate_address(const struct udevice *dev, const fdt32_t *in_addr);
 
@@ -675,7 +676,7 @@ u64 dev_translate_address(const struct udevice *dev, const fdt32_t *in_addr);
  *
  * @dev: device giving the context in which to translate the DMA address
  * @in_addr: pointer to the DMA address to translate
- * @return the translated DMA address; OF_BAD_ADDR on error
+ * Return: the translated DMA address; OF_BAD_ADDR on error
  */
 u64 dev_translate_dma_address(const struct udevice *dev,
 			      const fdt32_t *in_addr);
@@ -690,7 +691,7 @@ u64 dev_translate_dma_address(const struct udevice *dev,
  * @cpu: base address for CPU's view of memory
  * @bus: base address for BUS's view of memory
  * @size: size of the address space
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_get_dma_range(const struct udevice *dev, phys_addr_t *cpu,
 		      dma_addr_t *bus, u64 *size);
@@ -701,15 +702,15 @@ int dev_get_dma_range(const struct udevice *dev, phys_addr_t *cpu,
  *
  * The function travels the lookup table to get the highest alias id for the
  * given alias stem.
- * @return alias ID, if found, else -1
+ * Return: alias ID, if found, else -1
  */
 int dev_read_alias_highest_id(const char *stem);
 
 /**
  * dev_get_child_count() - get the child count of a device
  *
- * @dev: device to use for interation (struct udevice *)
+ * @dev: device to use for interation (`struct udevice *`)
- * @return the count of child subnode
+ * Return: the count of child subnode
  */
 int dev_get_child_count(const struct udevice *dev);
 
@@ -720,8 +721,8 @@ int dev_get_child_count(const struct udevice *dev);
  * range for this node.
  *
  * @dev: device to examine
- * @res returns the resource
+ * @res: returns the resource
- * @return 0 if ok, negative on error
+ * Return: 0 if ok, negative on error
  */
 int dev_read_pci_bus_range(const struct udevice *dev, struct resource *res);
 
@@ -737,7 +738,7 @@ int dev_read_pci_bus_range(const struct udevice *dev, struct resource *res);
  *       one or more display timing nodes.
  * @index: index number to read (0=first timing subnode)
  * @config: place to put timings
- * @return 0 if OK, -FDT_ERR_NOTFOUND if not found
+ * Return: 0 if OK, -FDT_ERR_NOTFOUND if not found
  */
 int dev_decode_display_timing(const struct udevice *dev, int index,
 			      struct display_timing *config);
@@ -1100,7 +1101,7 @@ static inline int dev_decode_display_timing(const struct udevice *dev,
  * device-tree node.
  *
  * @subnode: ofnode holding the current subnode
- * @dev: device to use for interation (struct udevice *)
+ * @dev: device to use for interation (`struct udevice *`)
  */
 #define dev_for_each_subnode(subnode, dev) \
 	for (subnode = dev_read_first_subnode(dev); \
@@ -1114,7 +1115,7 @@ static inline int dev_decode_display_timing(const struct udevice *dev,
  * device-tree node.
  *
  * @prop: struct ofprop holding the current property
- * @dev: device to use for interation (struct udevice *)
+ * @dev: device to use for interation (`struct udevice *`)
  */
 #define dev_for_each_property(prop, dev) \
 	for (int ret_prop = dev_read_first_prop(dev, &prop); \

include/dm/root.h

@@ -19,7 +19,7 @@ extern struct list_head uclass_head;
  *
  * This function returns pointer to the root node of the driver tree,
  *
- * @return pointer to root device, or NULL if not inited yet
+ * Return: pointer to root device, or NULL if not inited yet
  */
 struct udevice *dm_root(void);
 
@@ -27,6 +27,8 @@ struct global_data;
 /**
  * dm_fixup_for_gd_move() - Handle global_data moving to a new place
  *
+ * @new_gd: Pointer to the new global data
+ *
  * The uclass list is part of global_data. Due to the way lists work, moving
  * the list will cause it to become invalid. This function fixes that up so
  * that the uclass list will work correctly.
@@ -40,7 +42,7 @@ void dm_fixup_for_gd_move(struct global_data *new_gd);
  *
  * @pre_reloc_only: If true, bind only drivers with the DM_FLAG_PRE_RELOC
  * flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_plat(bool pre_reloc_only);
 
@@ -52,7 +54,7 @@ int dm_scan_plat(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_fdt(bool pre_reloc_only);
 
@@ -65,7 +67,7 @@ int dm_scan_fdt(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_extended_scan(bool pre_reloc_only);
 
@@ -79,7 +81,7 @@ int dm_extended_scan(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_scan_other(bool pre_reloc_only);
 
@@ -92,7 +94,7 @@ int dm_scan_other(bool pre_reloc_only);
  *
  * @pre_reloc_only: If true, bind only nodes with special devicetree properties,
  * or drivers with the DM_FLAG_PRE_RELOC flag. If false bind all drivers.
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_init_and_scan(bool pre_reloc_only);
 
@@ -103,7 +105,7 @@ int dm_init_and_scan(bool pre_reloc_only);
  * This needs to be called before anything uses the DM
  *
  * @of_live:	Enable live device tree
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_init(bool of_live);
 
@@ -111,7 +113,7 @@ int dm_init(bool of_live);
  * dm_uninit - Uninitialise Driver Model structures
  *
  * All devices will be removed and unbound
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_uninit(void);
 
@@ -124,7 +126,7 @@ int dm_uninit(void);
  * All devices with the matching flags set will be removed
  *
  * @flags: Flags for selective device removal
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int dm_remove_devices_flags(uint flags);
 #else

include/dm/uclass.h

@@ -84,7 +84,7 @@ struct udevice;
  * its children. If non-zero this is the size of this data, to be allocated
  * in the child device's parent_plat pointer. This value is only used as
  * a fallback if this member is 0 in the driver.
- * @flags: Flags for this uclass (DM_UC_...)
+ * @flags: Flags for this uclass ``(DM_UC_...)``
  */
 struct uclass_driver {
 	const char *name;
@@ -127,17 +127,16 @@ struct uclass_driver {
  * build time. Before this is used, an extern UCLASS_DRIVER() must have been
  * declared.
  *
- * For example:
+ * For example::
  *
- * extern UCLASS_DRIVER(clk);
+ *   extern UCLASS_DRIVER(clk);
- *
+ *   struct uclass_driver *drvs[] = {
- * struct uclass_driver *drvs[] = {
+ *       DM_UCLASS_DRIVER_REF(clk),
- *	DM_UCLASS_DRIVER_REF(clk),
+ *   };
- * };
  *
  * @_name: Name of the uclass_driver. This must be a valid C identifier, used by
  *	the linker_list.
- * @returns struct uclass_driver * for the uclass driver
+ * Return: struct uclass_driver * for the uclass driver
  */
 #define DM_UCLASS_DRIVER_REF(_name)					\
 	ll_entry_ref(struct uclass_driver, _name, uclass_driver)
@@ -145,8 +144,8 @@ struct uclass_driver {
 /**
  * uclass_get_priv() - Get the private data for a uclass
  *
- * @uc		Uclass to check
+ * @uc:	Uclass to check
- * @return private data, or NULL if none
+ * Return: private data, or NULL if none
  */
 void *uclass_get_priv(const struct uclass *uc);
 
@@ -159,8 +158,9 @@ void *uclass_get_priv(const struct uclass *uc);
  *
  * @key: ID to look up
  * @ucp: Returns pointer to uclass (there is only one per ID)
- * @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
+ * Return:
- *	other error
+ * 0 if OK, -EDEADLK if driver model is not yet inited,
+ * other -ve on other error
  */
 int uclass_get(enum uclass_id key, struct uclass **ucp);
 
@@ -168,16 +168,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
  * uclass_get_name() - Get the name of a uclass driver
  *
  * @id: ID to look up
- * @returns the name of the uclass driver for that ID, or NULL if none
+ * Return: the name of the uclass driver for that ID, or NULL if none
  */
 const char *uclass_get_name(enum uclass_id id);
 
 /**
- * uclass_get_by_name() - Look up a uclass by its driver name
+ * uclass_get_by_name_len() - Look up a uclass by its partial driver name
  *
  * @name: Name to look up
- * @len: Length of name
+ * @len: Length of the partial name
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
  */
 enum uclass_id uclass_get_by_name_len(const char *name, int len);
 
@@ -185,7 +185,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int len);
  * uclass_get_by_name() - Look up a uclass by its driver name
  *
  * @name: Name to look up
- * @returns the associated uclass ID, or UCLASS_INVALID if not found
+ * Return: the associated uclass ID, or UCLASS_INVALID if not found
  */
 enum uclass_id uclass_get_by_name(const char *name);
 
@@ -197,7 +197,7 @@ enum uclass_id uclass_get_by_name(const char *name);
  * @id: ID to look up
  * @index: Device number within that uclass (0=first)
  * @devp: Returns pointer to device (there is only one per for each ID)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
 
@@ -211,7 +211,7 @@ int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
  * @id: ID to look up
  * @name: name of a device to get
  * @devp: Returns pointer to device (the first one with the name)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_name(enum uclass_id id, const char *name,
 			      struct udevice **devp);
@@ -228,7 +228,7 @@ int uclass_get_device_by_name(enum uclass_id id, const char *name,
  * @id: ID to look up
  * @seq: Sequence number to find (0=first)
  * @devp: Returns pointer to device (there is only one for each seq)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
 
@@ -243,7 +243,7 @@ int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
  * @id: ID to look up
  * @node: Device tree offset to search for (if -ve then -ENODEV is returned)
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_of_offset(enum uclass_id id, int node,
 				   struct udevice **devp);
@@ -257,9 +257,9 @@ int uclass_get_device_by_of_offset(enum uclass_id id, int node,
  * The device is probed to activate it ready for use.
  *
  * @id: ID to look up
- * @np: Device tree node to search for (if NULL then -ENODEV is returned)
+ * @node: Device tree node to search for (if NULL then -ENODEV is returned)
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
 				struct udevice **devp);
@@ -271,12 +271,13 @@ int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
  *
  * The device is probed to activate it ready for use.
  *
- * @id: uclass ID to look up
+ * @id:		uclass ID to look up
  * @phandle_id: the phandle id to look up
- * @devp: Returns pointer to device (there is only one for each node). NULL if
+ * @devp:	Returns pointer to device (there is only one for each node).
- *	there is no such device.
+ *		NULL if there is no such device.
- * @return 0 if OK, -ENODEV if there is no device match the phandle, other
+ * Return:
- *	-ve on error
+ * 0 if OK, -ENODEV if there is no device match the phandle,
+ * other -ve on error
  */
 int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
 				    struct udevice **devp);
@@ -292,8 +293,8 @@ int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
  * @parent: Parent device containing the phandle pointer
  * @name: Name of property in the parent device node
  * @devp: Returns pointer to device (there is only one for each node)
- * @return 0 if OK, -ENOENT if there is no @name present in the node, other
+ * Return: 0 if OK, -ENOENT if there is no @name present in the node, other
- *	-ve on error
+ * -ve on error
  */
 int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
 				 const char *name, struct udevice **devp);
@@ -310,7 +311,7 @@ int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
  * @id: ID to look up
  * @drv: Driver to look for
  * @devp: Returns pointer to the first device with that driver
- * @return 0 if OK, -ve on error
+ * Return: 0 if OK, -ve on error
  */
 int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
 				struct udevice **devp);
@@ -327,7 +328,7 @@ int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
  * @devp: Returns pointer to the first device in that uclass if no error
  * occurred, or NULL if there is no first device, or an error occurred with
  * that device.
- * @return 0 if OK (found or not found), other -ve on error
+ * Return: 0 if OK (found or not found), other -ve on error
  */
 int uclass_first_device(enum uclass_id id, struct udevice **devp);
 
@@ -338,7 +339,7 @@ int uclass_first_device(enum uclass_id id, struct udevice **devp);
  *
  * @id: Uclass ID to look up
  * @devp: Returns pointer to the first device in that uclass, or NULL if none
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
 
@@ -353,7 +354,7 @@ int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if no error occurred, or NULL if there is
  * no next device, or an error occurred with that next device.
- * @return 0 if OK (found or not found), other -ve on error
+ * Return: 0 if OK (found or not found), other -ve on error
  */
 int uclass_next_device(struct udevice **devp);
 
@@ -365,7 +366,7 @@ int uclass_next_device(struct udevice **devp);
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if no error occurred, or NULL if
  * there is no next device.
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_next_device_err(struct udevice **devp);
 
@@ -380,7 +381,7 @@ int uclass_next_device_err(struct udevice **devp);
  * @id: Uclass ID to look up
  * @devp: Returns pointer to the first device in that uclass, or NULL if there
  * is no first device
- * @return 0 if OK (found or not found), other -ve on error. If an error occurs
+ * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
  * it is still possible to move to the next device.
  */
 int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
@@ -395,7 +396,7 @@ int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
  *
  * @devp: On entry, pointer to device to lookup. On exit, returns pointer
  * to the next device in the uclass if any
- * @return 0 if OK (found or not found), other -ve on error. If an error occurs
+ * Return: 0 if OK (found or not found), other -ve on error. If an error occurs
  * it is still possible to move to the next device.
  */
 int uclass_next_device_check(struct udevice **devp);
@@ -409,7 +410,7 @@ int uclass_next_device_check(struct udevice **devp);
  * @id: Uclass ID to check
  * @driver_data: Driver data to search for
  * @devp: Returns pointer to the first matching device in that uclass, if found
- * @return 0 if found, -ENODEV if not found, other -ve on error
+ * Return: 0 if found, -ENODEV if not found, other -ve on error
  */
 int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
 				struct udevice **devp);
@@ -421,7 +422,7 @@ int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
  * looking for its ID.
  *
  * @id: uclass ID to look up
- * @return 0 if OK, other -ve on error
+ * Return: 0 if OK, other -ve on error
  */
 int uclass_probe_all(enum uclass_id id);
 
@@ -429,7 +430,7 @@ int uclass_probe_all(enum uclass_id id);
  * uclass_id_count() - Count the number of devices in a uclass
  *
  * @id: uclass ID to look up
- * @return number of devices in that uclass (0 if none)
+ * Return: number of devices in that uclass (0 if none)
  */
 int uclass_id_count(enum uclass_id id);
 
@@ -444,7 +445,7 @@ int uclass_id_count(enum uclass_id id);
  * @id: enum uclass_id ID to use
  * @pos: struct udevice * to hold the current device. Set to NULL when there
  * are no more devices.
- * @uc: temporary uclass variable (struct uclass *)
+ * @uc: temporary uclass variable (``struct uclass *``)
  */
 #define uclass_id_foreach_dev(id, pos, uc) \
 	if (!uclass_get(id, &uc)) \

include/efi.h

@@ -395,9 +395,9 @@ struct efi_entry_systable {
 };
 
 static inline struct efi_mem_desc *efi_get_next_mem_desc(
-		struct efi_entry_memmap *map, struct efi_mem_desc *desc)
+		struct efi_mem_desc *desc, int desc_size)
 {
-	return (struct efi_mem_desc *)((ulong)desc + map->desc_size);
+	return (struct efi_mem_desc *)((ulong)desc + desc_size);
 }
 
 /**
@@ -407,6 +407,12 @@ static inline struct efi_mem_desc *efi_get_next_mem_desc(
  * @sys_table: Pointer to system table
  * @boot: Pointer to boot-services table
  * @run: Pointer to runtime-services table
+ * @memmap_key: Key returned from get_memory_map()
+ * @memmap_desc: List of memory-map records
+ * @memmap_alloc: Amount of memory allocated for memory map list
+ * @memmap_size Size of memory-map list in bytes
+ * @memmap_desc_size: Size of an individual memory-map record, in bytes
+ * @memmap_version: Memory-map version
  *
  * @use_pool_for_malloc: true if all allocation should go through the EFI 'pool'
  *	methods allocate_pool() and free_pool(); false to use 'pages' methods
@@ -424,6 +430,12 @@ struct efi_priv {
 	struct efi_system_table *sys_table;
 	struct efi_boot_services *boot;
 	struct efi_runtime_services *run;
+	efi_uintn_t memmap_key;
+	struct efi_mem_desc *memmap_desc;
+	efi_uintn_t memmap_alloc;
+	efi_uintn_t memmap_size;
+	efi_uintn_t memmap_desc_size;
+	u32 memmap_version;
 
 	/* app: */
 	bool use_pool_for_malloc;
@@ -498,14 +510,14 @@ void efi_set_priv(struct efi_priv *priv);
 /**
  * efi_get_sys_table() - Get access to the main EFI system table
  *
- * @return pointer to EFI system table
+ * Returns: pointer to EFI system table
  */
 struct efi_system_table *efi_get_sys_table(void);
 
 /**
  * efi_get_boot() - Get access to the EFI boot services table
  *
- * @return pointer to EFI boot services table
+ * Returns: pointer to EFI boot services table
  */
 struct efi_boot_services *efi_get_boot(void);
 
@@ -514,7 +526,7 @@ struct efi_boot_services *efi_get_boot(void);
  *
  * This is used when U-Boot is built as an EFI application.
  *
- * @return the base of RAM as known to U-Boot
+ * Returns: the base of RAM as known to U-Boot
  */
 unsigned long efi_get_ram_base(void);
 
@@ -525,6 +537,7 @@ unsigned long efi_get_ram_base(void);
  * @banner:	Banner to display when starting
  * @image:	The image handle passed to efi_main()
  * @sys_table:	The EFI system table pointer passed to efi_main()
+ * Return: 0 on succcess, EFI error code on failure
  */
 int efi_init(struct efi_priv *priv, const char *banner, efi_handle_t image,
 	     struct efi_system_table *sys_table);
@@ -535,7 +548,7 @@ int efi_init(struct efi_priv *priv, const char *banner, efi_handle_t image,
  * @priv:	Pointer to private EFI structure
  * @size:	Number of bytes to allocate
  * @retp:	Return EFI status result
- * @return pointer to memory allocated, or NULL on error
+ * Returns: pointer to memory allocated, or NULL on error
  */
 void *efi_malloc(struct efi_priv *priv, int size, efi_status_t *retp);
 
@@ -572,10 +585,45 @@ void efi_putc(struct efi_priv *priv, const char ch);
  *
  * @type:	Entry type to search for
  * @datap:	Returns pointer to entry data
- * @sizep:	Returns pointer to entry size
+ * @sizep:	Returns entry size
- * @return 0 if OK, -ENODATA if there is no table, -ENOENT if there is no entry
+ * Return: 0 if OK, -ENODATA if there is no table, -ENOENT if there is no entry
  * of the requested type, -EPROTONOSUPPORT if the table has the wrong version
  */
 int efi_info_get(enum efi_entry_t type, void **datap, int *sizep);
 
+/**
+ * efi_store_memory_map() - Collect the memory-map info from EFI
+ *
+ * Collect the memory info and store it for later use, e.g. in calling
+ * exit_boot_services()
+ *
+ * @priv:	Pointer to private EFI structure
+ * Returns: 0 if OK, non-zero on error
+ */
+int efi_store_memory_map(struct efi_priv *priv);
+
+/**
+ * efi_call_exit_boot_services() - Handle the exit-boot-service procedure
+ *
+ * Tell EFI we don't want their boot services anymore
+ *
+ * Return: 0 if OK, non-zero on error
+ */
+int efi_call_exit_boot_services(void);
+
+/**
+ * efi_get_mmap() - Get the memory map from EFI
+ *
+ * This is used in the app. The caller must free *@descp when done
+ *
+ * @descp:	Returns allocated pointer to EFI memory map table
+ * @sizep:	Returns size of table in bytes
+ * @keyp:	Returns memory-map key
+ * @desc_sizep:	Returns size of each @desc_base record
+ * @versionp:	Returns version number of memory map
+ * Returns: 0 on success, -ve on error
+ */
+int efi_get_mmap(struct efi_mem_desc **descp, int *sizep, uint *keyp,
+		 int *desc_sizep, uint *versionp);
+
 #endif /* _LINUX_EFI_H */

include/efi_loader.h

@@ -517,6 +517,8 @@ efi_status_t EFIAPI efi_convert_pointer(efi_uintn_t debug_disposition,
 					void **address);
 /* Carve out DT reserved memory ranges */
 void efi_carve_out_dt_rsv(void *fdt);
+/* Purge unused kaslr-seed */
+void efi_try_purge_kaslr_seed(void *fdt);
 /* Called by bootefi to make console interface available */
 efi_status_t efi_console_register(void);
 /* Called by bootefi to make all disk storage accessible as EFI objects */

include/part.h

@@ -50,7 +50,7 @@ struct block_drvr {
 
 #define PART_NAME_LEN 32
 #define PART_TYPE_LEN 32
-#define MAX_SEARCH_PARTITIONS 64
+#define MAX_SEARCH_PARTITIONS 128
 
 #define PART_BOOTABLE			((int)BIT(0))
 #define PART_EFI_SYSTEM_PARTITION	((int)BIT(1))

lib/efi/efi.c

@@ -135,3 +135,75 @@ void efi_free(struct efi_priv *priv, void *ptr)
 
 	boot->free_pool(ptr);
 }
+
+int efi_store_memory_map(struct efi_priv *priv)
+{
+	struct efi_boot_services *boot = priv->sys_table->boottime;
+	efi_uintn_t size, desc_size;
+	efi_status_t ret;
+
+	/* Get the memory map so we can switch off EFI */
+	size = 0;
+	ret = boot->get_memory_map(&size, NULL, &priv->memmap_key,
+				   &priv->memmap_desc_size,
+				   &priv->memmap_version);
+	if (ret != EFI_BUFFER_TOO_SMALL) {
+		/*
+		 * Note this function avoids using printf() since it is not
+		 * available in the stub
+		 */
+		printhex2(EFI_BITS_PER_LONG);
+		putc(' ');
+		printhex2(ret);
+		puts(" No memory map\n");
+		return ret;
+	}
+	/*
+	 * Since doing a malloc() may change the memory map and also we want to
+	 * be able to read the memory map in efi_call_exit_boot_services()
+	 * below, after more changes have happened
+	 */
+	priv->memmap_alloc = size + 1024;
+	priv->memmap_size = priv->memmap_alloc;
+	priv->memmap_desc = efi_malloc(priv, size, &ret);
+	if (!priv->memmap_desc) {
+		printhex2(ret);
+		puts(" No memory for memory descriptor\n");
+		return ret;
+	}
+
+	ret = boot->get_memory_map(&priv->memmap_size, priv->memmap_desc,
+				   &priv->memmap_key, &desc_size,
+				   &priv->memmap_version);
+	if (ret) {
+		printhex2(ret);
+		puts(" Can't get memory map\n");
+		return ret;
+	}
+
+	return 0;
+}
+
+int efi_call_exit_boot_services(void)
+{
+	struct efi_priv *priv = efi_get_priv();
+	const struct efi_boot_services *boot = priv->boot;
+	efi_uintn_t size;
+	u32 version;
+	efi_status_t ret;
+
+	size = priv->memmap_alloc;
+	ret = boot->get_memory_map(&size, priv->memmap_desc,
+				   &priv->memmap_key,
+				   &priv->memmap_desc_size, &version);
+	if (ret) {
+		printhex2(ret);
+		puts(" Can't get memory map\n");
+		return ret;
+	}
+	ret = boot->exit_boot_services(priv->parent_image, priv->memmap_key);
+	if (ret)
+		return ret;
+
+	return 0;
+}

lib/efi/efi_app.c

@@ -32,6 +32,39 @@ int efi_info_get(enum efi_entry_t type, void **datap, int *sizep)
 	return -ENOSYS;
 }
 
+int efi_get_mmap(struct efi_mem_desc **descp, int *sizep, uint *keyp,
+		 int *desc_sizep, uint *versionp)
+{
+	struct efi_priv *priv = efi_get_priv();
+	struct efi_boot_services *boot = priv->sys_table->boottime;
+	efi_uintn_t size, desc_size, key;
+	struct efi_mem_desc *desc;
+	efi_status_t ret;
+	u32 version;
+
+	/* Get the memory map so we can switch off EFI */
+	size = 0;
+	ret = boot->get_memory_map(&size, NULL, &key, &desc_size, &version);
+	if (ret != EFI_BUFFER_TOO_SMALL)
+		return log_msg_ret("get", -ENOMEM);
+
+	desc = malloc(size);
+	if (!desc)
+		return log_msg_ret("mem", -ENOMEM);
+
+	ret = boot->get_memory_map(&size, desc, &key, &desc_size, &version);
+	if (ret)
+		return log_msg_ret("get", -EINVAL);
+
+	*descp = desc;
+	*sizep = size;
+	*desc_sizep = desc_size;
+	*versionp = version;
+	*keyp = key;
+
+	return 0;
+}
+
 /**
  * efi_bind_block() - bind a new block device to an EFI device
  *
@@ -321,6 +354,15 @@ efi_status_t EFIAPI efi_main(efi_handle_t image,
 		return ret;
 	}
 
+	/*
+	 * We could store the EFI memory map here, but it changes all the time,
+	 * so this is only useful for debugging.
+	 *
+	 * ret = efi_store_memory_map(priv);
+	 * if (ret)
+	 *	return ret;
+	 */
+
 	printf("starting\n");
 
 	board_init_f(GD_FLG_SKIP_RELOC);

lib/efi/efi_stub.c

@@ -304,15 +304,12 @@ efi_status_t EFIAPI efi_main(efi_handle_t image,
 {
 	struct efi_priv local_priv, *priv = &local_priv;
 	struct efi_boot_services *boot = sys_table->boottime;
-	struct efi_mem_desc *desc;
 	struct efi_entry_memmap map;
 	struct efi_gop *gop;
 	struct efi_entry_gopmode mode;
 	struct efi_entry_systable table;
 	efi_guid_t efi_gop_guid = EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID;
-	efi_uintn_t key, desc_size, size;
 	efi_status_t ret;
-	u32 version;
 	int cs32;
 
 	ret = efi_init(priv, "Payload", image, sys_table);
@@ -327,24 +324,11 @@ efi_status_t EFIAPI efi_main(efi_handle_t image,
 	if (cs32 < 0)
 		return EFI_UNSUPPORTED;
 
-	/* Get the memory map so we can switch off EFI */
+	ret = efi_store_memory_map(priv);
-	size = 0;
+	if (ret)
-	ret = boot->get_memory_map(&size, NULL, &key, &desc_size, &version);
-	if (ret != EFI_BUFFER_TOO_SMALL) {
-		printhex2(EFI_BITS_PER_LONG);
-		putc(' ');
-		printhex2(ret);
-		puts(" No memory map\n");
 		return ret;
-	}
+
-	size += 1024;	/* Since doing a malloc() may change the memory map! */
+	ret = setup_info_table(priv, priv->memmap_size + 128);
-	desc = efi_malloc(priv, size, &ret);
-	if (!desc) {
-		printhex2(ret);
-		puts(" No memory for memory descriptor\n");
-		return ret;
-	}
-	ret = setup_info_table(priv, size + 128);
 	if (ret)
 		return ret;
 
@@ -360,48 +344,20 @@ efi_status_t EFIAPI efi_main(efi_handle_t image,
 			       sizeof(struct efi_gop_mode_info));
 	}
 
-	ret = boot->get_memory_map(&size, desc, &key, &desc_size, &version);
-	if (ret) {
-		printhex2(ret);
-		puts(" Can't get memory map\n");
-		return ret;
-	}
-
 	table.sys_table = (ulong)sys_table;
 	add_entry_addr(priv, EFIET_SYS_TABLE, &table, sizeof(table), NULL, 0);
 
-	ret = boot->exit_boot_services(image, key);
+	ret = efi_call_exit_boot_services();
-	if (ret) {
+	if (ret)
-		/*
+		return ret;
-		 * Unfortunately it happens that we cannot exit boot services
-		 * the first time. But the second time it work. I don't know
-		 * why but this seems to be a repeatable problem. To get
-		 * around it, just try again.
-		 */
-		printhex2(ret);
-		puts(" Can't exit boot services\n");
-		size = sizeof(desc);
-		ret = boot->get_memory_map(&size, desc, &key, &desc_size,
-					   &version);
-		if (ret) {
-			printhex2(ret);
-			puts(" Can't get memory map\n");
-			return ret;
-		}
-		ret = boot->exit_boot_services(image, key);
-		if (ret) {
-			printhex2(ret);
-			puts(" Can't exit boot services 2\n");
-			return ret;
-		}
-	}
 
 	/* The EFI UART won't work now, switch to a debug one */
 	use_uart = true;
 
-	map.version = version;
+	map.version = priv->memmap_version;
-	map.desc_size = desc_size;
+	map.desc_size = priv->memmap_desc_size;
-	add_entry_addr(priv, EFIET_MEMORY_MAP, &map, sizeof(map), desc, size);
+	add_entry_addr(priv, EFIET_MEMORY_MAP, &map, sizeof(map),
+		       priv->memmap_desc, priv->memmap_size);
 	add_entry_addr(priv, EFIET_END, NULL, 0, 0, 0);
 
 	memcpy((void *)CONFIG_SYS_TEXT_BASE, _binary_u_boot_bin_start,

lib/efi_loader/efi_dt_fixup.c

@@ -8,6 +8,7 @@
 #include <common.h>
 #include <efi_dt_fixup.h>
 #include <efi_loader.h>
+#include <efi_rng.h>
 #include <fdtdec.h>
 #include <mapmem.h>
 
@@ -40,6 +41,38 @@ static void efi_reserve_memory(u64 addr, u64 size, bool nomap)
 			addr, size);
 }
 
+/**
+ * efi_try_purge_kaslr_seed() - Remove unused kaslr-seed
+ *
+ * Kernel's EFI STUB only relies on EFI_RNG_PROTOCOL for randomization
+ * and completely ignores the kaslr-seed for its own randomness needs
+ * (i.e the randomization of the physical placement of the kernel).
+ * Weed it out from the DTB we hand over, which would mess up our DTB
+ * TPM measurements as well.
+ *
+ * @fdt: Pointer to device tree
+ */
+void efi_try_purge_kaslr_seed(void *fdt)
+{
+	const efi_guid_t efi_guid_rng_protocol = EFI_RNG_PROTOCOL_GUID;
+	struct efi_handler *handler;
+	efi_status_t ret;
+	int nodeoff = 0;
+	int err = 0;
+
+	ret = efi_search_protocol(efi_root, &efi_guid_rng_protocol, &handler);
+	if (ret != EFI_SUCCESS)
+		return;
+
+	nodeoff = fdt_path_offset(fdt, "/chosen");
+	if (nodeoff < 0)
+		return;
+
+	err = fdt_delprop(fdt, nodeoff, "kaslr-seed");
+	if (err < 0 && err != -FDT_ERR_NOTFOUND)
+		log_err("Error deleting kaslr-seed\n");
+}
+
 /**
  * efi_carve_out_dt_rsv() - Carve out DT reserved memory ranges
  *

lib/efi_loader/efi_firmware.c

@@ -128,8 +128,11 @@ static efi_status_t efi_get_dfu_info(
 	size_t names_len, total_size;
 	int dfu_num, i;
 	u16 *name, *next;
+	int ret;
 
-	dfu_init_env_entities(NULL, NULL);
+	ret = dfu_init_env_entities(NULL, NULL);
+	if (ret)
+		return EFI_SUCCESS;
 
 	names_len = 0;
 	dfu_num = 0;
@@ -138,7 +141,7 @@ static efi_status_t efi_get_dfu_info(
 		dfu_num++;
 	}
 	if (!dfu_num) {
-		log_warning("Probably dfu_alt_info not defined\n");
+		log_warning("No entities in dfu_alt_info\n");
 		*image_info_size = 0;
 		dfu_free_entities();