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.
42 lines
1.9 KiB
Markdown
42 lines
1.9 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Query the region containing an address
|
|
|
|
WhiteMagic SHALL return the mapped memory region that contains a given address, including its base, size, protection, state, and type.
|
|
|
|
#### Scenario: query a committed address
|
|
- **WHEN** the region containing a known committed address is queried
|
|
- **THEN** it MUST return a region whose base and size bracket that address and whose protection reflects the page's actual protection
|
|
|
|
#### Scenario: region membership test
|
|
- **WHEN** a region is asked whether it contains an address
|
|
- **THEN** it MUST return true only for addresses within `[base, base + size)`
|
|
|
|
### Requirement: Enumerate mapped regions
|
|
|
|
WhiteMagic SHALL enumerate the mapped memory regions of the target from the lowest address upward, lazily.
|
|
|
|
#### Scenario: enumeration walks the address space
|
|
- **WHEN** the target's regions are enumerated
|
|
- **THEN** the sequence MUST yield contiguous, non-overlapping regions ascending by base address until the end of the queryable address space
|
|
|
|
#### Scenario: early stop
|
|
- **WHEN** a caller stops consuming the enumeration after the first match
|
|
- **THEN** enumeration MUST NOT query the entire address space
|
|
|
|
### Requirement: Scoped protection change
|
|
|
|
WhiteMagic SHALL change the protection of a region and restore the original protection when the returned scope is disposed.
|
|
|
|
#### Scenario: protection is applied within the scope
|
|
- **WHEN** a protection-change scope is created for a region with a new protection
|
|
- **THEN** the region's protection MUST be the requested value for the duration of the scope
|
|
|
|
#### Scenario: protection is restored on dispose
|
|
- **WHEN** the protection-change scope is disposed
|
|
- **THEN** the region's protection MUST be restored to the value it had before the scope was created
|
|
|
|
#### Scenario: restore on exception
|
|
- **WHEN** the guarded body throws before the scope is disposed
|
|
- **THEN** the original protection MUST still be restored as the scope unwinds
|