PsSetContext

Sets the register context of the current CPU core of the debug target.

Syntax

PULSE_STATUS PsSetContext(
 [in] PPS_ENGINE pEngine,
 [in] PPS_CTX pContext,
 [in] uint64_t RegMask
);

Parameters

PPS_ENGINE pEngine

An opaque handle to an engine created by the EngCreateEngine function.

PPS_CTX pContext

A pointer to the PS_CTX structure that will be used to set the target registers.

uint64_t RegMask

Specifies the register mask that defines which registers will be modified. Only the contents of the registers specified in the mask will be modified based on the pContext parameter.
Currently defined values:

DBG_CTX_PART_FLAG_RIP
(1ULL << 0)		 RIP register. Current instruction pointer.
DBG_CTX_PART_FLAG_CR3
(1ULL << 1)		 CR3 register. Current page table root pointer.
DBG_CTX_PART_FLAG_RSP
(1ULL << 2)		 RSP register. Current stack pointer.
DBG_CTX_PART_FLAG_RAX
(1ULL << 3)		 RAX general-purpose register.
DBG_CTX_PART_FLAG_RBX
(1ULL << 4)		 RBX general-purpose register.
DBG_CTX_PART_FLAG_RCX
(1ULL << 5)		 RCX general-purpose register.
DBG_CTX_PART_FLAG_RDX
(1ULL << 6)		 RDX general-purpose register.
DBG_CTX_PART_FLAG_RSI
(1ULL << 7)		 RSI general-purpose register.
DBG_CTX_PART_FLAG_RDI
(1ULL << 8)		 RDI general-purpose register.
DBG_CTX_PART_FLAG_RBP
(1ULL << 9)		 RBP general-purpose register.
DBG_CTX_PART_FLAG_RFLAGS
(1ULL << 10)		 RFLAGS register. Current execution flags register.
DBG_CTX_PART_FLAG_R8
(1ULL << 11)		 R8 general-purpose register.
DBG_CTX_PART_FLAG_R9
(1ULL << 12)		 R9 general-purpose register.
DBG_CTX_PART_FLAG_R10
(1ULL << 13)		 R10 general-purpose register.
DBG_CTX_PART_FLAG_R11
(1ULL << 14)		 R11 general-purpose register.
DBG_CTX_PART_FLAG_R12
(1ULL << 15)		 R12 general-purpose register.
DBG_CTX_PART_FLAG_R13
(1ULL << 16)		 R13 general-purpose register.
DBG_CTX_PART_FLAG_R14
(1ULL << 17)		 R14 general-purpose register.
DBG_CTX_PART_FLAG_R15
(1ULL << 18)		 R15 general-purpose register.
DBG_CTX_PART_FLAG_CS
(1ULL << 19)		 CS register. Code segment selector.
DBG_CTX_PART_FLAG_CS_ACCESS
(1ULL << 20)		 CS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_CS_BASE
(1ULL << 21)		 CS base register. Reflects the CS segment base.
DBG_CTX_PART_FLAG_CS_LIMIT
(1ULL << 22)		 CS limit register. Reflects the CS segment limit.
DBG_CTX_PART_FLAG_DS
(1ULL << 23)		 DS register. Data segment selector.
DBG_CTX_PART_FLAG_DS_ACCESS
(1ULL << 24)		 DS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_DS_BASE
(1ULL << 25)		 DS base register. Reflects the DS segment base.
DBG_CTX_PART_FLAG_DS_LIMIT
(1ULL << 26)		 DS limit register. Reflects the DS segment limit.
DBG_CTX_PART_FLAG_SS
(1ULL << 27)		 SS register. Stack segment selector.
DBG_CTX_PART_FLAG_SS_ACCESS
(1ULL << 28)		 SS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_SS_BASE
(1ULL << 29)		 SS base register. Reflects the SS segment base.
DBG_CTX_PART_FLAG_SS_LIMIT
(1ULL << 30)		 SS limit register. Reflects the SS segment limit.
DBG_CTX_PART_FLAG_ES
(1ULL << 31)		 ES register. Extended segment selector.
DBG_CTX_PART_FLAG_ES_ACCESS
(1ULL << 32)		 ES access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_ES_BASE
(1ULL << 33)		 ES base register. Reflects the ES segment base.
DBG_CTX_PART_FLAG_ES_LIMIT
(1ULL << 34)		 ES limit register. Reflects the ES segment limit.
DBG_CTX_PART_FLAG_FS
(1ULL << 35)		 FS register. FS segment selector.
DBG_CTX_PART_FLAG_FS_ACCESS
(1ULL << 36)		 FS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_FS_BASE
(1ULL << 37)		 FS base register. Reflects the FS segment base.
DBG_CTX_PART_FLAG_FS_LIMIT
(1ULL << 38)		 FS limit register. Reflects the FS segment limit.
DBG_CTX_PART_FLAG_GS
(1ULL << 39)		 GS register. GS segment selector.
DBG_CTX_PART_FLAG_GS_ACCESS
(1ULL << 40)		 GS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_GS_BASE
(1ULL << 41)		 GS base register. Reflects the GS segment base.
DBG_CTX_PART_FLAG_GS_LIMIT
(1ULL << 42)		 GS limit register. Reflects the GS segment limit.
DBG_CTX_PART_FLAG_CR0
(1ULL << 43)		 CR0 register.
DBG_CTX_PART_FLAG_CR2
(1ULL << 44)		 CR2 register. Last page fault linear address.
DBG_CTX_PART_FLAG_CR4
(1ULL << 45)		 CR4 register.
DBG_CTX_PART_FLAG_CR8
(1ULL << 46)		 CR8 register. TPR register mirror.
DBG_CTX_PART_FLAG_GDT_BASE
(1ULL << 47)		 GDT base register. Reflects the Global Descriptor Table base.
DBG_CTX_PART_FLAG_GDT_LIMIT
(1ULL << 48)		 GDT limit register. Reflects the Global Descriptor Table limit.
DBG_CTX_PART_FLAG_IDT_BASE
(1ULL << 49)		 IDT base register. Reflects the Interrupt Descriptor Table base.
DBG_CTX_PART_FLAG_IDT_LIMIT
(1ULL << 50)		 IDT limit register. Reflects the Interrupt Descriptor Table limit.
DBG_CTX_PART_FLAG_LDT
(1ULL << 51)		 LDT register. Local Descriptor Table selector.
DBG_CTX_PART_FLAG_LDT_ACCESS
(1ULL << 52)		 LDT access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_LDT_BASE
(1ULL << 53)		 LDT base register. Reflects the LDT segment base.
DBG_CTX_PART_FLAG_LDT_LIMIT
(1ULL << 54)		 LDT limit register. Reflects the LDT segment limit.
DBG_CTX_PART_FLAG_TSS
(1ULL << 55)		 TSS (or TR) register. Task State Selector or Task Register selector.
DBG_CTX_PART_FLAG_TSS_ACCESS
(1ULL << 56)		 TSS access register. Reflects the "access" part of the segment descriptor.
DBG_CTX_PART_FLAG_TSS_BASE
(1ULL << 57)		 TSS base register. Reflects the TSS segment base.
DBG_CTX_PART_FLAG_TSS_LIMIT
(1ULL << 58)		 TSS limit register. Reflects the TSS segment limit.
DBG_CTX_PART_FLAG_DR0
(1ULL << 59)		 DR0 debug register.
DBG_CTX_PART_FLAG_DR1
(1ULL << 60)		 DR1 debug register.
DBG_CTX_PART_FLAG_DR2
(1ULL << 61)		 DR2 debug register.
DBG_CTX_PART_FLAG_DR3
(1ULL << 62)		 DR3 debug register.
DBG_CTX_PART_FLAG_DR6
(1ULL << 63)		 DR6 debug register.
DBG_CTX_PART_FLAG_DR7
(1ULL << 63)		 DR7 debug register.

Return value

If the function succeeds, the return value is PULSE_STATUS_SUCCESS.

If it fails, it returns one of the PULSE_STATUS values. Possible return codes include, but are not limited to, the following:

PULSE_STATUS_INSUFFICIENT_RESOURCES
0xC0000002		 One of the memory allocations failed during initialization.
PULSE_STATUS_READ_FAILED
0xC0000003		 Transport communication failed during a read operation.
PULSE_STATUS_WRITE_FAILED
0xC0000004		 Transport communication failed during a write operation.
PULSE_STATUS_TIMEOUT
0xC0000007		 Might happen if
  • Transport I/O timed out.
  • No response was received from the debuggee within the request timeout period.
PULSE_STATUS_INVALID_PARAMETER
0xC0000010		 Might happen if
  • The pEngine parameter is NULL.
  • The pContext parameter is NULL.
PULSE_STATUS_INVALID_PACKET
0xC0000031		 An invalid or unexpected packet was received in response.
PULSE_STATUS_DEVICE_CONNECTION_LOST
0xC0000308		 The connection to the transport was lost. Try restarting the engine or the transport.

Remarks

The RegMask parameter allows partial context state modifications.