Page MenuHomeFreeBSD
Files F161545921

D54895.diff
No OneTemporary
Actions

D54895.diff
View Options

diff --git a/usr.sbin/Makefile b/usr.sbin/Makefile
--- a/usr.sbin/Makefile
+++ b/usr.sbin/Makefile
@@ -164,6 +164,7 @@
SUBDIR.${MK_LEGACY_CONSOLE}+= kbdmap
SUBDIR.${MK_LEGACY_CONSOLE}+= moused
SUBDIR.${MK_LEGACY_CONSOLE}+= vidcontrol
+SUBDIR.${MK_LLDB}+= kdb
SUBDIR.${MK_PPP}+= pppctl
SUBDIR.${MK_NS_CACHING}+= nscd
SUBDIR.${MK_LPR}+= lpr
diff --git a/usr.sbin/kdb/Makefile b/usr.sbin/kdb/Makefile
new file mode 100644
--- /dev/null
+++ b/usr.sbin/kdb/Makefile
@@ -0,0 +1,4 @@
+SCRIPTS= kdb.sh
+MAN= kdb.1
+
+.include <bsd.prog.mk>
diff --git a/usr.sbin/kdb/kdb.1 b/usr.sbin/kdb/kdb.1
new file mode 100644
--- /dev/null
+++ b/usr.sbin/kdb/kdb.1
@@ -0,0 +1,168 @@
+.\" Copyright (c) 2004 Marcel Moolenaar
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd January 24, 2026
+.Dt KDB 1
+.Os
+.Sh NAME
+.Nm kdb
+.Nd kernel debugger
+.Sh SYNOPSIS
+.Nm
+.Op Fl b Ar rate
+.Op Fl v
+.Op Fl d Ar crashdir
+.Op Fl c Ar core | Fl n Ar dumpnr | Fl r Ar device
+.Op Fl -lldb-args Ar args
+.Op Ar kernel Op Ar core
+.Sh DESCRIPTION
+The
+.Nm
+utility is a debugger based on
+.Xr lldb 1
+that allows debugging of kernel core files.
+.Pp
+The options are as follows:
+.Bl -tag -width "-d crashdir"
+.It Fl b Ar rate
+Set the baudrate to
+.Ar rate .
+.It Fl v
+Increase verbosity level.
+Can be specified multiple times for greater detail.
+.Pp
+Level 1: Print core file, device, or image file path.
+.Pp
+Level 2: Print level 1 information plus crash directory.
+.Pp
+Level 3: Print level 2 information plus lldb commands.
+.It Fl d Ar crashdir
+Use
+.Ar crashdir
+instead of the default,
+.Pa /var/crash
+to locate kernel core dump files in.
+The name
+.Pa vmcore.
+plus the dump number will be appended to determine the actual dump file name.
+.It Fl c Ar core
+Explicitly use
+.Ar core
+as the core dump file.
+.It Fl n Ar dumpnr
+Use the kernel core dump file numbered
+.Ar dumpnr
+for debugging.
+.It Fl r Ar device
+Use
+.Ar device
+to connect
+.Nm
+to for a remote debugging session.
+.It Fl -lldb-args Ar args
+Pass additional arguments directly to
+.Xr lldb 1 .
+The arguments should be enclosed in quotes if they contain spaces or multiple options.
+Note that passing arguments conflicting with kgdb's arguments such as
+.Fl c
+will cause error and should be avoided.
+.El
+.Pp
+The
+.Fl c , n ,
+and
+.Fl r
+options are mutually exclusive.
+.Pp
+Optionally, the name of the kernel symbol file and the name of the core dump
+file can be supplied on the command-line as positional arguments.
+If no kernel symbol file name has been given, the symbol file of the currently
+running kernel will be used.
+If no core dump file has been specified through either of the options or the
+last command-line argument,
+.Pa /dev/mem
+will be opened to allow debugging the currently running kernel.
+.Sh ENVIRONMENT
+.Bl -tag -width "KDB_CRASH_DIR"
+.It Ev KDB_CRASH_DIR
+If set, this directory will be used as the default crash directory
+instead of
+.Pa /var/crash .
+.El
+.Sh FILES
+.Bl -tag -width "/var/crash"
+.It Pa /dev/mem
+Default memory image to open if no core dump file has been specified.
+.It Pa /var/crash
+Default directory to locate kernel core dump files.
+.El
+.Sh EXAMPLES
+Debug the most recent kernel crash:
+.Pp
+.Dl "kdb -n 0"
+.Pp
+Debug a specific core file with a specific kernel:
+.Pp
+.Dl "kdb /boot/kernel/kernel /var/crash/vmcore.0"
+.Pp
+Run a batch script on a core dump:
+.Pp
+.Dl "kdb --batch -o \*qbt\*q -o \*qquit\*q -c vmcore.0"
+.Pp
+Connect to a remote kernel debugging session:
+.Pp
+.Dl "kdb -r cuaU0 /boot/kernel/kernel"
+.Pp
+Use the REPL mode for interactive Python scripting:
+.Pp
+.Dl "kdb --lldb-args \*q--repl\*q -n 0"
+.Pp
+Or simply:
+.Pp
+.Dl "kdb --repl -n 0"
+.Pp
+Pass multiple lldb options:
+.Pp
+.Dl "kdb --lldb-args \*q-O \*q\*qbt\*q\*q -O \*q\*qquit\*q\*q\*q -c vmcore.0"
+.Sh SEE ALSO
+.Xr lldb 1
+.Sh HISTORY
+The
+.Nm
+utility first appeared in its current form in
+.Fx 16.0 .
+It replaced the earlier
+.Xr kgdb 1
+utility which was based on
+.Xr gdb 1 .
+.Sh AUTHORS
+.An -nosplit
+The original
+.Xr kgdb 1
+was written by
+.An Marcel Moolenaar Aq Mt marcel@FreeBSD.org .
+It was later rewritten in shell script for
+.Xr lldb 1
+by
+.An Minsoo Choo Aq Mt minsoochoo0122@proton.me .
diff --git a/usr.sbin/kdb/kdb.sh b/usr.sbin/kdb/kdb.sh
new file mode 100755
--- /dev/null
+++ b/usr.sbin/kdb/kdb.sh
@@ -0,0 +1,354 @@
+#!/bin/sh
+#
+# Copyright (c) 2004 Marcel Moolenaar
+# Copyright (c) 2026 The FreeBSD Foundation
+#
+# This software was developed by Minsoo Choo under sponsorship from the FreeBSD
+# Foundation.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+# IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+# OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+# NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+# THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+usage()
+{
+ echo "usage: kdb [-v] [-b rate] [-d crashdir]" \
+ "[-c core | -n dumpnr | -r device]" >&2
+ echo " [--lldb-args args] [kernel [core]]" >&2
+ exit 1
+}
+
+warnx()
+{
+ printf "%s: %s\n" "${0##*/}" "$*" >&2
+}
+
+err()
+{
+ local exitcode="$1"
+ shift
+ warnx "$*"
+ exit "$exitcode"
+}
+
+errx()
+{
+ local exitcode="$1"
+ shift
+ warnx "$*"
+ exit "$exitcode"
+}
+
+kernel_from_dumpnr()
+{
+ local nr="$1"
+ local path line dir
+
+ # If there's a kernel image right here in the crash directory, then
+ # use it. The kernel image is either called kernel.<nr> or is in a
+ # subdirectory kernel.<nr> and called kernel. The latter allows us
+ # to collect the modules in the same place.
+ path="${CRASHDIR}/kernel.${nr}"
+ if [ -f "$path" ]; then
+ KERNEL="$path"
+ return
+ fi
+ if [ -d "$path" ]; then
+ path="${CRASHDIR}/kernel.${nr}/kernel"
+ if [ -f "$path" ]; then
+ KERNEL="$path"
+ return
+ fi
+ fi
+
+ # No kernel image here. Parse the dump header. The kernel object
+ # directory can be found there and we probably have the kernel
+ # image still in it. The object directory may also have a kernel
+ # with debugging info (called either kernel.full or kernel.debug).
+ # If we have a debug kernel, use it.
+ path="${CRASHDIR}/info.${nr}"
+ if [ ! -f "$path" ]; then
+ warnx "$path"
+ return
+ fi
+
+ while IFS= read -r line; do
+ # Check if line starts with " " (4 spaces)
+ case "$line" in
+ " "*)
+ # Extract directory after colon, or use everything
+ # after 4 spaces
+ if echo "$line" | grep -q ':'; then
+ dir=$(echo "$line" | sed 's/^.*://')
+ else
+ dir=$(echo "$line" | sed 's/^ //')
+ fi
+
+ # Check for kernel.full first as if it exists
+ # kernel.debug will also exist, but will only
+ # contain debug symbols and not be recognized
+ # as a valid kernel by the osabi sniffer.
+ path="${dir}/kernel.full"
+ if [ -f "$path" ]; then
+ KERNEL="$path"
+ return
+ fi
+ path="${dir}/kernel.debug"
+ if [ -f "$path" ]; then
+ KERNEL="$path"
+ return
+ fi
+ path="${dir}/kernel"
+ if [ -f "$path" ]; then
+ KERNEL="$path"
+ return
+ fi
+ return
+ ;;
+ esac
+ done < "$path"
+}
+
+# Remote targets can support any number of syntaxes and we want to
+# support them all with one addition: we support specifying a device
+# node for a serial device without the "/dev/" prefix.
+#
+# What we do is to check the existing remote target first. If that
+# fails, we try it with "/dev/" prepended. If that succeeds we use
+# the resulting path, otherwise we use the original target. If
+# either the check succeeds make sure the file is either a character
+# device or a FIFO.
+verify_remote()
+{
+ local path
+
+ if [ ! -e "$DEVICE" ]; then
+ path="/dev/${DEVICE}"
+ if [ -e "$path" ]; then
+ DEVICE="$path"
+ else
+ return
+ fi
+ fi
+
+ if [ ! -c "$DEVICE" ] && [ ! -p "$DEVICE" ]; then
+ errx 1 \
+ "${DEVICE}: not a special file, FIFO or socket."
+ fi
+}
+
+# Main script starts here
+BAUDRATE=
+CRASHDIR=/var/crash
+DEVICE=
+DUMPNR=
+KERNEL=
+LLDBARGS=
+LLDB_EXTRA_ARGS=
+VERBOSE=
+VMCORE=
+
+# Check environment variable
+if [ -n "$KDB_CRASH_DIR" ]; then
+ CRASHDIR="$KDB_CRASH_DIR"
+fi
+
+# Parse command line options
+while getopts "b:c:d:n:qr:v-:" opt; do
+ case "$opt" in
+ b)
+ # Validate baud rate is a number
+ case "$OPTARG" in
+ ''|*[!0-9]*)
+ warnx "warning: could not set baud rate to \`${OPTARG}'."
+ ;;
+ *)
+ BAUDRATE="$OPTARG"
+ ;;
+ esac
+ ;;
+ c)
+ # use given core file.
+ if [ -n "$VMCORE" ]; then
+ warnx "option -c: can only be specified once"
+ usage
+ fi
+ VMCORE="$OPTARG"
+ ;;
+ d)
+ # lookup dumps in given directory.
+ CRASHDIR="$OPTARG"
+ ;;
+ n)
+ # use dump with given number.
+ DUMPNR="$OPTARG"
+ ;;
+ r)
+ # use given device for remote session.
+ if [ -n "$DEVICE" ]; then
+ warnx "option -r: can only be specified once"
+ usage
+ fi
+ DEVICE="$OPTARG"
+ ;;
+ v)
+ # increase verbosity.
+ VERBOSE="${VERBOSE}v"
+ ;;
+ -)
+ # Handle long options
+ case "$OPTARG" in
+ lldb-args)
+ # Get the next argument
+ eval "LLDB_EXTRA_ARGS=\${$OPTIND}"
+ OPTIND=$((OPTIND + 1))
+ ;;
+ lldb-args=*)
+ # Handle --lldb-args=value format
+ LLDB_EXTRA_ARGS="${OPTARG#lldb-args=}"
+ ;;
+ *)
+ warnx "unknown option: --${OPTARG}"
+ usage
+ ;;
+ esac
+ ;;
+ *)
+ usage
+ ;;
+ esac
+done
+shift $((OPTIND - 1))
+
+# Check if more than one of -c, -n, -r are set
+count=0
+[ -n "$VMCORE" ] && count=$((count + 1))
+[ -n "$DUMPNR" ] && count=$((count + 1))
+[ -n "$DEVICE" ] && count=$((count + 1))
+
+if [ "$count" -gt 1 ]; then
+ warnx "options -c, -n and -r are mutually exclusive"
+ usage
+fi
+
+if [ -n "$VERBOSE" ] && [ "${#VERBOSE}" -gt 1 ]; then
+ warnx "using ${CRASHDIR} as the crash directory"
+fi
+
+# Get kernel argument if provided
+if [ -n "$1" ]; then
+ KERNEL="$1"
+ shift
+fi
+
+# Check for extra core file argument with -n or -r
+if [ -n "$1" ] && { [ -n "$DUMPNR" ] || [ -n "$DEVICE" ]; }; then
+ warnx "options -n and -r do not take a core file. Ignored"
+ shift
+fi
+
+# Handle dumpnr option
+if [ -n "$DUMPNR" ]; then
+ path="${CRASHDIR}/vmcore.${DUMPNR}"
+ if [ ! -e "$path" ]; then
+ err 1 "$path"
+ fi
+ if [ ! -f "$path" ]; then
+ errx 1 "${path}: not a regular file"
+ fi
+ VMCORE="$path"
+elif [ -n "$DEVICE" ]; then
+ verify_remote
+elif [ -n "$1" ]; then
+ if [ -z "$VMCORE" ]; then
+ VMCORE="$1"
+ shift
+ fi
+ if [ -n "$1" ]; then
+ warnx "multiple core files specified. Ignored"
+ fi
+elif [ -z "$VMCORE" ] && [ -z "$KERNEL" ]; then
+ VMCORE="/dev/mem"
+ KERNEL=$(sysctl -n kern.bootfile 2>/dev/null)
+ KERNEL=${KERNEL:-/boot/kernel/kernel}
+fi
+
+# Verbose output
+if [ -n "$VERBOSE" ]; then
+ [ -n "$VMCORE" ] && warnx "core file: ${VMCORE}"
+ [ -n "$DEVICE" ] && warnx "device file: ${DEVICE}"
+ [ -n "$KERNEL" ] && warnx "kernel image: ${KERNEL}"
+fi
+
+# A remote target requires an explicit kernel argument.
+if [ -n "$DEVICE" ] && [ -z "$KERNEL" ]; then
+ warnx "remote debugging requires a kernel"
+ usage
+fi
+
+# If we don't have a kernel image yet, try to find one.
+if [ -z "$KERNEL" ]; then
+ if [ -n "$DUMPNR" ]; then
+ kernel_from_dumpnr "$DUMPNR"
+ fi
+
+ if [ -z "$KERNEL" ]; then
+ errx 1 "couldn't find a suitable kernel image"
+ fi
+ if [ -n "$VERBOSE" ]; then
+ warnx "kernel image: ${KERNEL}"
+ fi
+fi
+
+# Build lldb command arguments
+LLDBARGS="${LLDB_EXTRA_ARGS}"
+
+# Source quietly by default
+if [ -n "$VERBOSE" ] || [ "${#VERBOSE}" -lt 3 ]; then
+ LLDBARGS="${LLDBARGS} -Q"
+fi
+
+# Set an alternate prompt.
+LLDBARGS="${LLDBARGS} -o 'settings set prompt \"(kdb) \"'"
+
+# Set baud rate if specified
+if [ -n "$BAUDRATE" ]; then
+ LLDBARGS="${LLDBARGS} -o 'settings set " \
+"plugin.process.gdb-remote.serial-baud-rate ${BAUDRATE}'"
+fi
+
+if [ -n "$VMCORE" ]; then
+ # Open the vmcore if requested.
+ # Use standard lldb syntax: lldb kernel -c core
+ LLDBARGS="${LLDBARGS} \"${KERNEL}\" -c \"${VMCORE}\""
+elif [ -n "$DEVICE" ]; then
+ # Open the remote target if requested.
+ LLDBARGS="${LLDBARGS} -o 'target create \"${KERNEL}\"'"
+ LLDBARGS="${LLDBARGS} -o 'gdb-remote ${DEVICE}'"
+else
+ # Just kernel, no core
+ LLDBARGS="${LLDBARGS} \"${KERNEL}\""
+fi
+
+# Execute lldb
+eval "exec lldb ${LLDBARGS}"

File Metadata

Mime Type
text/plain
Expires
Sun, Jul 5, 5:52 PM (13 h, 55 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34719078
Default Alt Text
D54895.diff (14 KB)

Event Timeline