From d8fd37e1e13483e5494e3bbb93b053134ab3c7b9 Mon Sep 17 00:00:00 2001
From: Gordon Bergling <gbe@FreeBSD.org>
Date: Fri, 17 Jul 2020 22:15:02 +0000
Subject: [PATCH] devstat(9): Update the man page to reflect the current
 implementation

- Rename devstat_add_entry to devstat_new_entry
- Update the description of devstat_trans_flags
- Add manpage aliases for devstat_start_transaction_bio and devstat_end_transaction_bio

PR:		157316
Submitted by:	novel
Reviewed by:	cem, bcr (mentor)
Approved by:	bcr (mentor)
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D25677
---
 ObsoleteFiles.inc        |  3 +++
 share/man/man9/Makefile  |  6 ++++--
 share/man/man9/devstat.9 | 41 ++++++++++++++++++++++------------------
 3 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
index 13689deea351..9e2baf525f22 100644
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -36,6 +36,9 @@
 #   xargs -n1 | sort | uniq -d;
 # done
 
+# 20200715: rework of devstat(9) man page
+OLD_FILES+=usr/share/man/man9/devstat_add_entry.9.gz
+
 # 20200714: update byacc to 20200330
 OLD_FILES+=usr/tests/usr.bin/yacc/btyacc_calc1.y
 OLD_FILES+=usr/tests/usr.bin/yacc/btyacc_demo.y
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 96a7c819eb18..c44805c01c9b 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -968,10 +968,12 @@ MLINKS+=device_set_desc.9 device_get_desc.9 \
 	device_set_desc.9 device_set_desc_copy.9
 MLINKS+=device_set_flags.9 device_get_flags.9
 MLINKS+=devstat.9 devicestat.9 \
-	devstat.9 devstat_add_entry.9 \
+	devstat.9 devstat_new_entry.9 \
 	devstat.9 devstat_end_transaction.9 \
+	devstat.9 devstat_end_transaction_bio.9 \
 	devstat.9 devstat_remove_entry.9 \
-	devstat.9 devstat_start_transaction.9
+	devstat.9 devstat_start_transaction.9 \
+	devstat.9 devstat_start_transaction_bio.9
 MLINKS+=disk.9 disk_add_alias.9 \
 	disk.9 disk_alloc.9 \
 	disk.9 disk_create.9 \
diff --git a/share/man/man9/devstat.9 b/share/man/man9/devstat.9
index 51119bc6b62b..5025fba6c3e1 100644
--- a/share/man/man9/devstat.9
+++ b/share/man/man9/devstat.9
@@ -27,25 +27,24 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 22, 2018
+.Dd July 15, 2020
 .Dt DEVSTAT 9
 .Os
 .Sh NAME
 .Nm devstat ,
-.Nm devstat_add_entry ,
 .Nm devstat_end_transaction ,
 .Nm devstat_end_transaction_bio ,
 .Nm devstat_end_transaction_bio_bt ,
+.Nm devstat_new_entry ,
 .Nm devstat_remove_entry ,
 .Nm devstat_start_transaction ,
 .Nm devstat_start_transaction_bio
 .Nd kernel interface for keeping device statistics
 .Sh SYNOPSIS
 .In sys/devicestat.h
-.Ft void
-.Fo devstat_add_entry
-.Fa "struct devstat *ds"
-.Fa "const char *dev_name"
+.Ft struct devstat *
+.Fo devstat_new_entry
+.Fa "const void *dev_name"
 .Fa "int unit_number"
 .Fa "uint32_t block_size"
 .Fa "devstat_support_flags flags"
@@ -78,7 +77,6 @@
 .Fa "struct devstat *ds"
 .Fa "const struct bio *bp"
 .Fc
-.Fc
 .Ft void
 .Fo devstat_end_transaction_bio_bt
 .Fa "struct devstat *ds"
@@ -103,19 +101,13 @@ for most disk-like drivers in the 2000s and beyond.
 New consumers of the interface should almost certainly use only the "bio"
 variants of the start and end transacation routines.
 .Pp
-.Fn devstat_add_entry
-registers a device with the
-.Nm
-subsystem.
-The caller is expected to have already allocated \fBand zeroed\fR
-the devstat structure before calling this function.
-.Fn devstat_add_entry
+.Fn devstat_new_entry
+allocates and initializes
+.Va devstat
+structure and returns a pointer to it.
+.Fn devstat_new_entry
 takes several arguments:
 .Bl -tag -width device_type
-.It ds
-The
-.Va devstat
-structure, allocated and zeroed by the client.
 .It dev_name
 The device name, e.g., da, cd, sa.
 .It unit_number
@@ -386,6 +378,8 @@ to insert a device in the
 list.
 The second parameter is attach order.
 See below for a list of available priorities.
+.It id
+Identification for GEOM nodes.
 .El
 .Pp
 Each device is given a device type.
@@ -478,8 +472,19 @@ typedef enum {
 	DEVSTAT_WRITE	= 0x02,
 	DEVSTAT_FREE	= 0x03
 } devstat_trans_flags;
+#define DEVSTAT_N_TRANS_FLAGS   4
 .Ed
 .Pp
+DEVSTAT_NO_DATA is a type of transactions to the device which are neither
+reads or writes.
+For instance,
+.Tn SCSI
+drivers often send a test unit ready command to
+.Tn SCSI
+devices.
+The test unit ready command does not read or write any data.
+It merely causes the device to return its status.
+.Pp
 There are four possible values for the
 .Va tag_type
 argument to