Kernel Debugger IOCTLs (Compact 2013)
10/16/2014
The kernel debugger supports both hardware and software breakpoints. The software breakpoint features require no additional OEM action or code. The hardware breakpoint features require the OEM to implement kernel debugger IOCTLs. The OEM may omit a group of IOCTLs where support is not required, and omit individual IOCTLs, as indicated by the "Status" columns in the tables in this topic.
Software Breakpoints
Software breakpoints operate with no additional OEM action or code. However, they require substantially more overhead than hardware breakpoints. Software breakpoints do not require IOCTL implementation because the kernel debugger does not call IOCTLs to support software breakpoints, which it manages independently of the debug target.
Hardware Breakpoints: OEM Implementation
Hardware breakpoints require the OEM to implement IOCTLs specific to their platform as described in this section. The OEM must implement the control IOCTLs to support any Platform Builder hardware kernel debugger functions, and can implement the code and data IOCTLs or data IOCTLs or both as they require. Moreover, the OEM must implement these IOCTLs because the implementation is specific to each hardware platform.
Hardware breakpoints perform significantly faster than software breakpoints, and may be required for debugging time-sensitive logic.
Breakpoint Function Groups
The kernel debugger IOCTLs are divided into three breakpoint function groups: control, code, and data.
Kernel Debugger Breakpoints: Control IOCTLs
The following table shows the IOCTLs that control kernel debugger breakpoints. These IOCTLs are prerequisites to the code breakpoint IOCTLs and data breakpoint IOCTLs.
IOCTL |
Status |
Description |
|---|---|---|
Optional |
Notifies the BSP that the kernel debugger is about to wake the device from a previous KD_IOCTL_KERNEL_HALT. |
|
Required |
Indicates end of error report dump generation. |
|
Required |
Indicates start of error report dump generation. |
|
Required |
Initializes the kernel debugger. |
|
Optional |
Notifies the BSP that the kernel debugger is about to halt the device. |
|
Required |
Indicates that just-in-time (JIT) debugging has started. |
|
Required |
Checks accessibility status of a memory location. |
|
Required |
Resets the device. |
Kernel Debugger Breakpoints: Code Breakpoint IOCTLs
The following table shows the IOCTLs that support the kernel debugger code breakpoints.
IOCTL |
Status |
Description |
|---|---|---|
Required |
Clears a code breakpoint. |
|
KD_IOCTL_ENUM_CBP |
Reserved. Do not implement. |
Enumerates the code breakpoints that are set. |
Required |
Queries the number of hardware code breakpoints that are available. |
|
Required |
Sets a code breakpoint. |
Kernel Debugger Breakpoints: Data Breakpoint IOCTLs
The following table shows the IOCTLs that support the kernel debugger data breakpoints.
IOCTL |
Status |
Description |
|---|---|---|
Required |
Clears a data breakpoint. |
|
KD_IOCTL_ENUM_DBP |
Reserved. Do not implement. |
Enumerates the data breakpoints that are set. |
Required |
Queries the number of hardware data breakpoints that are available. |
|
Required |
Sets a data breakpoint. |
|
Required for x86 hardware. Optional otherwise. |
Maps an exception code to a different code. |
Kernel Debugger Breakpoints: Data Structures
The following table shows the structures that support the kernel debugger data breakpoints.
Structure |
Description |
|---|---|
Contains breakpoint information, used by the OEMKDIoctl function. |
|
Contains exception code information, used by KD_IOCTL_MAP_EXCEPTION. |