svn commit: r364016 - in stable/12: . share/man/man9

[Gordon Bergling]

Author: gbe (doc committer)
Date: Fri Aug  7 15:03:20 2020
New Revision: 364016
URL: https://svnweb.freebsd.org/changeset/base/364016

Log:
  MFC r363291: 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
  Approved by:	bcr
  Differential Revision:	https://reviews.freebsd.org/D25677

Modified:
  stable/12/ObsoleteFiles.inc
  stable/12/share/man/man9/Makefile
  stable/12/share/man/man9/devstat.9
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/ObsoleteFiles.inc
==============================================================================
--- stable/12/ObsoleteFiles.inc	Fri Aug  7 13:42:47 2020	(r364015)
+++ stable/12/ObsoleteFiles.inc	Fri Aug  7 15:03:20 2020	(r364016)
@@ -289,6 +289,9 @@ OLD_DIRS+=usr/lib/clang/10.0.0/lib/freebsd
 OLD_DIRS+=usr/lib/clang/10.0.0/lib
 OLD_DIRS+=usr/lib/clang/10.0.0
 
+# 20200715: rework of devstat(9) man page
+OLD_FILES+=usr/share/man/man9/devstat_add_entry.9.gz
+
 # 20200516: Remove bogus man links
 OLD_FILES+=usr/share/man/man3/getauusernam_R.3.gz
 OLD_FILES+=usr/share/man/man3/getauclassnam_3.3.gz

Modified: stable/12/share/man/man9/Makefile
==============================================================================
--- stable/12/share/man/man9/Makefile	Fri Aug  7 13:42:47 2020	(r364015)
+++ stable/12/share/man/man9/Makefile	Fri Aug  7 15:03:20 2020	(r364016)
@@ -903,10 +903,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 \

Modified: stable/12/share/man/man9/devstat.9
==============================================================================
--- stable/12/share/man/man9/devstat.9	Fri Aug  7 13:42:47 2020	(r364015)
+++ stable/12/share/man/man9/devstat.9	Fri Aug  7 15:03:20 2020	(r364016)
@@ -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,7 +472,18 @@ 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