svn commit: r363291 - in head: . share/man/man9

[Gordon Bergling]

Author: gbe (doc committer)
Date: Fri Jul 17 22:15:02 2020
New Revision: 363291
URL: https://svnweb.freebsd.org/changeset/base/363291

Log:
  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

Modified:
  head/ObsoleteFiles.inc
  head/share/man/man9/Makefile
  head/share/man/man9/devstat.9

Modified: head/ObsoleteFiles.inc
==============================================================================
--- head/ObsoleteFiles.inc	Fri Jul 17 22:07:19 2020	(r363290)
+++ head/ObsoleteFiles.inc	Fri Jul 17 22:15:02 2020	(r363291)
@@ -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

Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile	Fri Jul 17 22:07:19 2020	(r363290)
+++ head/share/man/man9/Makefile	Fri Jul 17 22:15:02 2020	(r363291)
@@ -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 \

Modified: head/share/man/man9/devstat.9
==============================================================================
--- head/share/man/man9/devstat.9	Fri Jul 17 22:07:19 2020	(r363290)
+++ head/share/man/man9/devstat.9	Fri Jul 17 22:15:02 2020	(r363291)
@@ -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