[people/ms/u-boot.git] / doc / README.ubispl

Lightweight UBI and UBI fastmap support

# Copyright (C) Thomas Gleixner <tglx@linutronix.de>
#
# SPDX-License-Identifier: GPL 2.0+ BSD-3-Clause

Scans the UBI information and loads the requested static volumes into
memory.

Configuration Options:

   CONFIG_SPL_UBI
     Enables the SPL UBI support

   CONFIG_SPL_UBI_MAX_VOL_LEBS
     The maximum number of logical eraseblocks which a static volume
     to load can contain. Used for sizing the scan data structure

   CONFIG_SPL_UBI_MAX_PEB_SIZE
     The maximum physical erase block size. Either a compile time
     constant or runtime detection. Used for sizing the scan data
     structure

   CONFIG_SPL_UBI_MAX_PEBS
     The maximum physical erase block count. Either a compile time
     constant or runtime detection. Used for sizing the scan data
     structure

   CONFIG_SPL_UBI_VOL_IDS
     The maximum volume ids which can be loaded. Used for sizing the
     scan data structure.

Usage notes:

In the board config file define for example:

#define CONFIG_SPL_UBI
#define CONFIG_SPL_UBI_MAX_VOL_LEBS	256
#define CONFIG_SPL_UBI_MAX_PEB_SIZE	(256*1024)
#define CONFIG_SPL_UBI_MAX_PEBS		4096
#define CONFIG_SPL_UBI_VOL_IDS		8

The size requirement is roughly as follows:

    2k for the basic data structure
  + CONFIG_SPL_UBI_VOL_IDS * CONFIG_SPL_UBI_MAX_VOL_LEBS * 8
  + CONFIG_SPL_UBI_MAX_PEBS * 64
  + CONFIG_SPL_UBI_MAX_PEB_SIZE * UBI_FM_MAX_BLOCKS

The last one is big, but I really don't care in that stage. Real world
implementations only use the first couple of blocks, but the code
handles up to UBI_FM_MAX_BLOCKS.

Given the above configuration example the requirement is about 5M
which is usually not a problem to reserve in the RAM along with the
other areas like the kernel/dts load address.

So something like this will do the trick:

#define SPL_FINFO_ADDR			0x80800000
#define SPL_DTB_LOAD_ADDR		0x81800000
#define SPL_KERNEL_LOAD_ADDR		0x82000000

In the board file, implement the following:

static struct ubispl_load myvolumes[] = {
	{
		.vol_id		= 0,	/* kernel volume */
		.load_addr	= (void *)SPL_KERNEL_LOAD_ADDR,
	},
	{
		.vol_id		= 1,	/* DT blob */
		.load_addr	= (void *)SPL_DTB_LOAD_ADDR,
	}
};

int spl_start_uboot(void)
{
	struct ubispl_info info;

	info.ubi = (struct ubi_scan_info *) SPL_FINFO_ADDR;
	info.fastmap = 1;
	info.read = nand_spl_read_flash;

#if COMPILE_TIME_DEFINED
	/*
	 * MY_NAND_NR_SPL_PEBS is the number of physical erase blocks
	 * in the FLASH which are reserved for the SPL. Think about
	 * mtd partitions:
	 *
	 * part_spl { .start = 0, .end = 4 }
	 * part_ubi { .start = 4, .end = NR_PEBS }
	 */
	info.peb_offset = MY_NAND_NR_SPL_PEBS;
	info.peb_size = CONFIG_SYS_NAND_BLOCK_SIZE;
	info.vid_offset = MY_NAND_UBI_VID_OFFS;
	info.leb_start = MY_NAND_UBI_DATA_OFFS;
	info.peb_count = MY_NAND_UBI_NUM_PEBS;
#else
	get_flash_info(&flash_info);
	info.peb_offset = MY_NAND_NR_SPL_PEBS;
	info.peb_size = flash_info.peb_size;

	/*
	 * The VID and Data offset depend on the capability of the
	 * FLASH chip to do subpage writes.
	 *
	 * If the flash chip supports subpage writes, then the VID
	 * header starts at the second subpage. So for 2k pages size
	 * with 4 subpages the VID offset is 512. The DATA offset is 2k.
	 *
	 * If the flash chip does not support subpage writes then the
	 * VID offset is FLASH_PAGE_SIZE and the DATA offset
	 * 2 * FLASH_PAGE_SIZE
	 */
	info.vid_offset = flash_info.vid_offset;
	info.leb_start = flash_info.data_offset;

	/*
	 * The flash reports the total number of erase blocks, so
	 * we need to subtract the number of blocks which are reserved
	 * for the SPL itself and not managed by UBI.
	 */
	info.peb_count = flash_info.peb_count - MY_NAND_NR_SPL_PEBS;
#endif

	ret = ubispl_load_volumes(&info, myvolumes, ARRAY_SIZE(myvolumes);

	....

}

Note: you can load any payload that way. You can even load u-boot from
UBI, so the only non UBI managed FLASH area is the one which is
reserved for the SPL itself and read from the SoC ROM.

And you can do fallback scenarios:

    if (ubispl_load_volumes(&info, volumes0, ARRAY_SIZE(volumes0)))
        if (ubispl_load_volumes(&info, volumes1, ARRAY_SIZE(volumes1)))
	    ubispl_load_volumes(&info, vol_uboot, ARRAY_SIZE(vol_uboot));
Commit	Line	Data
6f4e7d3c TG	1	Lightweight UBI and UBI fastmap support
	2
	3	# Copyright (C) Thomas Gleixner <tglx@linutronix.de>
	4	#
	5	# SPDX-License-Identifier: GPL 2.0+ BSD-3-Clause
	6
	7	Scans the UBI information and loads the requested static volumes into
	8	memory.
	9
	10	Configuration Options:
	11
	12	CONFIG_SPL_UBI
	13	Enables the SPL UBI support
	14
	15	CONFIG_SPL_UBI_MAX_VOL_LEBS
	16	The maximum number of logical eraseblocks which a static volume
	17	to load can contain. Used for sizing the scan data structure
	18
	19	CONFIG_SPL_UBI_MAX_PEB_SIZE
	20	The maximum physical erase block size. Either a compile time
	21	constant or runtime detection. Used for sizing the scan data
	22	structure
	23
	24	CONFIG_SPL_UBI_MAX_PEBS
	25	The maximum physical erase block count. Either a compile time
	26	constant or runtime detection. Used for sizing the scan data
	27	structure
	28
	29	CONFIG_SPL_UBI_VOL_IDS
	30	The maximum volume ids which can be loaded. Used for sizing the
	31	scan data structure.
	32
	33	Usage notes:
	34
	35	In the board config file define for example:
	36
	37	#define CONFIG_SPL_UBI
	38	#define CONFIG_SPL_UBI_MAX_VOL_LEBS 256
	39	#define CONFIG_SPL_UBI_MAX_PEB_SIZE (256*1024)
	40	#define CONFIG_SPL_UBI_MAX_PEBS 4096
	41	#define CONFIG_SPL_UBI_VOL_IDS 8
	42
	43	The size requirement is roughly as follows:
	44
	45	2k for the basic data structure
	46	+ CONFIG_SPL_UBI_VOL_IDS * CONFIG_SPL_UBI_MAX_VOL_LEBS * 8
	47	+ CONFIG_SPL_UBI_MAX_PEBS * 64
	48	+ CONFIG_SPL_UBI_MAX_PEB_SIZE * UBI_FM_MAX_BLOCKS
	49
	50	The last one is big, but I really don't care in that stage. Real world
	51	implementations only use the first couple of blocks, but the code
	52	handles up to UBI_FM_MAX_BLOCKS.
	53
	54	Given the above configuration example the requirement is about 5M
	55	which is usually not a problem to reserve in the RAM along with the
	56	other areas like the kernel/dts load address.
	57
	58	So something like this will do the trick:
	59
	60	#define SPL_FINFO_ADDR 0x80800000
	61	#define SPL_DTB_LOAD_ADDR 0x81800000
	62	#define SPL_KERNEL_LOAD_ADDR 0x82000000
	63
	64	In the board file, implement the following:
65
66	static struct ubispl_load myvolumes[] = {
67	{
68	.vol_id = 0, /* kernel volume */
69	.load_addr = (void *)SPL_KERNEL_LOAD_ADDR,
70	},
71	{
72	.vol_id = 1, /* DT blob */
73	.load_addr = (void *)SPL_DTB_LOAD_ADDR,
74	}
75	};
76
77	int spl_start_uboot(void)
78	{
79	struct ubispl_info info;
80
81	info.ubi = (struct ubi_scan_info *) SPL_FINFO_ADDR;
82	info.fastmap = 1;
83	info.read = nand_spl_read_flash;
84
85	#if COMPILE_TIME_DEFINED
86	/*
87	* MY_NAND_NR_SPL_PEBS is the number of physical erase blocks
88	* in the FLASH which are reserved for the SPL. Think about
89	* mtd partitions:
90	*
91	* part_spl { .start = 0, .end = 4 }
92	* part_ubi { .start = 4, .end = NR_PEBS }
93	*/
94	info.peb_offset = MY_NAND_NR_SPL_PEBS;
95	info.peb_size = CONFIG_SYS_NAND_BLOCK_SIZE;
96	info.vid_offset = MY_NAND_UBI_VID_OFFS;
97	info.leb_start = MY_NAND_UBI_DATA_OFFS;
98	info.peb_count = MY_NAND_UBI_NUM_PEBS;
99	#else
100	get_flash_info(&flash_info);
101	info.peb_offset = MY_NAND_NR_SPL_PEBS;
102	info.peb_size = flash_info.peb_size;
103
104	/*
105	* The VID and Data offset depend on the capability of the
106	* FLASH chip to do subpage writes.
107	*
108	* If the flash chip supports subpage writes, then the VID
109	* header starts at the second subpage. So for 2k pages size
110	* with 4 subpages the VID offset is 512. The DATA offset is 2k.
111	*
112	* If the flash chip does not support subpage writes then the
113	* VID offset is FLASH_PAGE_SIZE and the DATA offset
114	* 2 * FLASH_PAGE_SIZE
115	*/
116	info.vid_offset = flash_info.vid_offset;
117	info.leb_start = flash_info.data_offset;
118
119	/*
120	* The flash reports the total number of erase blocks, so
121	* we need to subtract the number of blocks which are reserved
122	* for the SPL itself and not managed by UBI.
123	*/
124	info.peb_count = flash_info.peb_count - MY_NAND_NR_SPL_PEBS;
125	#endif
126
127	ret = ubispl_load_volumes(&info, myvolumes, ARRAY_SIZE(myvolumes);
128
129	....
130
131	}
132
133	Note: you can load any payload that way. You can even load u-boot from
134	UBI, so the only non UBI managed FLASH area is the one which is
135	reserved for the SPL itself and read from the SoC ROM.
136
137	And you can do fallback scenarios:
138
139	if (ubispl_load_volumes(&info, volumes0, ARRAY_SIZE(volumes0)))
140	if (ubispl_load_volumes(&info, volumes1, ARRAY_SIZE(volumes1)))
141	ubispl_load_volumes(&info, vol_uboot, ARRAY_SIZE(vol_uboot));