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

probe_rs/flashing/
error.rs
