probe_rs/flashing/error.rs
1use crate::config::{NvmRegion, RamRegion, TargetDescriptionSource};
2use crate::error;
3use std::ops::Range;
4
5/// Describes any error that happened during the or in preparation for the flashing procedure.
6#[derive(thiserror::Error, Debug)]
7pub enum FlashError {
8 /// No flash algorithm was found by the given name.
9 #[error("The {name} target has no flash algorithm called {name}")]
10 AlgorithmNotFound {
11 /// The name of the target.
12 name: String,
13 /// The name of the algorithm that was not found.
14 algo_name: String,
15 },
16 /// Detected multiple preferred algorithms for the same flash region.
17 #[error("detected multiple preferred algorithms for a flash region {region:?}")]
18 MultiplePreferredAlgos {
19 /// The region which matched multiple preferred flash algorithms.
20 region: NvmRegion,
21 },
22 /// No flash memory contains the entire requested memory range.
23 #[error("No flash memory contains the entire requested memory range {range:#010X?}.")]
24 NoSuitableNvm {
25 /// The requested memory range.
26 range: Range<u64>,
27 /// The source of this target description (was it a built in target or one loaded externally and from what file path?).
28 description_source: TargetDescriptionSource,
29 },
30 /// Erasing the full chip flash failed.
31 #[error("Failed to erase the whole chip.")]
32 ChipEraseFailed {
33 /// The source error of this error.
34 source: Box<dyn std::error::Error + 'static + Send + Sync>,
35 },
36 /// Failed to read data from flash.
37 #[error("Failed to read data from flash.")]
38 FlashReadFailed {
39 /// The source error of this error.
40 source: Box<dyn std::error::Error + 'static + Send + Sync>,
41 },
42 /// Erasing the given flash sector failed.
43 #[error("Failed to erase flash sector at address {sector_address:#010x}.")]
44 EraseFailed {
45 /// The address of the sector that should have been erased.
46 sector_address: u64,
47 /// The source error of this error.
48 #[source]
49 source: Box<dyn std::error::Error + 'static + Send + Sync>,
50 },
51 /// Writing the given page failed.
52 #[error("The page write of the page at address {page_address:#010x} failed.")]
53 PageWrite {
54 /// The address of the page that should have been written.
55 page_address: u64,
56 /// The source error of this error.
57 #[source]
58 source: Box<dyn std::error::Error + 'static + Send + Sync>,
59 },
60 /// Initializing the flash algorithm failed.
61 #[error("The initialization of the flash algorithm failed.")]
62 Init(#[source] Box<dyn std::error::Error + 'static + Send + Sync>),
63 /// Uninitializing the flash algorithm failed.
64 #[error("The uninitialization of the flash algorithm failed.")]
65 Uninit(#[source] Box<dyn std::error::Error + 'static + Send + Sync>),
66 /// This target does not support full chip flash erases.
67 #[error("The chip erase routine is not supported with the given flash algorithm.")]
68 ChipEraseNotSupported,
69 /// Calling the given routine returned the given error code.
70 #[error(
71 "The execution of '{name}' failed with code {error_code}. This might indicate a problem with the flash algorithm."
72 )]
73 RoutineCallFailed {
74 /// The name of the routine that was called.
75 name: &'static str,
76 /// The error code the called routine returned.
77 error_code: u32,
78 },
79 /// Failed to read the core status.
80 #[error("Failed to read the core status.")]
81 UnableToReadCoreStatus(#[source] error::Error),
82 /// The core entered an unexpected status while executing a flashing operation.
83 #[error("The core entered an unexpected status: {status:?}.")]
84 UnexpectedCoreStatus {
85 /// The status that the core entered.
86 status: crate::CoreStatus,
87 },
88 /// The given address was not contained in the given NVM region.
89 #[error("{address:#010x} is not contained in {region:?}")]
90 AddressNotInRegion {
91 /// The address which was not contained in `region`.
92 address: u32,
93 /// The region which did not contain `address`.
94 region: NvmRegion,
95 },
96 /// An error occurred during the interaction with the core.
97 #[error("Something during the interaction with the core went wrong")]
98 Core(#[source] error::Error),
99 /// Failed to reset, and then halt the CPU.
100 #[error("Failed to reset, and then halt the CPU.")]
101 ResetAndHalt(#[source] error::Error),
102 /// Failed to start running code on the CPU.
103 #[error("Failed to start running code on the CPU")]
104 Run(#[source] error::Error),
105 /// The RAM contents did not match the flash algorithm.
106 #[error(
107 "The RAM contents did not match the expected contents after loading the flash algorithm."
108 )]
109 FlashAlgorithmNotLoaded,
110 /// Failed to load the flash algorithm into RAM at given address. This can happen if there is not enough space.
111 ///
112 /// Check the algorithm code and settings before you try again.
113 #[error(
114 "Failed to load flash algorithm into RAM at address {address:#010x}. Is there space for the algorithm header?"
115 )]
116 InvalidFlashAlgorithmLoadAddress {
117 /// The address where the algorithm was supposed to be loaded to.
118 address: u64,
119 },
120 /// Failed to configure a valid stack size for the flash algorithm.
121 #[error("Failed to configure a stack of size {size} for the flash algorithm.")]
122 InvalidFlashAlgorithmStackSize {
123 /// The size of the stack that was tried to be configured.
124 size: u64,
125 },
126 /// Failed to configure the data region of a flash algorithm.
127 #[error(
128 "Failed to place data to address {data_load_addr:#010x} in RAM. The data must be placed in the range {data_ram:#x?}."
129 )]
130 InvalidDataAddress {
131 /// The address where the data was supposed to be loaded to.
132 data_load_addr: u64,
133 /// The range of the data memory.
134 data_ram: Range<u64>,
135 },
136 // TODO: Warn at YAML parsing stage.
137 // TODO: 1 Add information about flash (name, address)
138 // TODO: 2 Add source of target definition (built-in, yaml)
139 /// No flash algorithm was linked to this target.
140 #[error(
141 "Trying to write to flash region {range:#010x?}, but no suitable (default) flash loader algorithm is linked to the given target: {name}."
142 )]
143 NoFlashLoaderAlgorithmAttached {
144 /// The name of the chip.
145 name: String,
146 /// The memory region that was tried to be written.
147 range: Range<u64>,
148 },
149 /// More than one matching flash algorithm was found for the given memory range and all of them is marked as default.
150 #[error(
151 "Trying to write flash, but found more than one suitable flash loader algorithim marked as default for {region:?}."
152 )]
153 MultipleDefaultFlashLoaderAlgorithms {
154 /// The region which matched more than one flash algorithm.
155 region: NvmRegion,
156 },
157 /// More than one matching flash algorithm was found for the given memory range and none of them is marked as default.
158 #[error(
159 "Trying to write flash, but found more than one suitable flash algorithims but none marked as default for {region:?}."
160 )]
161 MultipleFlashLoaderAlgorithmsNoDefault {
162 /// The region which matched more than one flash algorithm.
163 region: NvmRegion,
164 },
165 /// Flash content verification failed.
166 #[error("Flash content verification failed.")]
167 Verify,
168 /// Failed to read flash size.
169 #[error("Failed to read flash size.")]
170 FlashSizeFailed {
171 /// The source error of this error.
172 #[source]
173 source: Box<dyn std::error::Error + 'static + Send + Sync>,
174 },
175 // TODO: 1 Add source of target definition
176 // TOOD: 2 Do this at target load time.
177 /// The given chip has no RAM defined.
178 #[error("No suitable RAM region is defined for target: {name}.")]
179 NoRamDefined {
180 /// The name of the chip.
181 name: String,
182 },
183 /// The given flash algorithm did not have a length multiple of 4 bytes.
184 ///
185 /// This means that the flash algorithm that was loaded is broken.
186 #[error("Flash algorithm {name} does not have a length that is 4 byte aligned.")]
187 InvalidFlashAlgorithmLength {
188 /// The name of the flash algorithm.
189 name: String,
190 /// The source of the flash algorithm (was it a built in target or one loaded externally and from what file path?).
191 algorithm_source: Option<TargetDescriptionSource>,
192 },
193 /// Two blocks of data overlap each other which means the loaded binary is broken.
194 ///
195 /// Please check your data and try again.
196 #[error(
197 "Adding data for addresses {added_addresses:#010x?} overlaps previously added data for addresses {existing_addresses:#010x?}."
198 )]
199 DataOverlaps {
200 /// The address range that was tried to be added.
201 added_addresses: Range<u64>,
202 /// The address range that was already present.
203 existing_addresses: Range<u64>,
204 },
205 /// No core can access this NVM region.
206 #[error("No core can access the NVM region {0:?}.")]
207 NoNvmCoreAccess(NvmRegion),
208 /// No core can access this RAM region.
209 #[error("No core can access the RAM region {0:?}.")]
210 NoRamCoreAccess(RamRegion),
211 /// The register value supplied for this flash algorithm is out of the supported range.
212 #[error("The register value {0:#010x} is out of the supported range.")]
213 RegisterValueNotSupported(u64),
214 /// Stack overflow while flashing.
215 #[error("Stack overflow detected during {operation}.")]
216 StackOverflowDetected {
217 /// The operation that caused the stack overflow.
218 operation: &'static str,
219 },
220}