add sg_bg_ctl; small cleanups

git-svn-id: svn://localhost/trunk@706 6180dd3e-e324-4e3e-922d-17de1ae2f315

Author: doug-gilbert

BSD_LICENSE

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999-2013 Douglas Gilbert.
+ * Copyright (c) 1999-2016 Douglas Gilbert.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without

COVERAGE

@@ -6,12 +6,14 @@ of them on the right. The second table lists supported ATA commands.
 
 SCSI command        sg3_utils utilities that use this SCSI command
 ------------        -------------------------------------------------
+ATA COMMAND PASS-THROUGH(12)  sg_sat_identify, ++
 ATA COMMAND PASS-THROUGH(16)  sg_sat_identify, sg_sat_set_features,
                     sg_sat_phy_event, sg_sat_read_gplog ++
                     [sg_sat_chk_power, sg__sat_identify,
                      sg__sat_set_features, sg_sat_smart_rd_data
                      (previous four in the examples directory)]
-ATA COMMAND PASS-THROUGH(12)  sg_sat_identify, ++
+ATA COMMAND PASS-THROUGH(32)  sg_sat_identify, ++
+BACKGROUND CONTROL  sg_bg_ctl
 CLOSE ZONE          sg_zone
 COMPARE AND WRITE   sg_compare_and_write
 COPY OPERATION ABORT    ddptctl, ++
@@ -133,4 +135,4 @@ THIRD PARTY COPY IN (0x83).
 
 
 Douglas Gilbert
-8th February 2016
+19th May 2016

ChangeLog

@@ -2,7 +2,8 @@ Each utility has its own version number, date of last change and
 some description at the top of its ".c" file. All utilities in the main
 directory have their own "man" pages. There is also a sg3_utils man page.
 
-Changelog for sg3_utils-1.43 [20160517] [svn: r705]
+Changelog for sg3_utils-1.43 [20160519] [svn: r706]
+  - sg_bg_ctl: new Background control command (spc4r08)
   - sg_senddiag: add --timeout=SEC option
   - sg_sanitize: add --timeout=SEC option
   - sg_format: add --timeout=SEC option

README

@@ -229,8 +229,8 @@ Utilities
 =========
 Here is list in alphabetical order of utilities found in the 'src'
 subdirectory of the sg3_utils package:
-    sginfo, sg_compare_and_write, sg_copy_results, sgm_dd, sgp_dd, sg_dd,
-    sg_decode_sense, sg_emc_trespass, sg_format, sg_get_config,
+    sginfo, sg_bt_ctl, sg_compare_and_write, sg_copy_results, sgm_dd, sgp_dd,
+    sg_dd, sg_decode_sense, sg_emc_trespass, sg_format, sg_get_config,
     sg_get_lba_status, sg_ident, sg_inq, sg_logs, sg_luns, sg_map, sg_map26,
     sg_modes, sg_opcodes, sg_persist, sg_prevent, sg_raw, sg_rbuf, sg_rdac,
     sg_read, sg_read_attr, sg_readcap, sg_read_block_limits, sg_read_buffer,
@@ -382,15 +382,15 @@ interface by defining the SG3_UTILS_OLD_OPTS environment variable
 or using '-O' as the first command line option.
 
 The more recent utilities that use "getopt_long" only are:
-  - sg_compare_and_write, sg_decode_sense, sg_format, sg_get_config,
-    sg_get_lba_status, sg_ident, sg_luns, sg_map26, sg_persist, sg_prevent,
-    sg_raw, sg_read_attr, sg_read_block_limits, sg_read_buffer, sg_read_long,
-    sg_reassign, sg_referrals, sg_requests, sg_rmsn, sg_rtpg, sg_safte,
-    sg_sanitize, sg_sat_identify, sg_sat_phy_event, sg_sat_read_gplog,
-    sg_sat_set_features, sg_scan(w), sg_ses, sg_ses_microcode, sg_stpg,
-    sg_sync, sg_test_rwbuf, sg_timestamp, sg_unmap, sg_verify, sg_vpd,
-    sg_write_buffer, sg_write_long, sg_write_same, sg_write_verify,
-    sg_wr_mode, sg_zone
+  - sg_bt_ctl, sg_compare_and_write, sg_decode_sense, sg_format,
+    sg_get_config, sg_get_lba_status, sg_ident, sg_luns, sg_map26,
+    sg_persist, sg_prevent, sg_raw, sg_read_attr, sg_read_block_limits,
+    sg_read_buffer, sg_read_long, sg_reassign, sg_referrals, sg_requests,
+    sg_rmsn, sg_rtpg, sg_safte, sg_sanitize, sg_sat_identify,
+    sg_sat_phy_event, sg_sat_read_gplog, sg_sat_set_features, sg_scan(w),
+    sg_ses, sg_ses_microcode, sg_stpg, sg_sync, sg_test_rwbuf, sg_timestamp,
+    sg_unmap, sg_verify, sg_vpd, sg_write_buffer, sg_write_long,
+    sg_write_same, sg_write_verify, sg_wr_mode, sg_zone
 
 
 Dangerous code
@@ -462,4 +462,4 @@ See http://sg.danny.cz/sg/tools.html
 
 
 Douglas Gilbert
-17th May 2016
+19th May 2016

doc/Makefile.am

@@ -1,18 +1,19 @@
 
 man_MANS = \
 	scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 scsi_start.8 \
-	scsi_stop.8 scsi_temperature.8 sg3_utils.8 sg_compare_and_write.8 \
-	sg_decode_sense.8 sg_format.8 sg_get_config.8 sg_get_lba_status.8 \
-	sg_ident.8 sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 \
-	sg_persist.8 sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
-	sg_read_block_limits.8 sg_read_buffer.8 sg_read_long.8 sg_readcap.8 \
-	sg_reassign.8 sg_referrals.8 sg_rep_zones.8 sg_requests.8 \
-	sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 sg_sanitize.8 \
-	sg_sat_identify.8 sg_sat_phy_event.8 sg_sat_read_gplog.8 \
-	sg_sat_set_features.8 sg_senddiag.8 sg_ses.8 sg_ses_microcode.8 \
-	sg_start.8 sg_stpg.8 sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 \
-	sg_verify.8 sg_vpd.8 sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 \
-	sg_write_same.8 sg_write_verify.8 sg_zone.8
+	scsi_stop.8 scsi_temperature.8 sg3_utils.8 sg_bg_ctl.8 \
+	sg_compare_and_write.8 sg_decode_sense.8 sg_format.8 sg_get_config.8 \
+	sg_get_lba_status.8 sg_ident.8 sg_inq.8 sg_logs.8 sg_luns.8 \
+	sg_modes.8 sg_opcodes.8 sg_persist.8 sg_prevent.8 sg_raw.8 sg_rdac.8 \
+	sg_read_attr.8 sg_read_block_limits.8 sg_read_buffer.8 \
+	sg_read_long.8 sg_readcap.8 sg_reassign.8 sg_referrals.8 \
+	sg_rep_zones.8 sg_requests.8 sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 \
+	sg_safte.8 sg_sanitize.8 sg_sat_identify.8 sg_sat_phy_event.8 \
+	sg_sat_read_gplog.8 sg_sat_set_features.8 sg_senddiag.8 sg_ses.8 \
+	sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_sync.8 sg_timestamp.8 \
+	sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 sg_wr_mode.8 \
+	sg_write_buffer.8 sg_write_long.8 sg_write_same.8 sg_write_verify.8 \
+	sg_zone.8
 CLEANFILES =
 
 if OS_LINUX

doc/Makefile.in

@@ -282,10 +282,10 @@ top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 \
 	scsi_start.8 scsi_stop.8 scsi_temperature.8 sg3_utils.8 \
-	sg_compare_and_write.8 sg_decode_sense.8 sg_format.8 \
-	sg_get_config.8 sg_get_lba_status.8 sg_ident.8 sg_inq.8 \
-	sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 sg_persist.8 \
-	sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
+	sg_bg_ctl.8 sg_compare_and_write.8 sg_decode_sense.8 \
+	sg_format.8 sg_get_config.8 sg_get_lba_status.8 sg_ident.8 \
+	sg_inq.8 sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 \
+	sg_persist.8 sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
 	sg_read_block_limits.8 sg_read_buffer.8 sg_read_long.8 \
 	sg_readcap.8 sg_reassign.8 sg_referrals.8 sg_rep_zones.8 \
 	sg_requests.8 sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 \

doc/sg_bg_ctl.8

@@ -0,0 +1,72 @@
+.TH SG_BG_CTL "8" "May 2016" "sg3_utils\-1.43" SG3_UTILS
+.SH NAME
+sg_bg_ctl \- send SCSI BACKGROUND CONTROL command
+.SH SYNOPSIS
+.B sg_bg_ctl
+[\fI\-\-ctl=CTL\fR] [\fI\-\-help\fR] [\fI\-\-time=TN\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI BACKGROUND CONTROL command to the \fIDEVICE\fR. This command
+was first found in the SBC\-4 draft standard revision 8 (sbc4r08.pdf). It can
+be used to start and stop 'advanced background operations' on the
+\fIDEVICE\fR. Only resource or thin provisioned devices (logical units which
+are typically (solid state) disks) support this command. Those advanced
+background operations often include garbage collection type operations which
+may degrade the disk's performance while they are being performed.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-c\fR, \fB\-\-ctl\fR=\fICTL\fR
+\fICTL\fR is the value placed in the BO_CTL field of the BACKGROUND CONTROL
+command (cdb). It is a two bit field so has 4 variants: 0 does not change
+the host initiated advanced background operations; 1 starts these operations;
+2 stops these operations and 3 is reserved. The default value is 0.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-t\fR, \fB\-\-time\fR=\fITN\fR
+\fITN\fR is a maximum time (with a unit of 100 ms or 1/10 second) that
+advanced background operations can occur. This value is ignored if the
+\fICTL\fR argument is other than 1. The default value is 0 which means there
+is no maximum time limit. Only values 0 to 255 (which is 25.5 seconds) can
+be given. This value is place in the BO_TIME field of the BACKGROUND CONTROL
+command.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.SH NOTES
+According to T10, support for 'background control operations' is indicated by
+the BOCS bit being set in the Block device characteristics VPD page [0xb1].
+The setting of the BOCS bit can be checked with the sg_vpd and sdparm
+utilities (and it is read only). There is a Background operations control
+mode page [0xa, 0x6] with a BO_MODE field for modifying the action of this
+operation. The BO_MODE field can be accessed and possibly modified with the
+sdparm utility. The BO_STATUS field can be found in the Background operation
+log page [0x15, 0x2] and that can be viewed with the sg_logs utility.
+.PP
+The current draft describing this area is SBC\-4 revision 10 (sbc4r10.pdf)
+in clause 4.33 . That contains the following example of a background
+operation: "Advanced background operation may include NAND block erase
+operations, media read operations, and media write operations (e.g.,
+garbage collection), which may impact response time for normal read requests
+or write requests from the application client."
+.SH EXIT STATUS
+The exit status of sg_bg_ctl is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2016 Douglas Gilbert
+.br
+This software is distributed under a FreeBSD license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg_vpd,sg_logs(sg3_utils); sdparm(sdparm)

src/Makefile.am

@@ -1,11 +1,11 @@
 
 bin_PROGRAMS = \
-	sg_compare_and_write sg_decode_sense sg_format sg_get_config \
-	sg_get_lba_status sg_ident sg_inq sg_logs sg_luns sg_modes \
-	sg_opcodes sg_persist sg_prevent sg_raw sg_rdac sg_read_attr \
-	sg_read_block_limits sg_read_buffer sg_read_long sg_readcap \
-	sg_reassign sg_referrals sg_rep_zones sg_requests sg_reset_wp \
-	sg_rmsn sg_rtpg sg_safte sg_sanitize sg_sat_identify \
+	sg_bg_ctl sg_compare_and_write sg_decode_sense sg_format \
+	sg_get_config sg_get_lba_status sg_ident sg_inq sg_logs sg_luns \
+	sg_modes sg_opcodes sg_persist sg_prevent sg_raw sg_rdac \
+	sg_read_attr sg_read_block_limits sg_read_buffer sg_read_long \
+	sg_readcap sg_reassign sg_referrals sg_rep_zones sg_requests \
+	sg_reset_wp sg_rmsn sg_rtpg sg_safte sg_sanitize sg_sat_identify \
 	sg_sat_phy_event sg_sat_read_gplog sg_sat_set_features sg_senddiag \
 	sg_ses sg_ses_microcode sg_start sg_stpg sg_sync sg_timestamp \
 	sg_turs sg_unmap sg_verify sg_vpd sg_wr_mode sg_write_buffer \
@@ -47,6 +47,8 @@ AM_CFLAGS = -Wall -W @os_cflags@
 # AM_CFLAGS = -Wall -W @os_cflags@ -pedantic -std=c11 --analyze
 # AM_CFLAGS = -Wall -W @os_cflags@ -pedantic -std=c++14
 
+sg_bg_ctl_LDADD = ../lib/libsgutils2.la @os_libs@
+
 sg_compare_and_write_LDADD = ../lib/libsgutils2.la @os_libs@
 
 sg_copy_results_LDADD = ../lib/libsgutils2.la @os_libs@

src/Makefile.in

@@ -88,12 +88,13 @@ PRE_UNINSTALL = :
 POST_UNINSTALL = :
 build_triplet = @build@
 host_triplet = @host@
-bin_PROGRAMS = sg_compare_and_write$(EXEEXT) sg_decode_sense$(EXEEXT) \
-	sg_format$(EXEEXT) sg_get_config$(EXEEXT) \
-	sg_get_lba_status$(EXEEXT) sg_ident$(EXEEXT) sg_inq$(EXEEXT) \
-	sg_logs$(EXEEXT) sg_luns$(EXEEXT) sg_modes$(EXEEXT) \
-	sg_opcodes$(EXEEXT) sg_persist$(EXEEXT) sg_prevent$(EXEEXT) \
-	sg_raw$(EXEEXT) sg_rdac$(EXEEXT) sg_read_attr$(EXEEXT) \
+bin_PROGRAMS = sg_bg_ctl$(EXEEXT) sg_compare_and_write$(EXEEXT) \
+	sg_decode_sense$(EXEEXT) sg_format$(EXEEXT) \
+	sg_get_config$(EXEEXT) sg_get_lba_status$(EXEEXT) \
+	sg_ident$(EXEEXT) sg_inq$(EXEEXT) sg_logs$(EXEEXT) \
+	sg_luns$(EXEEXT) sg_modes$(EXEEXT) sg_opcodes$(EXEEXT) \
+	sg_persist$(EXEEXT) sg_prevent$(EXEEXT) sg_raw$(EXEEXT) \
+	sg_rdac$(EXEEXT) sg_read_attr$(EXEEXT) \
 	sg_read_block_limits$(EXEEXT) sg_read_buffer$(EXEEXT) \
 	sg_read_long$(EXEEXT) sg_readcap$(EXEEXT) sg_reassign$(EXEEXT) \
 	sg_referrals$(EXEEXT) sg_rep_zones$(EXEEXT) \
@@ -139,13 +140,16 @@ CONFIG_CLEAN_VPATH_FILES =
 @OS_WIN32_CYGWIN_TRUE@am__EXEEXT_3 = sg_scan$(EXEEXT)
 am__installdirs = "$(DESTDIR)$(bindir)"
 PROGRAMS = $(bin_PROGRAMS)
-sg_compare_and_write_SOURCES = sg_compare_and_write.c
-sg_compare_and_write_OBJECTS = sg_compare_and_write.$(OBJEXT)
-sg_compare_and_write_DEPENDENCIES = ../lib/libsgutils2.la
+sg_bg_ctl_SOURCES = sg_bg_ctl.c
+sg_bg_ctl_OBJECTS = sg_bg_ctl.$(OBJEXT)
+sg_bg_ctl_DEPENDENCIES = ../lib/libsgutils2.la
 AM_V_lt = $(am__v_lt_@AM_V@)
 am__v_lt_ = $(am__v_lt_@AM_DEFAULT_V@)
 am__v_lt_0 = --silent
 am__v_lt_1 = 
+sg_compare_and_write_SOURCES = sg_compare_and_write.c
+sg_compare_and_write_OBJECTS = sg_compare_and_write.$(OBJEXT)
+sg_compare_and_write_DEPENDENCIES = ../lib/libsgutils2.la
 sg_copy_results_SOURCES = sg_copy_results.c
 sg_copy_results_OBJECTS = sg_copy_results.$(OBJEXT)
 sg_copy_results_DEPENDENCIES = ../lib/libsgutils2.la
@@ -374,7 +378,7 @@ AM_V_CCLD = $(am__v_CCLD_@AM_V@)
 am__v_CCLD_ = $(am__v_CCLD_@AM_DEFAULT_V@)
 am__v_CCLD_0 = @echo "  CCLD    " $@;
 am__v_CCLD_1 = 
-SOURCES = sg_compare_and_write.c sg_copy_results.c sg_dd.c \
+SOURCES = sg_bg_ctl.c sg_compare_and_write.c sg_copy_results.c sg_dd.c \
 	sg_decode_sense.c sg_emc_trespass.c sg_format.c \
 	sg_get_config.c sg_get_lba_status.c sg_ident.c \
 	$(sg_inq_SOURCES) sg_logs.c sg_luns.c sg_map.c sg_map26.c \
@@ -390,8 +394,8 @@ SOURCES = sg_compare_and_write.c sg_copy_results.c sg_dd.c \
 	sg_verify.c $(sg_vpd_SOURCES) sg_wr_mode.c sg_write_buffer.c \
 	sg_write_long.c sg_write_same.c sg_write_verify.c sg_xcopy.c \
 	sg_zone.c sginfo.c sgm_dd.c sgp_dd.c
-DIST_SOURCES = sg_compare_and_write.c sg_copy_results.c sg_dd.c \
-	sg_decode_sense.c sg_emc_trespass.c sg_format.c \
+DIST_SOURCES = sg_bg_ctl.c sg_compare_and_write.c sg_copy_results.c \
+	sg_dd.c sg_decode_sense.c sg_emc_trespass.c sg_format.c \
 	sg_get_config.c sg_get_lba_status.c sg_ident.c \
 	$(sg_inq_SOURCES) sg_logs.c sg_luns.c sg_map.c sg_map26.c \
 	sg_modes.c sg_opcodes.c sg_persist.c sg_prevent.c sg_raw.c \
@@ -564,6 +568,7 @@ AM_CFLAGS = -Wall -W @os_cflags@
 # AM_CFLAGS = -Wall -W @os_cflags@ -pedantic -std=c11
 # AM_CFLAGS = -Wall -W @os_cflags@ -pedantic -std=c11 --analyze
 # AM_CFLAGS = -Wall -W @os_cflags@ -pedantic -std=c++14
+sg_bg_ctl_LDADD = ../lib/libsgutils2.la @os_libs@
 sg_compare_and_write_LDADD = ../lib/libsgutils2.la @os_libs@
 sg_copy_results_LDADD = ../lib/libsgutils2.la @os_libs@
 sg_dd_LDADD = ../lib/libsgutils2.la @os_libs@
@@ -715,6 +720,10 @@ clean-binPROGRAMS:
 	echo " rm -f" $$list; \
 	rm -f $$list
 
+sg_bg_ctl$(EXEEXT): $(sg_bg_ctl_OBJECTS) $(sg_bg_ctl_DEPENDENCIES) $(EXTRA_sg_bg_ctl_DEPENDENCIES) 
+	@rm -f sg_bg_ctl$(EXEEXT)
+	$(AM_V_CCLD)$(LINK) $(sg_bg_ctl_OBJECTS) $(sg_bg_ctl_LDADD) $(LIBS)
+
 sg_compare_and_write$(EXEEXT): $(sg_compare_and_write_OBJECTS) $(sg_compare_and_write_DEPENDENCIES) $(EXTRA_sg_compare_and_write_DEPENDENCIES) 
 	@rm -f sg_compare_and_write$(EXEEXT)
 	$(AM_V_CCLD)$(LINK) $(sg_compare_and_write_OBJECTS) $(sg_compare_and_write_LDADD) $(LIBS)
@@ -977,6 +986,7 @@ mostlyclean-compile:
 distclean-compile:
 	-rm -f *.tab.c
 
+@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sg_bg_ctl.Po@am__quote@
 @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sg_compare_and_write.Po@am__quote@
 @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sg_copy_results.Po@am__quote@
 @AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/sg_dd.Po@am__quote@