kbe
3e294dc846
Introduces ApplicationFinder (by name/title/handle), Magic.Open overloads, and Magic.Threads/Regions/QueryRegion accessors. Closes section 3 of add-thread-region-finder and updates tasks/comparison doc.
58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Enumerate target threads
|
|
|
|
WhiteMagic SHALL enumerate the threads belonging to the target process and expose each as a controllable thread handle.
|
|
|
|
#### Scenario: enumerate returns the target's threads
|
|
- **WHEN** the threads of an open target are enumerated
|
|
- **THEN** the result MUST contain a handle for each thread owned by the target process and none owned by other processes
|
|
|
|
#### Scenario: resolve the main thread
|
|
- **WHEN** the main thread is requested
|
|
- **THEN** it MUST return the earliest-created thread of the target process
|
|
|
|
#### Scenario: get a thread by id
|
|
- **WHEN** a thread is requested by its thread id
|
|
- **THEN** it MUST return a handle bound to that thread, or fail deterministically if the id is not a thread of the target
|
|
|
|
### Requirement: Suspend and resume a thread
|
|
|
|
WhiteMagic SHALL suspend and resume an individual target thread and report the prior suspend count.
|
|
|
|
#### Scenario: suspend increments the suspend count
|
|
- **WHEN** a running thread is suspended
|
|
- **THEN** the thread MUST stop executing and the returned prior suspend count MUST reflect its state before the call
|
|
|
|
#### Scenario: resume restores execution
|
|
- **WHEN** a previously suspended thread is resumed to a zero suspend count
|
|
- **THEN** the thread MUST resume executing
|
|
|
|
### Requirement: Read and write thread context
|
|
|
|
WhiteMagic SHALL read and write a target thread's register context, selecting the context layout that matches the target's bitness.
|
|
|
|
#### Scenario: round-trip a register value
|
|
- **WHEN** a thread's context is read, a register is modified, and the context is written back
|
|
- **THEN** a subsequent read MUST reflect the modified register value
|
|
|
|
#### Scenario: bitness-correct context
|
|
- **WHEN** the target is a 32-bit (WOW64) process
|
|
- **THEN** the WOW64 context layout MUST be used, and for a 64-bit target the native layout MUST be used
|
|
|
|
### Requirement: Scoped thread freeze
|
|
|
|
WhiteMagic SHALL provide a scoped freeze that suspends a selected set of target threads and resumes exactly those threads when the scope is disposed, including when the guarded body throws.
|
|
|
|
#### Scenario: freeze suspends selected threads
|
|
- **WHEN** a freeze scope is created over a set of threads
|
|
- **THEN** each of those threads MUST be suspended for the duration of the scope
|
|
|
|
#### Scenario: dispose resumes only the frozen threads
|
|
- **WHEN** the freeze scope is disposed
|
|
- **THEN** exactly the threads it suspended MUST be resumed, and threads suspended by other callers MUST be left unchanged
|
|
|
|
#### Scenario: exception in the body still resumes
|
|
- **WHEN** the guarded body throws before the scope is disposed
|
|
- **THEN** the frozen threads MUST still be resumed as the scope unwinds
|