• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1You may also find it useful to refer to the in-tree `armv4t` and `armv4t_multicore` examples when transitioning between versions.
2
3# `0.4` -> `0.5`
4
5While the overall structure of the API has remained the same, `0.5.0` does introduce a few breaking API changes that require some attention. That being said, it should not be a difficult migration, and updating to `0.5.0` from `0.4` shouldn't take more than 10 mins of refactoring.
6
7Check out [`CHANGELOG.md`](../CHANGELOG.md) for a full list of changes.
8
9##### Consolidating the `{Hw,Sw}Breakpoint/Watchpoint` IDETs under the newly added `Breakpoints` IDETs.
10
11The various breakpoint IDETs that were previously directly implemented on the top-level `Target` trait have now been consolidated under a single `Breakpoints` IDET. This is purely an organizational change, and will not require rewriting any existing `{add, remove}_{sw_break,hw_break,watch}point` implementations.
12
13Porting from `0.4` to `0.5` should be as simple as:
14
15```rust
16// ==== 0.4.x ==== //
17
18impl Target for Emu {
19    fn sw_breakpoint(&mut self) -> Option<target::ext::breakpoints::SwBreakpointOps<Self>> {
20        Some(self)
21    }
22
23    fn hw_watchpoint(&mut self) -> Option<target::ext::breakpoints::HwWatchpointOps<Self>> {
24        Some(self)
25    }
26}
27
28impl target::ext::breakpoints::SwBreakpoint for Emu {
29    fn add_sw_breakpoint(&mut self, addr: u32) -> TargetResult<bool, Self> { ... }
30    fn remove_sw_breakpoint(&mut self, addr: u32) -> TargetResult<bool, Self> { ... }
31}
32
33impl target::ext::breakpoints::HwWatchpoint for Emu {
34    fn add_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
35    fn remove_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
36}
37
38// ==== 0.5.0 ==== //
39
40impl Target for Emu {
41    // (New Method) //
42    fn breakpoints(&mut self) -> Option<target::ext::breakpoints::BreakpointsOps<Self>> {
43        Some(self)
44    }
45}
46
47impl target::ext::breakpoints::Breakpoints for Emu {
48    fn sw_breakpoint(&mut self) -> Option<target::ext::breakpoints::SwBreakpointOps<Self>> {
49        Some(self)
50    }
51
52    fn hw_watchpoint(&mut self) -> Option<target::ext::breakpoints::HwWatchpointOps<Self>> {
53        Some(self)
54    }
55}
56
57// (Almost Unchanged) //
58impl target::ext::breakpoints::SwBreakpoint for Emu {
59    //                                            /-- New `kind` parameter
60    //                                           \/
61    fn add_sw_breakpoint(&mut self, addr: u32, _kind: arch::arm::ArmBreakpointKind) -> TargetResult<bool, Self> { ... }
62    fn remove_sw_breakpoint(&mut self, addr: u32, _kind: arch::arm::ArmBreakpointKind) -> TargetResult<bool, Self> { ... }
63}
64
65// (Unchanged) //
66impl target::ext::breakpoints::HwWatchpoint for Emu {
67    fn add_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
68    fn remove_hw_watchpoint(&mut self, addr: u32, kind: WatchKind) -> TargetResult<bool, Self> { ... }
69}
70
71```
72
73##### Single-register access methods (`{read,write}_register`) are now a separate `SingleRegisterAccess` trait
74
75Single register access is not a required part of the GDB protocol, and as such, has been moved out into its own IDET. This is a purely organizational change, and will not require rewriting any existing `{read,write}_register` implementations.
76
77Porting from `0.4` to `0.5` should be as simple as:
78
79```rust
80// ==== 0.4.x ==== //
81
82impl SingleThreadOps for Emu {
83    fn read_register(&mut self, reg_id: arch::arm::reg::id::ArmCoreRegId, dst: &mut [u8]) -> TargetResult<(), Self> { ... }
84    fn write_register(&mut self, reg_id: arch::arm::reg::id::ArmCoreRegId, val: &[u8]) -> TargetResult<(), Self> { ... }
85}
86
87// ==== 0.5.0 ==== //
88
89impl SingleThreadOps for Emu {
90    // (New Method) //
91    fn single_register_access(&mut self) -> Option<target::ext::base::SingleRegisterAccessOps<(), Self>> {
92        Some(self)
93    }
94}
95
96impl target::ext::base::SingleRegisterAccess<()> for Emu {
97    //                           /-- New `tid` parameter (ignored on single-threaded systems)
98    //                          \/
99    fn read_register(&mut self, _tid: (), reg_id: arch::arm::reg::id::ArmCoreRegId, dst: &mut [u8]) -> TargetResult<(), Self> { ... }
100    fn write_register(&mut self, _tid: (), reg_id: arch::arm::reg::id::ArmCoreRegId, val: &[u8]) -> TargetResult<(), Self> { ... }
101}
102```
103
104##### New `MultiThreadOps::resume` API
105
106In `0.4`, resuming a multithreaded target was done using an `Actions` iterator passed to a single `resume` method. In hindsight, this approach had a couple issues:
107
108- It was impossible to statically enforce the property that the `Actions` iterator was guaranteed to return at least one element, often forcing users to manually `unwrap`
109- The iterator machinery was quite heavy, and did not optimize very effectively
110- Handling malformed packets encountered during iteration was tricky, as the user-facing API exposed an infallible iterator, thereby complicating the internal error handling
111- Adding new kinds of `ResumeAction` (e.g: range stepping) required a breaking change, and forced users to change their `resume` method implementation regardless whether or not their target ended up using said action.
112
113In `0.5`, the API has been refactored to address some of these issues, and the single `resume` method has now been split into multiple "lifecycle" methods:
114
1151. `resume`
116    - As before, when `resume` is called the target should resume execution.
117    - But how does the target know how each thread should be resumed? That's where the next method comes in...
1181. `set_resume_action`
119    - This method is called prior to `resume`, and notifies the target how a particular `Tid` should be resumed.
1201. (optionally) `set_resume_action_range_step`
121    - If the target supports optimized range-stepping, it can opt to implement the newly added `MultiThreadRangeStepping` IDET which includes this method.
122    - Targets that aren't interested in optimized range-stepping can skip this method!
1231. `clear_resume_actions`
124    - After the target returns a `ThreadStopReason` from `resume`, this method will be called to reset the previously set per-`tid` resume actions.
125
126NOTE: This change does mean that targets are now responsible for maintaining some internal state that maps `Tid`s to `ResumeAction`s. Thankfully, this isn't difficult at all, and can as simple as maintaining a `HashMap<Tid, ResumeAction>`.
127
128Please refer to the in-tree `armv4t_multicore` example for an example of how this new `resume` flow works.
129