/* scan.h - typed value scanner, pointer scanner, and gva<->signature bridges.
 *
 * Layered above the pure matcher (sigscan.h) and the gva core (include.h): this
 * is the gva-bound scanning surface. The value scanner narrows a candidate set
 * across successive snapshots; the pointer scanner discovers module-anchored
 * pointer chains; the gva_sig_* bridges build mem_view_t windows out of guest
 * memory and feed them to the signature matcher.
 */
#ifndef VMIE_SCAN_H
#define VMIE_SCAN_H
#include <stdint.h>
#include <stddef.h>
#include "include.h"     /* gva_ctx, process (vregion - internal) */
#include "sigscan.h"     /* mem_view_t, sig_pattern_t */

/* typed value scanner. ENUMERATOR ORDER IS LOAD-BEARING: scan.c indexes the
 * table g_tsz[] = {1,2,4,8, 1,2,4,8, 4,8, 2} by these values - do not reorder
 * without updating scan.c. */
typedef enum {
    SCAN_I8, SCAN_I16, SCAN_I32, SCAN_I64,   /* signed   */
    SCAN_U8, SCAN_U16, SCAN_U32, SCAN_U64,   /* unsigned */
    SCAN_F32, SCAN_F64, SCAN_F16             /* float    */
} scan_type;

typedef enum {
    SCAN_EQ, SCAN_NEQ, SCAN_GT, SCAN_LT,             /* require a value argument        */
    SCAN_INC, SCAN_DEC, SCAN_CHANGED, SCAN_UNCHANGED /* relative to the previous snapshot */
} scan_op;

typedef struct scan scan;                       /* opaque session */
typedef struct { uint64_t addr; uint64_t value; } scan_hit;

#define SCAN_PTR_MAXDEPTH 8                      /* DFS depth and size of off[] */
typedef struct {
    uint64_t base;                              /* module-anchored base address */
    int      depth;                             /* number of offsets in off[]   */
    int32_t  off[SCAN_PTR_MAXDEPTH];            /* dereference chain            */
} scan_ptr_path;

scan*   scan_new(gva_ctx* ctx, const process* pr, scan_type t, const void* value,
                 int be, int aligned, uint64_t lo, uint64_t hi);
scan*   scan_new_cr3(gva_ctx* ctx, uintptr_t cr3, scan_type t, const void* value,
                     int be, int aligned, uint64_t lo, uint64_t hi);
int64_t scan_next(scan* s, scan_op op, const void* value);
int64_t scan_count(scan* s);
int     scan_results(scan* s, uint64_t offset, int max, scan_hit* out);
void    scan_free(scan* s);

int     scan_pointer(gva_ctx* ctx, const process* pr, uint64_t target,
                     int max_depth, uint32_t max_off, scan_ptr_path* out, int max);

/* gva bridges to the signature matcher: build mem_view from guest memory and feed sigscan.h */
int gva_sig_scan (gva_ctx* ctx, uintptr_t cr3, uint64_t lo, uint64_t hi,
                  uint32_t prot_any, const sig_pattern_t* p, uint64_t* out, int max);
int gva_sig_first(gva_ctx* ctx, uintptr_t cr3, uint64_t lo, uint64_t hi,
                  uint32_t prot_any, const sig_pattern_t* p, uint64_t* va);
int gva_sig_rip  (gva_ctx* ctx, uintptr_t cr3, uint64_t hit_va,
                  size_t disp_off, size_t instr_len, uint64_t* target);
int gva_pe_section(gva_ctx* ctx, uintptr_t cr3, uint64_t module_base,
                   const char* name, uint8_t* buf, size_t bufcap, mem_view_t* out);
int gva_sig_phys (gva_ctx* ctx, const sig_pattern_t* p, uint64_t* out, int max);

#endif /* VMIE_SCAN_H */