1 /*
2  * Arm SCP/MCP Software
3  * Copyright (c) 2017-2021, Arm Limited and Contributors. All rights reserved.
4  *
5  * SPDX-License-Identifier: BSD-3-Clause
6  */
7 
8 #ifndef MOD_BOOTLOADER_H
9 #define MOD_BOOTLOADER_H
10 
11 #include <fwk_element.h>
12 
13 #include <stddef.h>
14 #include <stdint.h>
15 
16 /*!
17  * \addtogroup GroupModules Modules
18  * \{
19  */
20 
21 /*!
22  * \defgroup GroupBoot Bootloader
23  *
24  * \details A service module providing support for loading firmware images.
25  *
26  * \{
27  */
28 
29 /*!
30  * \brief Module configuration.
31  */
32 struct mod_bootloader_config {
33     /*!
34      * Base address of the memory region that the image will be copied from.
35      * Note that this is not the base address of the image to be loaded.
36      *
37      * Note that if Shared Data Storage (SDS) is used for the booting process
38      * then this is not the base address of the image to be loaded. In this
39      * situation the base address is combined with an offset value, provided by
40      * the application processor firmware, via a Shared Data Storage region.
41      */
42     uintptr_t source_base;
43 
44     /*!
45      * The number of bytes of storage available at the source location.
46      * This value implicitly limits the maximum size of the image that can be
47      * copied.
48      */
49     uint32_t source_size;
50 
51     /*! Base address of the location that the image will be copied to. */
52     uintptr_t destination_base;
53 
54     /*!
55      * The number of bytes of storage available at the destination location.
56      * This value implicitly limits the maximum size of the image that can be
57      * copied.
58      */
59     uint32_t destination_size;
60 
61 #ifdef BUILD_HAS_MOD_SDS
62     /*!
63      * Identifier of the SDS structure containing image metadata, such as the
64      * size of the image and its offset from source_base.
65      */
66     uint32_t sds_struct_id;
67 #endif
68 };
69 
70 /*!
71  * \brief Bootloader interface.
72  */
73 struct mod_bootloader_api {
74     /*!
75      * \brief Copy a RAM Firmware image from a source location to a destination
76      *      (which is expected to be the SCP SRAM).
77      *
78      * \param config Pointer to an scp_bootloader_config structure containing
79      *      settings that control where the image is copied from and to.
80      *
81      * \retval ::FWK_SUCCESS The RAM Firmware image was copied successfully.
82      * \retval ::FWK_E_ALIGN The given image offset is not properly aligned.
83      * \retval ::FWK_E_DATA The image did not pass checksum validation.
84      * \retval ::FWK_E_PARAM An invalid parameter was encountered:
85      *      - The image source address is invalid.
86      *      - The image destination address is invalid.
87      *      - The image size is invalid.
88      * \retval ::FWK_E_SIZE A size-related issue was encountered:
89      *      - The given image size is below the minimum possible size.
90      *      - The image is too large for the destination memory area.
91      *      - The given image offset is beyond the source memory area.
92      *      - The header's size field does not match the given size.
93      *      - Part of the image lies outside of the source memory area.
94      */
95     int (*load_image)(void);
96 };
97 
98 /*!
99  * \}
100  */
101 
102 /*!
103  * \}
104  */
105 
106 #endif /* MOD_BOOTLOADER_H */
107