This is the same feature as the one that already exists in the
NTOS:KD!kdmain.c module used by the in-kernel KDBG debugger
(GCC builds), first introduced in commit 4ce30245de (r54473),
and documented at:
https://reactos.org/wiki/Debugging#Changing_the_serial_port_address
This feature is useful if one uses a PCI, PCIe, PCMCIA, or ExpressCard
serial card on real hardware (these cards are used e.g. with laptops
without a built-in serial port), or with AMT serial over LAN.
After determining the serial port I/O address (say, 0xCC00), specify
the debug port as follows:
/DEBUGPORT=COM:0xCC00
instead of the usual syntax: /DEBUGPORT=COMn (n an integer).
The same syntax can be used for debugging FreeLoader as well: in the
FREELDR.INI file, add a "Debug" line in the "FREELOADER" section,
as follows:
```
[FREELOADER]
Debug=/DEBUG /DEBUGPORT=COM:0xCC00 /BAUDRATE=115200
```
----
NOTE for KDCOM/KDGDB:
Since `strtoul()` is used, but isn't exported by ntoskrnl, link against
the "strtol" static library that has been introduced in commit d317d4fbcc
(r71481).
Don't loop past the end of the command-line buffer, if the command-line
terminates with a lone "DEBUGPORT" without any extra parameter following.
For example: "some things DEBUGPORT "
Support for the BAUDRATE option was erroneously removed in commit 95faf65ebf.
As a result, the in-kernel KDBG debugger was always running with the
default debug port baud rate (115200 Bd), even if the user tried to
override it with the BAUDRATE option for supporting terminals that use
a different baud rate.
- Don't hardcode constant string lengths.
- Use `_strnicmp()` -- Ideally we shouldn't have to unconditionally upcase
the global kernel command-line string to perform substrings comparisons.
- Cast `atol()` returned value to `ULONG`.
- Use DEFAULT_DEBUG_BAUD_RATE for the debug serial port.
- Use a less dramatic "Serial port not available" (without '!')
instead of "Serial port not found!" message, in case ReactOS
BSODs without a debugger attached to a serial port.
Sometimes people mistake this informational line as one of the
reasons why ReactOS BSODed or whatnot...
- Replace "Serial port found" by "Using COM..." message.
CORE-17977
- Fix a bug when subsequent port detection attempts fail because of
broken FIFO management. If FIFO logic is enabled the hardware will
not decode the legacy 0x30 and 0x32 I/O ports.
Therefore care should be taken when accessing these ports.
- Fix hang on boot when a serial device was not connected to the COM1 port.
Unlike 16550, a call to `CpDoesPortExist()` for the 8251 will succeed
even when if the user has not plug the serial port into PC-98 machine.
(I do not know how to put the 8251 into loopback mode.)
Fix this by checking for CTS prior to the LSR loop.
- Fix hang on boot when the chosen baud rate becomes too large due to
`DEFAULT_DEBUG_BAUD_RATE` being set to 115200.
- Some NP21/W workarounds were being incorrectly applied,
fix them and consolidate them into one check.
- Reuse exsisting code from the NS16550 driver to avoid code duplication.
- Rename HW definitions for better naming.
Co-authored-by: Hermès Bélusca-Maïto <[email protected]>
CORE-20107
Improve the minimal handling done in the fall-back KdSend/ReceivePacket()
routines when they are invoked by KD64 (in Release build).
Part of my `kdbg_tests_kdio_split` branch for splitting kd/kdio.c
into a separate KD dll.
KdSendPacket:
- Silently ignore PACKET_TYPE_KD_STATE_CHANGE32/64 DbgKdLoadSymbolsStateChange notification.
- Partially manage and log the unhandled PACKET_TYPE_KD_STATE_CHANGE DbgKdExceptionStateChange notification.
- Log other unhandled PACKET_TYPE_KD_STATE_CHANGE32/64 and PACKET_TYPE_KD_STATE_MANIPULATE notifications.
When KdSendPacket receives the DbgKdExceptionStateChange notification,
it cannot handle it (no debugger is there!). However, we need to claim
the debugger to be present, so that its KD64 caller: KdpSendWaitContinue(),
can call back KdReceivePacket(PACKET_TYPE_KD_STATE_MANIPULATE), which,
in turn, informs KD that the exception cannot be handled, by returning
a failure code in the ManipulateState's ContinueStatus.
During bugchecks, this allows KiBugCheckDebugBreak() to not loop infinitely,
but instead fall back into calling HalHaltSystem() to halt the computer.
When KDBG isn't included in the kernel (Release build), the fall-back
KdSend/ReceivePacket() routines are invoked by KD64. A minimal handling
of the basic packets needs to be done:
PACKET_TYPE_KD_STATE_CHANGE32/64 for KdSendPacket(),
and PACKET_TYPE_KD_POLL_BREAKIN, PACKET_TYPE_KD_STATE_MANIPULATE
for KdReceivePacket().
Addendum to commit 2046a17ef4
CORE-20107
Addendum to commit 271b985
CORE-20107
[NTOS:KD] Comment defines related to KdMax. They are not used,
but keep them for documentation purposes.
Addendum to e160c0f (r14799) and 6d53c91 (r27419).
Add redirections for KdSave/KdRestore and KdD0Transition/KdD3Transition.
Both KDBG and KD(TERM) need those since they will become external
transport DLLs later.
Split KdSendPacket and KdReceivePacket into those that manipulate the
KDBG state proper (reside in kdbg/kdbg.c), and those that deal only with
debug input/output that will reside in a KDTERM "KD Terminal Driver" DLL.
Based on some previous preparatory work by Hervé Poussineau in PR #4600.
(Equivalents of commits 5162bf106 and partly e9bcf7275.)
... since the original ones are internal to the kernel and won't be
available once KDBG is moved out of it.
Use these functions in the pager/prompt support.
The built string can be:
°°Kernel Debugger: Serial port found: COM1 (Port 0x000003F8) BaudRate 115200°°°°
(with ° representing the \r and \n in the message)
and you can verify that this is more than 80 characters in total.
This one was more subtle because the prompt (KdIoReadLine) functionality
makes a call-back to KDBG own command history getter function KdbGetHistoryEntry.
It is planned for this to become a registered optional callback pointer.
This is done in preparation for moving all this functionality in a
separate KDTERM "KD Terminal Driver" DLL.
Additionally:
- Flush the terminal input before sending ANSI escape sequences.
- In KDBG pager, always use the correct reading-key function (the
same used also for reading keys for a line of user input), and not
the simplistic two-call KdbpGetCharSerial + KdbpTryGetCharSerial
that would split the \r \n across calls.
- Call KdbpGetCommandLineSettings() in KdbInitialize() at BootPhase 0,
which is indirectly called by KdDebuggerInitialize0(). And fix its
command-line parsing too.
Rename KdbpReadCommand as KdIoReadLine. Extract the last-command
repetition functionality out of KdIoReadLine and put it where it
belongs: only in the KDBG command main loop KdbpCliMainLoop.
Use this function instead of KdpDprintf(), otherwise, we send them to
**ALL** the display providers, including for example dmesg. Replaying
the listing with dmesg would then cause the terminal to misbehave later.
For example, it would send the answer of a "Query Device Attributes"
command, as the response to a query for terminal size...
Addendum to commit 84e32e4e.
Explain more accurately what's going on regarding the returned string
and the inaccurate claims made in the official DbgPrompt documentation
in MSDN. (Has been verified by looking through the traffic in WinDbg
debugging of Windows and ReactOS.)
Addendum to commit de892d5b.
The boot options get stripped of their optional command switch '/'
(and replaced by whitspace separation) by the NT loader. Also, forbid
the presence of space between the optional '=' character following
(NO)LOADSYMBOLS.
In addition, fix the default initialization of LoadSymbols in KdbSymInit():
we cannot rely on MmNumberOfPhysicalPages in BootPhase 0 since at this point,
the Memory Manager hasn't been initialized and this variable is not yet set.
(We are called by KdInitSystem(0) -> KdDebuggerInitialize0 at kernel init.)
It gets initialized later on between BootPhase 0 and 1.
Also display a nice KDBG signon showing the status of symbols loading.
CORE-17470
+ KdpDebugLogInit: Add resources cleanup in failure code paths.
Fix, in an NT-compatible manner, how (and when) the KD/KDBG BootPhase >=2
initialization steps are performed.
These are necessary for any functionality KDBG needs, that would depend
on the NT I/O Manager and the storage and filesystem stacks to be running.
This includes, creating the debug log file, and for KDBG, loading its
KDBinit initialization file.
As a result, file debug logging is fixed.
The old ReactOS-specific (NT-incompatible) callback we did in the middle
of IoInitSystem() is removed, in favor of a runtime mechanism that should
work on Windows as well.
The idea for this new mechanism is loosely inspired by the TDL4 rootkit,
see http://blog.w4kfu.com/public/tdl4_article/draft_tdl4article.html
but contrary to it, a specific hook is used instead, as well as the
technique of driver reinitialization:
https://web.archive.org/web/20211021050515/https://driverentry.com.br/en/blog/?p=261
Its rationale is as follows:
We want to be able to perform I/O-related initialization (starting a
logger thread for file log debugging, loading KDBinit file for KDBG,
etc.). A good place for this would be as early as possible, once the
I/O Manager has started the storage and the boot filesystem drivers.
Here is an overview of the initialization steps of the NT Kernel and
Executive:
----
KiSystemStartup(KeLoaderBlock)
if (Cpu == 0) KdInitSystem(0, KeLoaderBlock);
KiSwitchToBootStack() -> KiSystemStartupBootStack()
-> KiInitializeKernel() -> ExpInitializeExecutive(Cpu, KeLoaderBlock)
(NOTE: Any unexpected debugger break will call KdInitSystem(0, NULL); )
KdInitSystem(0, LoaderBlock) -> KdDebuggerInitialize0(LoaderBlock);
ExpInitializeExecutive(Cpu == 0): ExpInitializationPhase = 0;
HalInitSystem(0, KeLoaderBlock); <-- Sets HalInitPnpDriver callback.
...
PsInitSystem(LoaderBlock)
PsCreateSystemThread(Phase1Initialization)
Phase1Initialization(Discard): ExpInitializationPhase = 1;
HalInitSystem(1, KeLoaderBlock);
...
Early initialization of Ob, Ex, Ke.
KdInitSystem(1, KeLoaderBlock);
...
KdDebuggerInitialize1(LoaderBlock);
...
IoInitSystem(LoaderBlock);
...
----
As we can see, KdDebuggerInitialize1() is the last KD initialization
routine the kernel calls, and is called *before* the I/O Manager starts.
Thus, direct Nt/ZwCreateFile ... calls done there would fail. Also,
we want to do the I/O initialization as soon as possible. There does
not seem to be any exported way to be notified about the I/O manager
initialization steps... that is, unless we somehow become a driver and
insert ourselves in the flow!
Since we are not a regular driver, we need to invoke IoCreateDriver()
to create one. However, remember that we are currently running *before*
IoInitSystem(), the I/O subsystem is not initialized yet. Due to this,
calling IoCreateDriver(), much like any other IO functions, would lead
to a crash, because it calls
ObCreateObject(..., IoDriverObjectType, ...), and IoDriverObjectType
is non-initialized yet (it's NULL).
The chosen solution is to hook a "known" exported callback: namely, the
HalInitPnpDriver() callback (it initializes the "HAL Root Bus Driver").
It is set very early on by the HAL via the HalInitSystem(0, ...) call,
and is called early on by IoInitSystem() before any driver is loaded,
but after the I/O Manager has been minimally set up so that new drivers
can be created.
When the hook: KdpInitDriver() is called, we create our driver with
IoCreateDriver(), specifying its entrypoint KdpDriverEntry(), then
restore and call the original HalInitPnpDriver() callback.
Another possible unexplored alternative, could be to insert ourselves
in the KeLoaderBlock->LoadOrderListHead boot modules list, or in the
KeLoaderBlock->BootDriverListHead boot-driver list. (Note that while
we may be able to do this, because boot-drivers are resident in memory,
much like we are, we cannot insert ourselves in the system-driver list
however, since those drivers are expected to come from PE image files.)
Once the KdpDriverEntry() driver entrypoint is called, we register
KdpDriverReinit() for re-initialization with the I/O Manager, in order
to provide more initialization points. KdpDriverReinit() calls the KD
providers at BootPhase >= 2, and schedules further reinitializations
(at most 3 more) if any of the providers request so.
- KdbSymInit() in kdb_symbols.c only initializes symbols implementation
support.
- The rest of KdbInitialize gets moved into kdb_cli.c and initializes
the KDBG debugger itself.
- Move KdbDebugPrint to kdb_cli.c as well.
- Use SAL2 annotations.
- KdSendPacket(): Validate DEBUG_IO API call.
- KdReceivePacket(): Take the LengthOfStringRead into account; use
KdbpReadCommand() to read the input, so that correct line edition
is available (backspace, etc.)
If you ask why there are two sets of functions that do the same, it's
because this file (and the kdmain.c) will very soon some day be moved to
a transport dll, outside the kernel, and it will need these functions.
- Remove KdbInit() macro and directly use KdbpCliInit() (since the place
where it was used was already within an #ifdef KDBG block).
- Declare KdpKdbgInit() only when KDBG is defined, move its definition
into kdio.c and remove the legacy wrappers/kdbg.c file.
And in KdbInitialize(), set KdpInitRoutine directly to the former,
instead of using the KdpKdbgInit indirection.
- Don't reset KdComPortInUse in KdpDebugLogInit().
- Minor refactorings: KdpSerialDebugPrint -> KdpSerialPrint and make it
static; argument name "Message" -> "String", "StringLength" -> "Length".
KD64: Raise to HIGH_LEVEL when entering trap
KDBG: lower to DISPATCH_LEVEL when applying IRQL hack & use a worker thread to load symbols
KD&KDBG: Actually unload symbols when required
Phase 2 and 3 were not done anymore since 777a2d94da.
Fix that, by merging phases 1 and 2, and by calling phase 3 later
for log file debugging, when ExpInitializationPhase = 3
CORE-17470
