[J-u-boot.git] / include / spl.h

/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * (C) Copyright 2012
 * Texas Instruments, <www.ti.com>
 */
#ifndef	_SPL_H_
#define	_SPL_H_

#include <binman_sym.h>

/* Platform-specific defines */
#include <linux/compiler.h>
#include <asm/spl.h>
#include <handoff.h>

/* Value in r0 indicates we booted from U-Boot */
#define UBOOT_NOT_LOADED_FROM_SPL	0x13578642

/* Boot type */
#define MMCSD_MODE_UNDEFINED	0
#define MMCSD_MODE_RAW		1
#define MMCSD_MODE_FS		2
#define MMCSD_MODE_EMMCBOOT	3

/*
 * u_boot_first_phase() - check if this is the first U-Boot phase
 *
 * U-Boot has up to three phases: TPL, SPL and U-Boot proper. Depending on the
 * build flags we can determine whether the current build is for the first
 * phase of U-Boot or not. If there is no SPL, then this is U-Boot proper. If
 * there is SPL but no TPL, the the first phase is SPL. If there is TPL, then
 * it is the first phase.
 *
 * @returns true if this is the first phase of U-Boot
 *
 */
static inline bool u_boot_first_phase(void)
{
	if (IS_ENABLED(CONFIG_TPL)) {
		if (IS_ENABLED(CONFIG_TPL_BUILD))
			return true;
	} else if (IS_ENABLED(CONFIG_SPL)) {
		if (IS_ENABLED(CONFIG_SPL_BUILD))
			return true;
	} else {
		return true;
	}

	return false;
}

enum u_boot_phase {
	PHASE_TPL,	/* Running in TPL */
	PHASE_SPL,	/* Running in SPL */
	PHASE_BOARD_F,	/* Running in U-Boot before relocation */
	PHASE_BOARD_R,	/* Running in U-Boot after relocation */
};

/**
 * spl_phase() - Find out the phase of U-Boot
 *
 * This can be used to avoid #ifdef logic and use if() instead.
 *
 * For example, to include code only in TPL, you might do:
 *
 *    #ifdef CONFIG_TPL_BUILD
 *    ...
 *    #endif
 *
 * but with this you can use:
 *
 *    if (spl_phase() == PHASE_TPL) {
 *       ...
 *    }
 *
 * To include code only in SPL, you might do:
 *
 *    #if defined(CONFIG_SPL_BUILD) && !defined(CONFIG_TPL_BUILD)
 *    ...
 *    #endif
 *
 * but with this you can use:
 *
 *    if (spl_phase() == PHASE_SPL) {
 *       ...
 *    }
 *
 * To include code only in U-Boot proper, you might do:
 *
 *    #ifndef CONFIG_SPL_BUILD
 *    ...
 *    #endif
 *
 * but with this you can use:
 *
 *    if (spl_phase() == PHASE_BOARD_F) {
 *       ...
 *    }
 *
 * @return U-Boot phase
 */
static inline enum u_boot_phase spl_phase(void)
{
#ifdef CONFIG_TPL_BUILD
	return PHASE_TPL;
#elif CONFIG_SPL_BUILD
	return PHASE_SPL;
#else
	DECLARE_GLOBAL_DATA_PTR;

	if (!(gd->flags & GD_FLG_RELOC))
		return PHASE_BOARD_F;
	else
		return PHASE_BOARD_R;
#endif
}

/* A string name for SPL or TPL */
#ifdef CONFIG_SPL_BUILD
# ifdef CONFIG_TPL_BUILD
#  define SPL_TPL_NAME	"TPL"
# else
#  define SPL_TPL_NAME	"SPL"
# endif
# define SPL_TPL_PROMPT	SPL_TPL_NAME ": "
#else
# define SPL_TPL_NAME	""
# define SPL_TPL_PROMPT	""
#endif

struct spl_image_info {
	const char *name;
	u8 os;
	uintptr_t load_addr;
	uintptr_t entry_point;
#if CONFIG_IS_ENABLED(LOAD_FIT) || CONFIG_IS_ENABLED(LOAD_FIT_FULL)
	void *fdt_addr;
#endif
	u32 boot_device;
	u32 size;
	u32 flags;
	void *arg;
#ifdef CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK
	ulong dcrc_data;
	ulong dcrc_length;
	ulong dcrc;
#endif
};

/*
 * Information required to load data from a device
 *
 * @dev: Pointer to the device, e.g. struct mmc *
 * @priv: Private data for the device
 * @bl_len: Block length for reading in bytes
 * @filename: Name of the fit image file.
 * @read: Function to call to read from the device
 */
struct spl_load_info {
	void *dev;
	void *priv;
	int bl_len;
	const char *filename;
	ulong (*read)(struct spl_load_info *load, ulong sector, ulong count,
		      void *buf);
};

/*
 * We need to know the position of U-Boot in memory so we can jump to it. We
 * allow any U-Boot binary to be used (u-boot.bin, u-boot-nodtb.bin,
 * u-boot.img), hence the '_any'. These is no checking here that the correct
 * image is found. For * example if u-boot.img is used we don't check that
 * spl_parse_image_header() can parse a valid header.
 */
binman_sym_extern(ulong, u_boot_any, image_pos);

/**
 * spl_load_simple_fit_skip_processing() - Hook to allow skipping the FIT
 *	image processing during spl_load_simple_fit().
 *
 * Return true to skip FIT processing, false to preserve the full code flow
 * of spl_load_simple_fit().
 */
bool spl_load_simple_fit_skip_processing(void);

/**
 * spl_load_simple_fit() - Loads a fit image from a device.
 * @spl_image:	Image description to set up
 * @info:	Structure containing the information required to load data.
 * @sector:	Sector number where FIT image is located in the device
 * @fdt:	Pointer to the copied FIT header.
 *
 * Reads the FIT image @sector in the device. Loads u-boot image to
 * specified load address and copies the dtb to end of u-boot image.
 * Returns 0 on success.
 */
int spl_load_simple_fit(struct spl_image_info *spl_image,
			struct spl_load_info *info, ulong sector, void *fdt);

#define SPL_COPY_PAYLOAD_ONLY	1
#define SPL_FIT_FOUND		2

/**
 * spl_load_imx_container() - Loads a imx container image from a device.
 * @spl_image:	Image description to set up
 * @info:	Structure containing the information required to load data.
 * @sector:	Sector number where container image is located in the device
 *
 * Reads the container image @sector in the device. Loads u-boot image to
 * specified load address.
 */
int spl_load_imx_container(struct spl_image_info *spl_image,
			   struct spl_load_info *info, ulong sector);

/* SPL common functions */
void preloader_console_init(void);
u32 spl_boot_device(void);
u32 spl_boot_mode(const u32 boot_device);
int spl_boot_partition(const u32 boot_device);
void spl_set_bd(void);

/**
 * spl_set_header_raw_uboot() - Set up a standard SPL image structure
 *
 * This sets up the given spl_image which the standard values obtained from
 * config options: CONFIG_SYS_MONITOR_LEN, CONFIG_SYS_UBOOT_START,
 * CONFIG_SYS_TEXT_BASE.
 *
 * @spl_image: Image description to set up
 */
void spl_set_header_raw_uboot(struct spl_image_info *spl_image);

/**
 * spl_parse_image_header() - parse the image header and set up info
 *
 * This parses the legacy image header information at @header and sets up
 * @spl_image according to what is found. If no image header is found, then
 * a raw image or bootz is assumed. If CONFIG_SPL_PANIC_ON_RAW_IMAGE is
 * enabled, then this causes a panic. If CONFIG_SPL_RAW_IMAGE_SUPPORT is not
 * enabled then U-Boot gives up. Otherwise U-Boot sets up the image using
 * spl_set_header_raw_uboot(), or possibly the bootz header.
 *
 * @spl_image: Image description to set up
 * @header image header to parse
 * @return 0 if a header was correctly parsed, -ve on error
 */
int spl_parse_image_header(struct spl_image_info *spl_image,
			   const struct image_header *header);

void spl_board_prepare_for_linux(void);
void spl_board_prepare_for_boot(void);
int spl_board_ubi_load_image(u32 boot_device);

/**
 * jump_to_image_linux() - Jump to a Linux kernel from SPL
 *
 * This jumps into a Linux kernel using the information in @spl_image.
 *
 * @spl_image: Image description to set up
 */
void __noreturn jump_to_image_linux(struct spl_image_info *spl_image);

/**
 * spl_start_uboot() - Check if SPL should start the kernel or U-Boot
 *
 * This is called by the various SPL loaders to determine whether the board
 * wants to load the kernel or U-Boot. This function should be provided by
 * the board.
 *
 * @return 0 if SPL should start the kernel, 1 if U-Boot must be started
 */
int spl_start_uboot(void);

/**
 * spl_display_print() - Display a board-specific message in SPL
 *
 * If CONFIG_SPL_DISPLAY_PRINT is enabled, U-Boot will call this function
 * immediately after displaying the SPL console banner ("U-Boot SPL ...").
 * This function should be provided by the board.
 */
void spl_display_print(void);

/**
 * struct spl_boot_device - Describes a boot device used by SPL
 *
 * @boot_device: A number indicating the BOOT_DEVICE type. There are various
 * BOOT_DEVICE... #defines and enums in U-Boot and they are not consistently
 * numbered.
 * @boot_device_name: Named boot device, or NULL if none.
 *
 * Note: Additional fields can be added here, bearing in mind that SPL is
 * size-sensitive and common fields will be present on all boards. This
 * struct can also be used to return additional information about the load
 * process if that becomes useful.
 */
struct spl_boot_device {
	uint boot_device;
	const char *boot_device_name;
};

/**
 * Holds information about a way of loading an SPL image
 *
 * @name: User-friendly name for this method (e.g. "MMC")
 * @boot_device: Boot device that this loader supports
 * @load_image: Function to call to load image
 */
struct spl_image_loader {
#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT
	const char *name;
#endif
	uint boot_device;
	/**
	 * load_image() - Load an SPL image
	 *
	 * @spl_image: place to put image information
	 * @bootdev: describes the boot device to load from
	 */
	int (*load_image)(struct spl_image_info *spl_image,
			  struct spl_boot_device *bootdev);
};

/* Declare an SPL image loader */
#define SPL_LOAD_IMAGE(__name)					\
	ll_entry_declare(struct spl_image_loader, __name, spl_image_loader)

/*
 * _priority is the priority of this method, 0 meaning it will be the top
 * choice for this device, 9 meaning it is the bottom choice.
 * _boot_device is the BOOT_DEVICE_... value
 * _method is the load_image function to call
 */
#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT
#define SPL_LOAD_IMAGE_METHOD(_name, _priority, _boot_device, _method) \
	SPL_LOAD_IMAGE(_method ## _priority ## _boot_device) = { \
		.name = _name, \
		.boot_device = _boot_device, \
		.load_image = _method, \
	}
#else
#define SPL_LOAD_IMAGE_METHOD(_name, _priority, _boot_device, _method) \
	SPL_LOAD_IMAGE(_method ## _priority ## _boot_device) = { \
		.boot_device = _boot_device, \
		.load_image = _method, \
	}
#endif

/* SPL FAT image functions */
int spl_load_image_fat(struct spl_image_info *spl_image,
		       struct blk_desc *block_dev, int partition,
		       const char *filename);
int spl_load_image_fat_os(struct spl_image_info *spl_image,
			  struct blk_desc *block_dev, int partition);

void __noreturn jump_to_image_no_args(struct spl_image_info *spl_image);

/* SPL EXT image functions */
int spl_load_image_ext(struct spl_image_info *spl_image,
		       struct blk_desc *block_dev, int partition,
		       const char *filename);
int spl_load_image_ext_os(struct spl_image_info *spl_image,
			  struct blk_desc *block_dev, int partition);

/**
 * spl_early_init() - Set up device tree and driver model in SPL if enabled
 *
 * Call this function in board_init_f() if you want to use device tree and
 * driver model early, before board_init_r() is called.
 *
 * If this is not called, then driver model will be inactive in SPL's
 * board_init_f(), and no device tree will be available.
 */
int spl_early_init(void);

/**
 * spl_init() - Set up device tree and driver model in SPL if enabled
 *
 * You can optionally call spl_early_init(), then optionally call spl_init().
 * This function will be called from board_init_r() if not called earlier.
 *
 * Both spl_early_init() and spl_init() perform a similar function except that
 * the latter will not set up the malloc() area if
 * CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN is enabled, since it is assumed to
 * already be done by a calll to spl_relocate_stack_gd() before board_init_r()
 * is reached.
 *
 * This function will be called from board_init_r() if not called earlier.
 *
 * If this is not called, then driver model will be inactive in SPL's
 * board_init_f(), and no device tree will be available.
 */
int spl_init(void);

#ifdef CONFIG_SPL_BOARD_INIT
void spl_board_init(void);
#endif

/**
 * spl_was_boot_source() - check if U-Boot booted from SPL
 *
 * This will normally be true, but if U-Boot jumps to second U-Boot, it will
 * be false. This should be implemented by board-specific code.
 *
 * @return true if U-Boot booted from SPL, else false
 */
bool spl_was_boot_source(void);

/**
 * spl_dfu_cmd- run dfu command with chosen mmc device interface
 * @param usb_index - usb controller number
 * @param mmc_dev -  mmc device nubmer
 *
 * @return 0 on success, otherwise error code
 */
int spl_dfu_cmd(int usbctrl, char *dfu_alt_info, char *interface, char *devstr);

int spl_mmc_load_image(struct spl_image_info *spl_image,
		       struct spl_boot_device *bootdev);

/**
 * spl_mmc_load() - Load an image file from MMC/SD media
 *
 * @param spl_image	Image data filled in by loading process
 * @param bootdev	Describes which device to load from
 * @param filename	Name of file to load (in FS mode)
 * @param raw_part	Partition to load from (in RAW mode)
 * @param raw_sect	Sector to load from (in RAW mode)
 *
 * @return 0 on success, otherwise error code
 */
int spl_mmc_load(struct spl_image_info *spl_image,
		 struct spl_boot_device *bootdev,
		 const char *filename,
		 int raw_part,
		 unsigned long raw_sect);

int spl_ymodem_load_image(struct spl_image_info *spl_image,
			  struct spl_boot_device *bootdev);

/**
 * spl_invoke_atf - boot using an ARM trusted firmware image
 */
void spl_invoke_atf(struct spl_image_info *spl_image);

/**
 * spl_optee_entry - entry function for optee
 *
 * args defind in op-tee project
 * https://github.com/OP-TEE/optee_os/
 * core/arch/arm/kernel/generic_entry_a32.S
 * @arg0: pagestore
 * @arg1: (ARMv7 standard bootarg #1)
 * @arg2: device tree address, (ARMv7 standard bootarg #2)
 * @arg3: non-secure entry address (ARMv7 bootarg #0)
 */
void spl_optee_entry(void *arg0, void *arg1, void *arg2, void *arg3);

/**
 * spl_invoke_opensbi - boot using a RISC-V OpenSBI image
 */
void spl_invoke_opensbi(struct spl_image_info *spl_image);

/**
 * board_return_to_bootrom - allow for boards to continue with the boot ROM
 *
 * If a board (e.g. the Rockchip RK3368 boards) provide some
 * supporting functionality for SPL in their boot ROM and the SPL
 * stage wants to return to the ROM code to continue booting, boards
 * can implement 'board_return_to_bootrom'.
 */
int board_return_to_bootrom(struct spl_image_info *spl_image,
			    struct spl_boot_device *bootdev);

/**
 * board_spl_fit_post_load - allow process images after loading finished
 *
 */
void board_spl_fit_post_load(ulong load_addr, size_t length);

/**
 * board_spl_fit_size_align - specific size align before processing payload
 *
 */
ulong board_spl_fit_size_align(ulong size);

/**
 * spl_perform_fixups() - arch/board-specific callback before processing
 *                        the boot-payload
 */
void spl_perform_fixups(struct spl_image_info *spl_image);

/*
 * spl_get_load_buffer() - get buffer for loading partial image data
 *
 * Returns memory area which can be populated by partial image data,
 * ie. uImage or fitImage header.
 */
struct image_header *spl_get_load_buffer(ssize_t offset, size_t size);

#endif
Commit	Line	Data
83d290c5	1	/* SPDX-License-Identifier: GPL-2.0+ */
47f7bcae TR	2	/*
	3	* (C) Copyright 2012
	4	* Texas Instruments, <www.ti.com>
47f7bcae TR	5	*/
	6	#ifndef _SPL_H_
	7	#define _SPL_H_
	8
8bee2d25 SG	9	#include <binman_sym.h>
8bee2d25 SG	10
47f7bcae	11	/* Platform-specific defines */
6507f133	12	#include <linux/compiler.h>
47f7bcae	13	#include <asm/spl.h>
b0edea3c	14	#include <handoff.h>
47f7bcae	15
32ba8952 SG	16	/* Value in r0 indicates we booted from U-Boot */
32ba8952 SG	17	#define UBOOT_NOT_LOADED_FROM_SPL 0x13578642
773b5940	18
47f7bcae TR	19	/* Boot type */
	20	#define MMCSD_MODE_UNDEFINED 0
	21	#define MMCSD_MODE_RAW 1
205b4f33	22	#define MMCSD_MODE_FS 2
7dbe63bc	23	#define MMCSD_MODE_EMMCBOOT 3
47f7bcae	24
e945a726 SG	25	/*
	26	* u_boot_first_phase() - check if this is the first U-Boot phase
	27	*
	28	* U-Boot has up to three phases: TPL, SPL and U-Boot proper. Depending on the
	29	* build flags we can determine whether the current build is for the first
	30	* phase of U-Boot or not. If there is no SPL, then this is U-Boot proper. If
	31	* there is SPL but no TPL, the the first phase is SPL. If there is TPL, then
	32	* it is the first phase.
	33	*
	34	* @returns true if this is the first phase of U-Boot
	35	*
	36	*/
	37	static inline bool u_boot_first_phase(void)
	38	{
	39	if (IS_ENABLED(CONFIG_TPL)) {
	40	if (IS_ENABLED(CONFIG_TPL_BUILD))
	41	return true;
	42	} else if (IS_ENABLED(CONFIG_SPL)) {
	43	if (IS_ENABLED(CONFIG_SPL_BUILD))
	44	return true;
	45	} else {
	46	return true;
	47	}
	48
	49	return false;
	50	}
	51
8e83b76d	52	enum u_boot_phase {
59c871bc SG	53	PHASE_TPL, /* Running in TPL */
	54	PHASE_SPL, /* Running in SPL */
	55	PHASE_BOARD_F, /* Running in U-Boot before relocation */
	56	PHASE_BOARD_R, /* Running in U-Boot after relocation */
8e83b76d SG	57	};
	58
	59	/**
	60	* spl_phase() - Find out the phase of U-Boot
	61	*
	62	* This can be used to avoid #ifdef logic and use if() instead.
	63	*
	64	* For example, to include code only in TPL, you might do:
	65	*
	66	* #ifdef CONFIG_TPL_BUILD
	67	* ...
	68	* #endif
	69	*
	70	* but with this you can use:
	71	*
	72	* if (spl_phase() == PHASE_TPL) {
	73	* ...
	74	* }
	75	*
	76	* To include code only in SPL, you might do:
	77	*
	78	* #if defined(CONFIG_SPL_BUILD) && !defined(CONFIG_TPL_BUILD)
	79	* ...
	80	* #endif
	81	*
	82	* but with this you can use:
	83	*
	84	* if (spl_phase() == PHASE_SPL) {
	85	* ...
	86	* }
	87	*
	88	* To include code only in U-Boot proper, you might do:
	89	*
	90	* #ifndef CONFIG_SPL_BUILD
	91	* ...
	92	* #endif
	93	*
	94	* but with this you can use:
	95	*
59c871bc	96	* if (spl_phase() == PHASE_BOARD_F) {
8e83b76d SG	97	* ...
	98	* }
	99	*
	100	* @return U-Boot phase
	101	*/
	102	static inline enum u_boot_phase spl_phase(void)
	103	{
	104	#ifdef CONFIG_TPL_BUILD
	105	return PHASE_TPL;
	106	#elif CONFIG_SPL_BUILD
	107	return PHASE_SPL;
	108	#else
59c871bc SG	109	DECLARE_GLOBAL_DATA_PTR;
	110
	111	if (!(gd->flags & GD_FLG_RELOC))
	112	return PHASE_BOARD_F;
	113	else
	114	return PHASE_BOARD_R;
8e83b76d SG	115	#endif
	116	}
	117
d6330064 SG	118	/* A string name for SPL or TPL */
	119	#ifdef CONFIG_SPL_BUILD
	120	# ifdef CONFIG_TPL_BUILD
8fb2391e	121	# define SPL_TPL_NAME "TPL"
d6330064	122	# else
8fb2391e	123	# define SPL_TPL_NAME "SPL"
d6330064 SG	124	# endif
	125	# define SPL_TPL_PROMPT SPL_TPL_NAME ": "
	126	#else
	127	# define SPL_TPL_NAME ""
	128	# define SPL_TPL_PROMPT ""
	129	#endif
	130
47f7bcae TR	131	struct spl_image_info {
	132	const char *name;
	133	u8 os;
f2efe678 PT	134	uintptr_t load_addr;
f2efe678 PT	135	uintptr_t entry_point;
a9a8271e	136	#if CONFIG_IS_ENABLED(LOAD_FIT) \|\| CONFIG_IS_ENABLED(LOAD_FIT_FULL)
75014470 PT	137	void *fdt_addr;
75014470 PT	138	#endif
de5dd4c4	139	u32 boot_device;
47f7bcae	140	u32 size;
022b4975	141	u32 flags;
5bf5250e	142	void *arg;
dae5c2dc SG	143	#ifdef CONFIG_SPL_LEGACY_IMAGE_CRC_CHECK
	144	ulong dcrc_data;
	145	ulong dcrc_length;
	146	ulong dcrc;
	147	#endif
47f7bcae TR	148	};
47f7bcae TR	149
f1dcee59 SG	150	/*
	151	* Information required to load data from a device
	152	*
	153	* @dev: Pointer to the device, e.g. struct mmc *
	154	* @priv: Private data for the device
	155	* @bl_len: Block length for reading in bytes
eafd5410	156	* @filename: Name of the fit image file.
f1dcee59 SG	157	* @read: Function to call to read from the device
	158	*/
	159	struct spl_load_info {
	160	void *dev;
	161	void *priv;
	162	int bl_len;
eafd5410	163	const char *filename;
f1dcee59 SG	164	ulong (read)(struct spl_load_info load, ulong sector, ulong count,
	165	void *buf);
	166	};
	167
8bee2d25 SG	168	/*
	169	* We need to know the position of U-Boot in memory so we can jump to it. We
	170	* allow any U-Boot binary to be used (u-boot.bin, u-boot-nodtb.bin,
	171	* u-boot.img), hence the '_any'. These is no checking here that the correct
	172	* image is found. For * example if u-boot.img is used we don't check that
	173	* spl_parse_image_header() can parse a valid header.
	174	*/
dbf6be9f	175	binman_sym_extern(ulong, u_boot_any, image_pos);
8bee2d25	176
e1eb6ada AD	177	/**
	178	* spl_load_simple_fit_skip_processing() - Hook to allow skipping the FIT
	179	* image processing during spl_load_simple_fit().
	180	*
	181	* Return true to skip FIT processing, false to preserve the full code flow
	182	* of spl_load_simple_fit().
	183	*/
	184	bool spl_load_simple_fit_skip_processing(void);
	185
eafd5410 LV	186	/**
eafd5410 LV	187	* spl_load_simple_fit() - Loads a fit image from a device.
f4d7d859	188	* @spl_image: Image description to set up
eafd5410 LV	189	* @info: Structure containing the information required to load data.
	190	* @sector: Sector number where FIT image is located in the device
	191	* @fdt: Pointer to the copied FIT header.
	192	*
	193	* Reads the FIT image @sector in the device. Loads u-boot image to
	194	* specified load address and copies the dtb to end of u-boot image.
	195	* Returns 0 on success.
	196	*/
f4d7d859 SG	197	int spl_load_simple_fit(struct spl_image_info *spl_image,
f4d7d859 SG	198	struct spl_load_info info, ulong sector, void fdt);
f1dcee59	199
022b4975	200	#define SPL_COPY_PAYLOAD_ONLY 1
e246bfcf	201	#define SPL_FIT_FOUND 2
022b4975	202
dd7d0911 PF	203	/**
	204	* spl_load_imx_container() - Loads a imx container image from a device.
	205	* @spl_image: Image description to set up
	206	* @info: Structure containing the information required to load data.
	207	* @sector: Sector number where container image is located in the device
	208	*
	209	* Reads the container image @sector in the device. Loads u-boot image to
	210	* specified load address.
	211	*/
	212	int spl_load_imx_container(struct spl_image_info *spl_image,
	213	struct spl_load_info *info, ulong sector);
	214
47f7bcae TR	215	/* SPL common functions */
	216	void preloader_console_init(void);
	217	u32 spl_boot_device(void);
2b1cdafa	218	u32 spl_boot_mode(const u32 boot_device);
35a66960	219	int spl_boot_partition(const u32 boot_device);
d1fc0a31	220	void spl_set_bd(void);
d95ceb97 SG	221
	222	/**
	223	* spl_set_header_raw_uboot() - Set up a standard SPL image structure
	224	*
	225	* This sets up the given spl_image which the standard values obtained from
	226	* config options: CONFIG_SYS_MONITOR_LEN, CONFIG_SYS_UBOOT_START,
	227	* CONFIG_SYS_TEXT_BASE.
	228	*
71316c1d	229	* @spl_image: Image description to set up
d95ceb97 SG	230	*/
	231	void spl_set_header_raw_uboot(struct spl_image_info *spl_image);
	232
71316c1d SG	233	/**
	234	* spl_parse_image_header() - parse the image header and set up info
	235	*
	236	* This parses the legacy image header information at @header and sets up
	237	* @spl_image according to what is found. If no image header is found, then
	238	* a raw image or bootz is assumed. If CONFIG_SPL_PANIC_ON_RAW_IMAGE is
24eb39b5	239	* enabled, then this causes a panic. If CONFIG_SPL_RAW_IMAGE_SUPPORT is not
71316c1d SG	240	* enabled then U-Boot gives up. Otherwise U-Boot sets up the image using
	241	* spl_set_header_raw_uboot(), or possibly the bootz header.
	242	*
	243	* @spl_image: Image description to set up
	244	* @header image header to parse
	245	* @return 0 if a header was correctly parsed, -ve on error
	246	*/
	247	int spl_parse_image_header(struct spl_image_info *spl_image,
	248	const struct image_header *header);
	249
47f7bcae	250	void spl_board_prepare_for_linux(void);
3a3b9147	251	void spl_board_prepare_for_boot(void);
bf55cd4f	252	int spl_board_ubi_load_image(u32 boot_device);
ca12e65c SG	253
	254	/**
	255	* jump_to_image_linux() - Jump to a Linux kernel from SPL
	256	*
	257	* This jumps into a Linux kernel using the information in @spl_image.
	258	*
	259	* @spl_image: Image description to set up
ca12e65c	260	*/
5bf5250e	261	void __noreturn jump_to_image_linux(struct spl_image_info *spl_image);
f59961e3 SG	262
	263	/**
	264	* spl_start_uboot() - Check if SPL should start the kernel or U-Boot
	265	*
	266	* This is called by the various SPL loaders to determine whether the board
	267	* wants to load the kernel or U-Boot. This function should be provided by
	268	* the board.
	269	*
	270	* @return 0 if SPL should start the kernel, 1 if U-Boot must be started
	271	*/
47f7bcae	272	int spl_start_uboot(void);
f59961e3	273
a807ab33 SG	274	/**
	275	* spl_display_print() - Display a board-specific message in SPL
	276	*
	277	* If CONFIG_SPL_DISPLAY_PRINT is enabled, U-Boot will call this function
	278	* immediately after displaying the SPL console banner ("U-Boot SPL ...").
	279	* This function should be provided by the board.
	280	*/
47f7bcae TR	281	void spl_display_print(void);
47f7bcae TR	282
ecdfd69a SG	283	/**
	284	* struct spl_boot_device - Describes a boot device used by SPL
	285	*
	286	* @boot_device: A number indicating the BOOT_DEVICE type. There are various
	287	* BOOT_DEVICE... #defines and enums in U-Boot and they are not consistently
	288	* numbered.
	289	* @boot_device_name: Named boot device, or NULL if none.
	290	*
	291	* Note: Additional fields can be added here, bearing in mind that SPL is
	292	* size-sensitive and common fields will be present on all boards. This
	293	* struct can also be used to return additional information about the load
	294	* process if that becomes useful.
	295	*/
	296	struct spl_boot_device {
	297	uint boot_device;
	298	const char *boot_device_name;
	299	};
	300
a0a80290 SG	301	/**
	302	* Holds information about a way of loading an SPL image
	303	*
ebc4ef61	304	* @name: User-friendly name for this method (e.g. "MMC")
a0a80290 SG	305	* @boot_device: Boot device that this loader supports
	306	* @load_image: Function to call to load image
	307	*/
	308	struct spl_image_loader {
ebc4ef61 SG	309	#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT
	310	const char *name;
	311	#endif
a0a80290 SG	312	uint boot_device;
	313	/**
	314	* load_image() - Load an SPL image
	315	*
2a2ee2ac	316	* @spl_image: place to put image information
a0a80290 SG	317	* @bootdev: describes the boot device to load from
a0a80290 SG	318	*/
2a2ee2ac SG	319	int (load_image)(struct spl_image_info spl_image,
2a2ee2ac SG	320	struct spl_boot_device *bootdev);
a0a80290 SG	321	};
	322
	323	/* Declare an SPL image loader */
	324	#define SPL_LOAD_IMAGE(__name) \
	325	ll_entry_declare(struct spl_image_loader, __name, spl_image_loader)
	326
	327	/*
0d3b0591	328	* _priority is the priority of this method, 0 meaning it will be the top
a0a80290	329	* choice for this device, 9 meaning it is the bottom choice.
0d3b0591 SG	330	* _boot_device is the BOOT_DEVICE_... value
0d3b0591 SG	331	* _method is the load_image function to call
a0a80290	332	*/
ebc4ef61 SG	333	#ifdef CONFIG_SPL_LIBCOMMON_SUPPORT
	334	#define SPL_LOAD_IMAGE_METHOD(_name, _priority, _boot_device, _method) \
	335	SPL_LOAD_IMAGE(_method ## _priority ## _boot_device) = { \
	336	.name = _name, \
	337	.boot_device = _boot_device, \
	338	.load_image = _method, \
	339	}
	340	#else
	341	#define SPL_LOAD_IMAGE_METHOD(_name, _priority, _boot_device, _method) \
0d3b0591 SG	342	SPL_LOAD_IMAGE(_method ## _priority ## _boot_device) = { \
	343	.boot_device = _boot_device, \
	344	.load_image = _method, \
a0a80290	345	}
ebc4ef61	346	#endif
a0a80290	347
773b5940	348	/* SPL FAT image functions */
710e9ca5 SG	349	int spl_load_image_fat(struct spl_image_info *spl_image,
710e9ca5 SG	350	struct blk_desc *block_dev, int partition,
4101f687	351	const char *filename);
710e9ca5 SG	352	int spl_load_image_fat_os(struct spl_image_info *spl_image,
710e9ca5 SG	353	struct blk_desc *block_dev, int partition);
773b5940	354
ce048224 JH	355	void __noreturn jump_to_image_no_args(struct spl_image_info *spl_image);
ce048224 JH	356
592f9222	357	/* SPL EXT image functions */
b4a6c2aa SG	358	int spl_load_image_ext(struct spl_image_info *spl_image,
b4a6c2aa SG	359	struct blk_desc *block_dev, int partition,
4101f687	360	const char *filename);
b4a6c2aa SG	361	int spl_load_image_ext_os(struct spl_image_info *spl_image,
b4a6c2aa SG	362	struct blk_desc *block_dev, int partition);
592f9222	363
070d00b8	364	/**
340f418a	365	* spl_early_init() - Set up device tree and driver model in SPL if enabled
070d00b8 SG	366	*
070d00b8 SG	367	* Call this function in board_init_f() if you want to use device tree and
340f418a EC	368	* driver model early, before board_init_r() is called.
	369	*
	370	* If this is not called, then driver model will be inactive in SPL's
	371	* board_init_f(), and no device tree will be available.
	372	*/
	373	int spl_early_init(void);
	374
	375	/**
	376	* spl_init() - Set up device tree and driver model in SPL if enabled
	377	*
	378	* You can optionally call spl_early_init(), then optionally call spl_init().
	379	* This function will be called from board_init_r() if not called earlier.
	380	*
	381	* Both spl_early_init() and spl_init() perform a similar function except that
	382	* the latter will not set up the malloc() area if
	383	* CONFIG_SPL_STACK_R_MALLOC_SIMPLE_LEN is enabled, since it is assumed to
	384	* already be done by a calll to spl_relocate_stack_gd() before board_init_r()
	385	* is reached.
	386	*
	387	* This function will be called from board_init_r() if not called earlier.
070d00b8 SG	388	*
	389	* If this is not called, then driver model will be inactive in SPL's
	390	* board_init_f(), and no device tree will be available.
	391	*/
	392	int spl_init(void);
	393
47f7bcae TR	394	#ifdef CONFIG_SPL_BOARD_INIT
	395	void spl_board_init(void);
	396	#endif
32ba8952 SG	397
	398	/**
	399	* spl_was_boot_source() - check if U-Boot booted from SPL
	400	*
	401	* This will normally be true, but if U-Boot jumps to second U-Boot, it will
	402	* be false. This should be implemented by board-specific code.
	403	*
	404	* @return true if U-Boot booted from SPL, else false
	405	*/
	406	bool spl_was_boot_source(void);
	407
52f2acc5 R	408	/**
	409	* spl_dfu_cmd- run dfu command with chosen mmc device interface
	410	* @param usb_index - usb controller number
	411	* @param mmc_dev - mmc device nubmer
	412	*
	413	* @return 0 on success, otherwise error code
	414	*/
	415	int spl_dfu_cmd(int usbctrl, char dfu_alt_info, char interface, char *devstr);
e50d76cc	416
09410c65 MV	417	int spl_mmc_load_image(struct spl_image_info *spl_image,
	418	struct spl_boot_device *bootdev);
	419
e1eb6ada AD	420	/**
	421	* spl_mmc_load() - Load an image file from MMC/SD media
	422	*
	423	* @param spl_image Image data filled in by loading process
	424	* @param bootdev Describes which device to load from
	425	* @param filename Name of file to load (in FS mode)
	426	* @param raw_part Partition to load from (in RAW mode)
	427	* @param raw_sect Sector to load from (in RAW mode)
	428	*
	429	* @return 0 on success, otherwise error code
	430	*/
	431	int spl_mmc_load(struct spl_image_info *spl_image,
	432	struct spl_boot_device *bootdev,
	433	const char *filename,
	434	int raw_part,
	435	unsigned long raw_sect);
	436
e413033d AD	437	int spl_ymodem_load_image(struct spl_image_info *spl_image,
	438	struct spl_boot_device *bootdev);
	439
f2efe678 PT	440	/**
	441	* spl_invoke_atf - boot using an ARM trusted firmware image
	442	*/
	443	void spl_invoke_atf(struct spl_image_info *spl_image);
225d30b7	444
70fe2876 KY	445	/**
	446	* spl_optee_entry - entry function for optee
	447	*
	448	* args defind in op-tee project
	449	* https://github.com/OP-TEE/optee_os/
	450	* core/arch/arm/kernel/generic_entry_a32.S
	451	* @arg0: pagestore
	452	* @arg1: (ARMv7 standard bootarg #1)
	453	* @arg2: device tree address, (ARMv7 standard bootarg #2)
	454	* @arg3: non-secure entry address (ARMv7 bootarg #0)
	455	*/
	456	void spl_optee_entry(void arg0, void arg1, void arg2, void arg3);
	457
5e30e45c LA	458	/**
	459	* spl_invoke_opensbi - boot using a RISC-V OpenSBI image
	460	*/
	461	void spl_invoke_opensbi(struct spl_image_info *spl_image);
	462
225d30b7 PT	463	/**
	464	* board_return_to_bootrom - allow for boards to continue with the boot ROM
	465	*
	466	* If a board (e.g. the Rockchip RK3368 boards) provide some
	467	* supporting functionality for SPL in their boot ROM and the SPL
	468	* stage wants to return to the ROM code to continue booting, boards
	469	* can implement 'board_return_to_bootrom'.
	470	*/
cda789a5 PF	471	int board_return_to_bootrom(struct spl_image_info *spl_image,
cda789a5 PF	472	struct spl_boot_device *bootdev);
de5dd4c4	473
28ded1f3 PF	474	/**
	475	* board_spl_fit_post_load - allow process images after loading finished
	476	*
	477	*/
	478	void board_spl_fit_post_load(ulong load_addr, size_t length);
	479
	480	/**
	481	* board_spl_fit_size_align - specific size align before processing payload
	482	*
	483	*/
	484	ulong board_spl_fit_size_align(ulong size);
	485
de5dd4c4 PT	486	/**
	487	* spl_perform_fixups() - arch/board-specific callback before processing
	488	* the boot-payload
	489	*/
	490	void spl_perform_fixups(struct spl_image_info *spl_image);
04ce5427 MV	491
	492	/*
	493	* spl_get_load_buffer() - get buffer for loading partial image data
	494	*
	495	* Returns memory area which can be populated by partial image data,
	496	* ie. uImage or fitImage header.
	497	*/
	498	struct image_header *spl_get_load_buffer(ssize_t offset, size_t size);
	499
47f7bcae	500	#endif