From: guenther <guenther@openbsd.org>
Date: Fri, 19 May 2023 18:43:16 +0000 (+0000)
Subject: uvm_coredump(9) was removed in 2015 (commitid dNPv28CJI5BxtRGW) as
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=b22a9f753ad50d507d7bcf908d5f76bdc4474722;p=openbsd

uvm_coredump(9) was removed in 2015 (commitid dNPv28CJI5BxtRGW) as
real processes have been dumped using uvm_coredump_walkmap(9) since
2009-03-05Z19:52:24.  Document the current API.
---

diff --git a/share/man/man9/uvm_init.9 b/share/man/man9/uvm_init.9
index 7aa15559a8b..d34d2869cfe 100644
--- a/share/man/man9/uvm_init.9
+++ b/share/man/man9/uvm_init.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: uvm_init.9,v 1.3 2020/04/23 07:57:27 mpi Exp $
+.\"	$OpenBSD: uvm_init.9,v 1.4 2023/05/19 18:43:16 guenther Exp $
 .\"	$NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $
 .\"
 .\" Copyright (c) 1998 Matthew R. Green
@@ -28,7 +28,7 @@
 .\" XXX this manual sets nS to 1 or 0 in the description, to obtain
 .\" synopsis-like function prototypes.  any better way?
 .\"
-.Dd $Mdocdate: April 23 2020 $
+.Dd $Mdocdate: May 19 2023 $
 .Dt UVM_INIT 9
 .Os
 .Sh NAME
@@ -46,7 +46,7 @@
 .Nm uvm_meter ,
 .Nm uvm_sysctl ,
 .Nm uvm_grow ,
-.Nm uvm_coredump
+.Nm uvm_coredump_walkmap
 .Nd virtual memory system external interface
 .Sh SYNOPSIS
 .In sys/param.h
@@ -174,7 +174,7 @@ argument is ignored.
 .Ft int
 .Fn uvm_grow "struct proc *p" "vaddr_t sp"
 .Ft int
-.Fn uvm_coredump "struct proc *p" "struct vnode *vp" "struct ucred *cred" "struct core *chdr"
+.Fn uvm_coredump_walkmap "struct proc *p" "uvm_coredump_setup_cb *setup" "struct uvm_coredump_walk_cb *walk" "void *cookie"
 .nr nS 0
 .Pp
 The
@@ -349,15 +349,48 @@ to include
 .Fa sp .
 .Pp
 The
-.Fn uvm_coredump
-function generates a coredump on vnode
-.Fa vp
-for process
+.Fn uvm_coredump_walkmap
+function supports writing out the memory image of a process in a
+core file.
+It walks the address space for process
 .Fa p
-with credentials
-.Fa cred
-and core header description in
-.Fa chdr .
+and counts of the number of segments necessary to hold the
+dumpable memory,
+where a segment consists of one-or-more present pages followed by
+zero-or-more mapped but not present (zero-fill) pages,
+or just one-or-more mapped but not present pages.
+It then invokes
+.Fa setup
+with that segment count and the
+.Fa cookie
+argument.
+.Bd -literal
+typedef int uvm_coredump_setup_cb(int nsegment, void *cookie);
+.Ed
+.Pp
+If that returns non-zero then
+.Fn uvm_coredump_walkmap
+returns that value immediately,
+otherwise it invokes
+.Fa walk
+once for each segment, in ascending address order,
+passing it the start of the segment,
+the start of the mapped-but-not-present pages,
+one past the last address in the segment,
+the protection on the segment,
+the index of the segment,
+and the
+.Fa cookie .
+.Bd -literal
+typedef int uvm_coredump_walk_cb(vaddr_t start, vaddr_t realend,
+    vaddr_t end, vm_prot_t prot, int nsegment, void *cookie);
+.Ed
+.Pp
+If a call to
+.Fa walk
+returns non-zero then
+.Fa uvm_coredump_walkmap
+returns that value immediately.
 .Sh NOTES
 The structure and types whose names begin with
 .Dq vm_
@@ -369,6 +402,7 @@ development stages.
 .Xr kvm 3 ,
 .Xr ddb 4 ,
 .Xr options 4 ,
+.Xr core 5 ,
 .Xr pmap 9
 .Rs
 .%A Charles D. Cranor