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    /// Attempted to call a vendor function that does not exist in the flash algorithm.
70    #[error("The '{name}' vendor-specific function does not exist in the flash algorithm.")]
71    VendorFunctionMissing {
72        /// The name of the routine that was called.
73        name: String,
74    },
75    /// Calling the given routine returned the given error code.
76    #[error(
77        "The execution of '{name}' failed with code {error_code}. This might indicate a problem with the flash algorithm."
78    )]
79    RoutineCallFailed {
80        /// The name of the routine that was called.
81        name: String,
82        /// The error code the called routine returned.
83        error_code: u32,
84    },
85    /// Failed to read the core status.
86    #[error("Failed to read the core status.")]
87    UnableToReadCoreStatus(#[source] error::Error),
88    /// The core entered an unexpected status while executing a flashing operation.
89    #[error("The core entered an unexpected status: {status:?}.")]
90    UnexpectedCoreStatus {
91        /// The status that the core entered.
92        status: crate::CoreStatus,
93    },
94    /// The given address was not contained in the given NVM region.
95    #[error("{address:#010x} is not contained in {region:?}")]
96    AddressNotInRegion {
97        /// The address which was not contained in `region`.
98        address: u32,
99        /// The region which did not contain `address`.
100        region: NvmRegion,
101    },
102    /// An error occurred during the interaction with the core.
103    #[error("Something during the interaction with the core went wrong")]
104    Core(#[source] error::Error),
105    /// Failed to reset, and then halt the CPU.
106    #[error("Failed to reset, and then halt the CPU.")]
107    ResetAndHalt(#[source] error::Error),
108    /// Failed to start running code on the CPU.
109    #[error("Failed to start running code on the CPU")]
110    Run(#[source] error::Error),
111    /// The RAM contents did not match the flash algorithm.
112    #[error(
113        "The RAM contents did not match the expected contents after loading the flash algorithm."
114    )]
115    FlashAlgorithmNotLoaded,
116    /// Failed to load the flash algorithm into RAM at given address. This can happen if there is not enough space.
117    ///
118    /// Check the algorithm code and settings before you try again.
119    #[error(
120        "Failed to load flash algorithm into RAM at address {address:#010x}. Is there space for the algorithm header?"
121    )]
122    InvalidFlashAlgorithmLoadAddress {
123        /// The address where the algorithm was supposed to be loaded to.
124        address: u64,
125    },
126    /// Failed to configure a valid stack size for the flash algorithm.
127    #[error("Failed to configure a stack of size {size} for the flash algorithm.")]
128    InvalidFlashAlgorithmStackSize {
129        /// The size of the stack that was tried to be configured.
130        size: u64,
131    },
132    /// Failed to configure the data region of a flash algorithm.
133    #[error(
134        "Failed to place data to address {data_load_addr:#010x} in RAM. The data must be placed in the range {data_ram:#x?}."
135    )]
136    InvalidDataAddress {
137        /// The address where the data was supposed to be loaded to.
138        data_load_addr: u64,
139        /// The range of the data memory.
140        data_ram: Range<u64>,
141    },
142    // TODO: Warn at YAML parsing stage.
143    // TODO: 1 Add information about flash (name, address)
144    // TODO: 2 Add source of target definition (built-in, yaml)
145    /// No flash algorithm was linked to this target.
146    #[error(
147        "Trying to write to flash region {range:#010x?}, but no suitable (default) flash loader algorithm is linked to the given target: {name}."
148    )]
149    NoFlashLoaderAlgorithmAttached {
150        /// The name of the chip.
151        name: String,
152        /// The memory region that was tried to be written.
153        range: Range<u64>,
154    },
155    /// More than one matching flash algorithm was found for the given memory range and all of them is marked as default.
156    #[error(
157        "Trying to write flash, but found more than one suitable flash loader algorithm marked as default for {region:?}."
158    )]
159    MultipleDefaultFlashLoaderAlgorithms {
160        /// The region which matched more than one flash algorithm.
161        region: NvmRegion,
162    },
163    /// More than one matching flash algorithm was found for the given memory range and none of them is marked as default.
164    #[error(
165        "Trying to write flash, but found more than one suitable flash algorithm but none marked as default for {region:?}."
166    )]
167    MultipleFlashLoaderAlgorithmsNoDefault {
168        /// The region which matched more than one flash algorithm.
169        region: NvmRegion,
170    },
171    /// Flash content verification failed.
172    #[error("Flash content verification failed.")]
173    Verify,
174    /// Failed to read flash size.
175    #[error("Failed to read flash size.")]
176    FlashSizeFailed {
177        /// The source error of this error.
178        #[source]
179        source: Box<dyn std::error::Error + 'static + Send + Sync>,
180    },
181    // TODO: 1 Add source of target definition
182    // TODO: 2 Do this at target load time.
183    /// The given chip has no RAM defined.
184    #[error("No suitable RAM region is defined for target: {name}.")]
185    NoRamDefined {
186        /// The name of the chip.
187        name: String,
188    },
189    /// The given flash algorithm did not have a length multiple of 4 bytes.
190    ///
191    /// This means that the flash algorithm that was loaded is broken.
192    #[error("Flash algorithm {name} does not have a length that is 4 byte aligned.")]
193    InvalidFlashAlgorithmLength {
194        /// The name of the flash algorithm.
195        name: String,
196        /// The source of the flash algorithm (was it a built in target or one loaded externally and from what file path?).
197        algorithm_source: Option<TargetDescriptionSource>,
198    },
199    /// Two blocks of data overlap each other which means the loaded binary is broken.
200    ///
201    /// Please check your data and try again.
202    #[error(
203        "Adding data for addresses {added_addresses:#010x?} overlaps previously added data for addresses {existing_addresses:#010x?}."
204    )]
205    DataOverlaps {
206        /// The address range that was tried to be added.
207        added_addresses: Range<u64>,
208        /// The address range that was already present.
209        existing_addresses: Range<u64>,
210    },
211    /// No core can access this NVM region.
212    #[error("No core can access the NVM region {0:?}.")]
213    NoNvmCoreAccess(NvmRegion),
214    /// No core can access this RAM region.
215    #[error("No core can access the RAM region {0:?}.")]
216    NoRamCoreAccess(RamRegion),
217    /// Stack overflow while flashing.
218    #[error("Stack overflow detected during {operation}.")]
219    StackOverflowDetected {
220        /// The operation that caused the stack overflow.
221        operation: &'static str,
222    },
223}
probe_rs/flashing/error.rs

probe_rs/flashing/
error.rs
