Safe Haskell | None |
---|---|
Language | Haskell2010 |
Data.Macaw.Discovery.State
Description
This defines the data structures for storing information learned from
code discovery. The DiscoveryState
is the main data structure
representing this information.
Synopsis
- data DiscoveryState arch
- type AddrSymMap (w :: Nat) = Map (MemSegmentOff w) ByteString
- exploredFunctions :: DiscoveryState arch -> [Some (DiscoveryFunInfo arch)]
- ppDiscoveryStateBlocks :: DiscoveryState arch -> Doc ann
- emptyDiscoveryState :: Memory (ArchAddrWidth arch) -> AddrSymMap (ArchAddrWidth arch) -> ArchitectureInfo arch -> DiscoveryState arch
- memory :: DiscoveryState arch -> Memory (ArchAddrWidth arch)
- symbolNames :: DiscoveryState arch -> AddrSymMap (ArchAddrWidth arch)
- archInfo :: DiscoveryState arch -> ArchitectureInfo arch
- data GlobalDataInfo w
- = JumpTable !(Maybe w)
- | ReferencedValue
- globalDataMap :: forall arch f. Functor f => (Map (ArchMemAddr arch) (GlobalDataInfo (ArchMemAddr arch)) -> f (Map (ArchMemAddr arch) (GlobalDataInfo (ArchMemAddr arch)))) -> DiscoveryState arch -> f (DiscoveryState arch)
- funInfo :: forall arch f. Functor f => (Map (ArchSegmentOff arch) (Some (DiscoveryFunInfo arch)) -> f (Map (ArchSegmentOff arch) (Some (DiscoveryFunInfo arch)))) -> DiscoveryState arch -> f (DiscoveryState arch)
- type UnexploredFunctionMap arch = Map (ArchSegmentOff arch) (FunctionExploreReason (ArchAddrWidth arch))
- unexploredFunctions :: forall arch f. Functor f => (UnexploredFunctionMap arch -> f (UnexploredFunctionMap arch)) -> DiscoveryState arch -> f (DiscoveryState arch)
- data NoReturnFunStatus
- trustedFunctionEntryPoints :: forall arch f. Functor f => (Map (ArchSegmentOff arch) NoReturnFunStatus -> f (Map (ArchSegmentOff arch) NoReturnFunStatus)) -> DiscoveryState arch -> f (DiscoveryState arch)
- exploreFnPred :: forall arch f. Functor f => ((ArchSegmentOff arch -> Bool) -> f (ArchSegmentOff arch -> Bool)) -> DiscoveryState arch -> f (DiscoveryState arch)
- data DiscoveryFunInfo arch ids = DiscoveryFunInfo {
- discoveredFunReason :: !(FunctionExploreReason (ArchAddrWidth arch))
- discoveredFunAddr :: !(ArchSegmentOff arch)
- discoveredFunSymbol :: !(Maybe ByteString)
- _parsedBlocks :: !(Map (ArchSegmentOff arch) (ParsedBlock arch ids))
- discoveredClassifyFailureResolutions :: [(ArchSegmentOff arch, [ArchSegmentOff arch])]
- discoveredFunName :: MemWidth (ArchAddrWidth arch) => DiscoveryFunInfo arch ids -> ByteString
- parsedBlocks :: forall arch ids f. Functor f => (Map (ArchSegmentOff arch) (ParsedBlock arch ids) -> f (Map (ArchSegmentOff arch) (ParsedBlock arch ids))) -> DiscoveryFunInfo arch ids -> f (DiscoveryFunInfo arch ids)
- data ParsedBlock arch ids = ParsedBlock {
- pblockAddr :: !(ArchSegmentOff arch)
- pblockPrecond :: !(Either String (ArchBlockPrecond arch))
- blockSize :: !Int
- blockReason :: !(BlockExploreReason (ArchAddrWidth arch))
- blockAbstractState :: !(AbsBlockState (ArchReg arch))
- blockJumpBounds :: !(InitJumpBounds arch)
- pblockStmts :: ![Stmt arch ids]
- pblockTermStmt :: !(ParsedTermStmt arch ids)
- data ParsedTermStmt arch ids
- = ParsedCall !(RegState (ArchReg arch) (Value arch ids)) !(Maybe (ArchSegmentOff arch))
- | PLTStub !(MapF (ArchReg arch) (Value arch ids)) !(ArchSegmentOff arch) !VersionedSymbol
- | ParsedJump !(RegState (ArchReg arch) (Value arch ids)) !(ArchSegmentOff arch)
- | ParsedBranch !(RegState (ArchReg arch) (Value arch ids)) !(Value arch ids BoolType) !(ArchSegmentOff arch) !(ArchSegmentOff arch)
- | ParsedLookupTable !(JumpTableLayout arch) !(RegState (ArchReg arch) (Value arch ids)) !(ArchAddrValue arch ids) !(Vector (ArchSegmentOff arch))
- | ParsedReturn !(RegState (ArchReg arch) (Value arch ids))
- | ParsedArchTermStmt !(ArchTermStmt arch (Value arch ids)) !(RegState (ArchReg arch) (Value arch ids)) !(Maybe (ArchSegmentOff arch))
- | ParsedTranslateError !Text
- | ClassifyFailure !(RegState (ArchReg arch) (Value arch ids)) [String]
- parsedTermSucc :: ParsedTermStmt arch ids -> [ArchSegmentOff arch]
- data JumpTableLayout arch
- = AbsoluteJumpTable !(BoundedMemArray arch (BVType (ArchAddrWidth arch)))
- | RelativeJumpTable !(ArchSegmentOff arch) !(BoundedMemArray arch (BVType w)) !(Extension w)
- data Extension (w :: Natural) = Extension {
- _extIsSigned :: !Bool
- _extWidth :: !(AddrWidthRepr w)
- jtlBackingAddr :: JumpTableLayout arch -> ArchSegmentOff arch
- jtlBackingSize :: JumpTableLayout arch -> Word64
- data BoundedMemArray arch (tp :: Type) = BoundedMemArray {
- arBase :: !(ArchSegmentOff arch)
- arStride :: !Word64
- arEltType :: !(MemRepr tp)
- arSlices :: !(Vector [MemChunk (ArchAddrWidth arch)])
- arByteCount :: forall arch (tp :: Type). BoundedMemArray arch tp -> Word64
- isReadOnlyBoundedMemArray :: forall arch (tp :: Type). BoundedMemArray arch tp -> Bool
- data FunctionExploreReason (w :: Nat)
- = PossibleWriteEntry !(MemSegmentOff w)
- | CallTarget !(MemSegmentOff w)
- | InitAddr
- | CodePointerInMem !(MemSegmentOff w)
- | UserRequest
- ppFunReason :: forall (w :: Nat). FunctionExploreReason w -> String
- data BlockExploreReason (w :: Nat)
- = NextIP !(MemSegmentOff w)
- | FunctionEntryPoint
- | SplitAt !(MemSegmentOff w) !(BlockExploreReason w)
- type RegConstraint (r :: Type -> Type) = (OrdF r, HasRepr r TypeRepr, RegisterInfo r, ShowF r)
DiscoveryState
data DiscoveryState arch Source #
Information discovered about the program
type AddrSymMap (w :: Nat) = Map (MemSegmentOff w) ByteString Source #
Maps code addresses to the associated symbol name if any.
exploredFunctions :: DiscoveryState arch -> [Some (DiscoveryFunInfo arch)] Source #
Return list of all functions discovered so far.
ppDiscoveryStateBlocks :: DiscoveryState arch -> Doc ann Source #
Arguments
:: Memory (ArchAddrWidth arch) | State of memory |
-> AddrSymMap (ArchAddrWidth arch) | Map from addresses to their symbol name (if any) |
-> ArchitectureInfo arch | architecture/OS specific information |
-> DiscoveryState arch |
Create empty discovery information.
memory :: DiscoveryState arch -> Memory (ArchAddrWidth arch) Source #
The initial memory when disassembly started.
symbolNames :: DiscoveryState arch -> AddrSymMap (ArchAddrWidth arch) Source #
Map addresses to known symbol names
archInfo :: DiscoveryState arch -> ArchitectureInfo arch Source #
Architecture-specific information needed for discovery.
data GlobalDataInfo w Source #
Information about a region of memory.
Constructors
JumpTable !(Maybe w) | A jump table that appears to end just before the given address. |
ReferencedValue | A value that appears in the program text. |
Instances
(Integral w, Show w) => Show (GlobalDataInfo w) Source # | |
Defined in Data.Macaw.Discovery.State Methods showsPrec :: Int -> GlobalDataInfo w -> ShowS # show :: GlobalDataInfo w -> String # showList :: [GlobalDataInfo w] -> ShowS # |
globalDataMap :: forall arch f. Functor f => (Map (ArchMemAddr arch) (GlobalDataInfo (ArchMemAddr arch)) -> f (Map (ArchMemAddr arch) (GlobalDataInfo (ArchMemAddr arch)))) -> DiscoveryState arch -> f (DiscoveryState arch) Source #
Map each jump table start to the address just after the end.
funInfo :: forall arch f. Functor f => (Map (ArchSegmentOff arch) (Some (DiscoveryFunInfo arch)) -> f (Map (ArchSegmentOff arch) (Some (DiscoveryFunInfo arch)))) -> DiscoveryState arch -> f (DiscoveryState arch) Source #
Get information for specific functions
type UnexploredFunctionMap arch = Map (ArchSegmentOff arch) (FunctionExploreReason (ArchAddrWidth arch)) Source #
unexploredFunctions :: forall arch f. Functor f => (UnexploredFunctionMap arch -> f (UnexploredFunctionMap arch)) -> DiscoveryState arch -> f (DiscoveryState arch) Source #
List of functions to explore next.
data NoReturnFunStatus Source #
Flags whether a function is labeled no return or not.
Constructors
NoReturnFun | Function labeled no return |
MayReturnFun | Function may retun |
Instances
Show NoReturnFunStatus Source # | |
Defined in Data.Macaw.Architecture.Info Methods showsPrec :: Int -> NoReturnFunStatus -> ShowS # show :: NoReturnFunStatus -> String # showList :: [NoReturnFunStatus] -> ShowS # | |
Pretty NoReturnFunStatus Source # | |
Defined in Data.Macaw.Architecture.Info |
trustedFunctionEntryPoints :: forall arch f. Functor f => (Map (ArchSegmentOff arch) NoReturnFunStatus -> f (Map (ArchSegmentOff arch) NoReturnFunStatus)) -> DiscoveryState arch -> f (DiscoveryState arch) Source #
Retrieves functions that are trusted entry points.
exploreFnPred :: forall arch f. Functor f => ((ArchSegmentOff arch -> Bool) -> f (ArchSegmentOff arch -> Bool)) -> DiscoveryState arch -> f (DiscoveryState arch) Source #
DiscoveryFunInfo
data DiscoveryFunInfo arch ids Source #
Information discovered about a particular function
Constructors
DiscoveryFunInfo | |
Fields
|
Instances
ArchConstraints arch => Pretty (DiscoveryFunInfo arch ids) Source # | |
Defined in Data.Macaw.Discovery.State Methods pretty :: DiscoveryFunInfo arch ids -> Doc ann prettyList :: [DiscoveryFunInfo arch ids] -> Doc ann |
discoveredFunName :: MemWidth (ArchAddrWidth arch) => DiscoveryFunInfo arch ids -> ByteString Source #
Returns the "name" associated with a function.
This is either the symbol or the address.
parsedBlocks :: forall arch ids f. Functor f => (Map (ArchSegmentOff arch) (ParsedBlock arch ids) -> f (Map (ArchSegmentOff arch) (ParsedBlock arch ids))) -> DiscoveryFunInfo arch ids -> f (DiscoveryFunInfo arch ids) Source #
Parsed block
data ParsedBlock arch ids Source #
A contiguous region of instructions in memory.
Constructors
ParsedBlock | |
Fields
|
Instances
(ArchConstraints arch, Show (ArchBlockPrecond arch)) => Show (ParsedBlock arch ids) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods showsPrec :: Int -> ParsedBlock arch ids -> ShowS # show :: ParsedBlock arch ids -> String # showList :: [ParsedBlock arch ids] -> ShowS # | |
ArchConstraints arch => Pretty (ParsedBlock arch ids) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents |
Block terminal statements
data ParsedTermStmt arch ids Source #
This term statement is used to describe higher level expressions of how block ending with a a FetchAndExecute statement should be interpreted.
Constructors
ParsedCall !(RegState (ArchReg arch) (Value arch ids)) !(Maybe (ArchSegmentOff arch)) | A call with the current register values and location to return
to or Note that the semantics of this instruction assume that the program has already stored the return address in the appropriate location (which depends on the ABI). For example on X86_64 this is the top of the stack while on ARM this is the link register. |
PLTStub !(MapF (ArchReg arch) (Value arch ids)) !(ArchSegmentOff arch) !VersionedSymbol |
This is a special case of a tail call. It has been added separately because it occurs frequently in dynamically linked code, and we can use this to recognize PLT stubs. The first argument maps registers that were changed to their
value. Other registers have the initial value. This should
typically be empty on The second argument is the address in the .GOT that the target function is stored at. The PLT stub sets the PC to the address stored here. The third and fourth arguments are used to resolve where the function should jump to. |
ParsedJump !(RegState (ArchReg arch) (Value arch ids)) !(ArchSegmentOff arch) | A jump to an explicit address within a function. |
ParsedBranch !(RegState (ArchReg arch) (Value arch ids)) !(Value arch ids BoolType) !(ArchSegmentOff arch) !(ArchSegmentOff arch) |
The value assigned to the IP in |
ParsedLookupTable !(JumpTableLayout arch) !(RegState (ArchReg arch) (Value arch ids)) !(ArchAddrValue arch ids) !(Vector (ArchSegmentOff arch)) | A lookup table that branches to one of a vector of addresses. The registers store the registers, the value contains the index to jump to, and the possible addresses as a table. If the index (when interpreted as an unsigned number) is larger than the number of entries in the vector, then the result is undefined. |
ParsedReturn !(RegState (ArchReg arch) (Value arch ids)) | A return with the given registers. |
ParsedArchTermStmt !(ArchTermStmt arch (Value arch ids)) !(RegState (ArchReg arch) (Value arch ids)) !(Maybe (ArchSegmentOff arch)) | An architecture-specific statement with the registers prior to execution, and the given next control flow address. |
ParsedTranslateError !Text | An error occured in translating the block |
ClassifyFailure !(RegState (ArchReg arch) (Value arch ids)) [String] | The classifier failed to identity the block. Includes registers with list of reasons for each classifer to fail |
Instances
ArchConstraints arch => Show (ParsedTermStmt arch ids) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods showsPrec :: Int -> ParsedTermStmt arch ids -> ShowS # show :: ParsedTermStmt arch ids -> String # showList :: [ParsedTermStmt arch ids] -> ShowS # |
parsedTermSucc :: ParsedTermStmt arch ids -> [ArchSegmentOff arch] Source #
Get all successor blocks for the given list of statements.
JumpTableLayout
data JumpTableLayout arch Source #
This describes the layout of a jump table. Beware: on some architectures, after reading from the jump table, the resulting addresses must be aligned. See the IPAlignment class.
Constructors
AbsoluteJumpTable !(BoundedMemArray arch (BVType (ArchAddrWidth arch))) |
|
RelativeJumpTable !(ArchSegmentOff arch) !(BoundedMemArray arch (BVType w)) !(Extension w) |
The value is computed as
|
Instances
RegisterInfo (ArchReg arch) => Show (JumpTableLayout arch) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods showsPrec :: Int -> JumpTableLayout arch -> ShowS # show :: JumpTableLayout arch -> String # showList :: [JumpTableLayout arch] -> ShowS # |
data Extension (w :: Natural) Source #
Information about a value that is the signed or unsigned extension of another value.
This is used for jump tables, and only supports widths that are in memory
Constructors
Extension | |
Fields
|
jtlBackingAddr :: JumpTableLayout arch -> ArchSegmentOff arch Source #
Return base address of table storing contents of jump table.
jtlBackingSize :: JumpTableLayout arch -> Word64 Source #
Returns the number of bytes in the layout
BoundedMemArray
data BoundedMemArray arch (tp :: Type) Source #
This describes a region of memory dereferenced in some array read.
These regions may be be sparse, given an index i
, the
the address given by arBase
+ arIx
.*
arStride
Constructors
BoundedMemArray | |
Fields
|
Instances
RegisterInfo (ArchReg arch) => Show (BoundedMemArray arch tp) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods showsPrec :: Int -> BoundedMemArray arch tp -> ShowS # show :: BoundedMemArray arch tp -> String # showList :: [BoundedMemArray arch tp] -> ShowS # |
arByteCount :: forall arch (tp :: Type). BoundedMemArray arch tp -> Word64 Source #
Return number of bytes used by this array.
isReadOnlyBoundedMemArray :: forall arch (tp :: Type). BoundedMemArray arch tp -> Bool Source #
Return true if the address stored is readable and not writable.
Reasons for exploring
data FunctionExploreReason (w :: Nat) Source #
This describes why we started exploring a given function.
Constructors
PossibleWriteEntry !(MemSegmentOff w) | Exploring because code at the given block writes it to memory. |
CallTarget !(MemSegmentOff w) | Exploring because address terminates with a call that jumps here. |
InitAddr | Identified as an entry point from initial information |
CodePointerInMem !(MemSegmentOff w) | A code pointer that was stored at the given address. |
UserRequest | The user requested that we analyze this address as a function. |
Instances
MemWidth w => Show (FunctionExploreReason w) Source # | |
Defined in Data.Macaw.Discovery.State Methods showsPrec :: Int -> FunctionExploreReason w -> ShowS # show :: FunctionExploreReason w -> String # showList :: [FunctionExploreReason w] -> ShowS # | |
Eq (FunctionExploreReason w) Source # | |
Defined in Data.Macaw.Discovery.State Methods (==) :: FunctionExploreReason w -> FunctionExploreReason w -> Bool # (/=) :: FunctionExploreReason w -> FunctionExploreReason w -> Bool # |
ppFunReason :: forall (w :: Nat). FunctionExploreReason w -> String Source #
Print exploration reason.
data BlockExploreReason (w :: Nat) Source #
This describes why we are exploring a given block within a function.
Constructors
NextIP !(MemSegmentOff w) | Exploring because the given block jumps here. |
FunctionEntryPoint | Identified as an entry point from initial information |
SplitAt !(MemSegmentOff w) !(BlockExploreReason w) | Added because the address split this block after it had been disassembled. Also includes the reason we thought the block should be there before we split it. |
Instances
MemWidth w => Show (BlockExploreReason w) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods showsPrec :: Int -> BlockExploreReason w -> ShowS # show :: BlockExploreReason w -> String # showList :: [BlockExploreReason w] -> ShowS # | |
Eq (BlockExploreReason w) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents Methods (==) :: BlockExploreReason w -> BlockExploreReason w -> Bool # (/=) :: BlockExploreReason w -> BlockExploreReason w -> Bool # | |
MemWidth w => Pretty (BlockExploreReason w) Source # | |
Defined in Data.Macaw.Discovery.ParsedContents |
DiscoveryState utilities
type RegConstraint (r :: Type -> Type) = (OrdF r, HasRepr r TypeRepr, RegisterInfo r, ShowF r) Source #
Constraint on architecture register values needed by code exploration.