1 /*
2 * Copyright (c) 2016-2021 Douglas Gilbert.
3 * All rights reserved.
4 * Use of this source code is governed by a BSD-style
5 * license that can be found in the BSD_LICENSE file.
6 *
7 * SPDX-License-Identifier: BSD-2-Clause
8 */
9
10 #include <unistd.h>
11 #include <fcntl.h>
12 #include <stdio.h>
13 #include <stdlib.h>
14 #include <stdbool.h>
15 #include <string.h>
16 #include <ctype.h>
17 #include <getopt.h>
18 #define __STDC_FORMAT_MACROS 1
19 #include <inttypes.h>
20
21 #ifdef HAVE_CONFIG_H
22 #include "config.h"
23 #endif
24 #include "sg_lib.h"
25 #include "sg_lib_data.h"
26 #include "sg_pt.h"
27 #include "sg_cmds_basic.h"
28 #include "sg_unaligned.h"
29 #include "sg_pr2serr.h"
30
31 /* A utility program originally written for the Linux OS SCSI subsystem.
32 *
33 *
34 * This program issues the SCSI BACKGROUND CONTROL command to the given SCSI
35 * device. Based on sbc4r10.pdf .
36 */
37
38 static const char * version_str = "1.13 20211114";
39
40 #define BACKGROUND_CONTROL_SA 0x15
41
42 #define SENSE_BUFF_LEN 64 /* Arbitrary, could be larger */
43 #define DEF_PT_TIMEOUT 60 /* 60 seconds */
44
45 static const char * cmd_name = "Background control";
46
47
48 static struct option long_options[] = {
49 {"ctl", required_argument, 0, 'c'},
50 {"help", no_argument, 0, 'h'},
51 {"time", required_argument, 0, 't'},
52 {"verbose", no_argument, 0, 'v'},
53 {"version", no_argument, 0, 'V'},
54 {0, 0, 0, 0},
55 };
56
57
58 static void
usage()59 usage()
60 {
61 pr2serr("Usage: "
62 "sg_bg_ctl [--ctl=CTL] [--help] [--time=TN] [--verbose] "
63 "[--version]\n"
64 " DEVICE\n");
65 pr2serr(" where:\n"
66 " --ctl=CTL|-c CTL CTL is background operation control "
67 "value\n"
68 " default: 0 -> don't change background "
69 "operations\n"
70 " 1 -> start; 2 -> stop\n"
71 " --help|-h print out usage message\n"
72 " --time=TN|-t TN TN (units 100 ms) is max time to perform "
73 "background\n"
74 " operations (def: 0 -> no limit)\n"
75 " --verbose|-v increase verbosity\n"
76 " --version|-V print version string and exit\n\n"
77 "Performs a SCSI BACKGROUND CONTROL command. It can start or "
78 "stop\n'advanced background operations'. Operations started by "
79 "this command\n(i.e. when ctl=1) are termed as 'host initiated' "
80 "and allow a resource or\nthin provisioned device (disk) to "
81 "perform garbage collection type operations.\nThese may "
82 "degrade performance while they occur. Hence it is best to\n"
83 "perform this action while the computer is not too busy.\n");
84 }
85
86 /* Invokes a SCSI BACKGROUND CONTROL command (SBC-4). Return of 0 -> success,
87 * various SG_LIB_CAT_* positive values or -1 -> other errors */
88 static int
sg_ll_background_control(int sg_fd,unsigned int bo_ctl,unsigned int bo_time,bool noisy,int verbose)89 sg_ll_background_control(int sg_fd, unsigned int bo_ctl, unsigned int bo_time,
90 bool noisy, int verbose)
91 {
92 int ret, res, sense_cat;
93 uint8_t bcCDB[16] = {SG_SERVICE_ACTION_IN_16,
94 BACKGROUND_CONTROL_SA, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
95 0, 0, 0, 0};
96 uint8_t sense_b[SENSE_BUFF_LEN] SG_C_CPP_ZERO_INIT;
97 struct sg_pt_base * ptvp;
98
99 if (bo_ctl)
100 bcCDB[2] |= (bo_ctl & 0x3) << 6;
101 if (bo_time)
102 bcCDB[3] = bo_time;
103 if (verbose) {
104 char b[128];
105
106 pr2serr(" %s cdb: %s\n", cmd_name,
107 sg_get_command_str(bcCDB, (int)sizeof(bcCDB), false,
108 sizeof(b), b));
109 }
110
111 ptvp = construct_scsi_pt_obj();
112 if (NULL == ptvp) {
113 pr2serr("%s: out of memory\n", cmd_name);
114 return -1;
115 }
116 set_scsi_pt_cdb(ptvp, bcCDB, sizeof(bcCDB));
117 set_scsi_pt_sense(ptvp, sense_b, sizeof(sense_b));
118 res = do_scsi_pt(ptvp, sg_fd, DEF_PT_TIMEOUT, verbose);
119 ret = sg_cmds_process_resp(ptvp, cmd_name, res, noisy, verbose,
120 &sense_cat);
121 if (-1 == ret) {
122 if (get_scsi_pt_transport_err(ptvp))
123 ret = SG_LIB_TRANSPORT_ERROR;
124 else
125 ret = sg_convert_errno(get_scsi_pt_os_err(ptvp));
126 } else if (-2 == ret) {
127 switch (sense_cat) {
128 case SG_LIB_CAT_RECOVERED:
129 case SG_LIB_CAT_NO_SENSE:
130 ret = 0;
131 break;
132 default:
133 ret = sense_cat;
134 break;
135 }
136 } else
137 ret = 0;
138 destruct_scsi_pt_obj(ptvp);
139 return ret;
140 }
141
142
143 int
main(int argc,char * argv[])144 main(int argc, char * argv[])
145 {
146 bool verbose_given = false;
147 bool version_given = false;
148 int sg_fd = -1;
149 int res, c;
150 unsigned int ctl = 0;
151 unsigned int time_tnth = 0;
152 int verbose = 0;
153 const char * device_name = NULL;
154 int ret = 0;
155
156 while (1) {
157 int option_index = 0;
158
159 c = getopt_long(argc, argv, "c:ht:vV", long_options, &option_index);
160 if (c == -1)
161 break;
162
163 switch (c) {
164 case 'c':
165 if ((1 != sscanf(optarg, "%4u", &ctl)) || (ctl > 3)) {
166 pr2serr("--ctl= expects a number from 0 to 3\n");
167 return SG_LIB_SYNTAX_ERROR;
168 }
169 break;
170 case 'h':
171 case '?':
172 usage();
173 return 0;
174 case 't':
175 if ((1 != sscanf(optarg, "%4u", &time_tnth)) ||
176 (time_tnth > 255)) {
177 pr2serr("--time= expects a number from 0 to 255\n");
178 return SG_LIB_SYNTAX_ERROR;
179 }
180 break;
181 case 'v':
182 verbose_given = true;
183 ++verbose;
184 break;
185 case 'V':
186 version_given = true;
187 break;
188 default:
189 pr2serr("unrecognised option code 0x%x ??\n", c);
190 usage();
191 return SG_LIB_SYNTAX_ERROR;
192 }
193 }
194 if (optind < argc) {
195 if (NULL == device_name) {
196 device_name = argv[optind];
197 ++optind;
198 }
199 if (optind < argc) {
200 for (; optind < argc; ++optind)
201 pr2serr("Unexpected extra argument: %s\n",
202 argv[optind]);
203 usage();
204 return SG_LIB_SYNTAX_ERROR;
205 }
206 }
207 #ifdef DEBUG
208 pr2serr("In DEBUG mode, ");
209 if (verbose_given && version_given) {
210 pr2serr("but override: '-vV' given, zero verbose and continue\n");
211 verbose_given = false;
212 version_given = false;
213 verbose = 0;
214 } else if (! verbose_given) {
215 pr2serr("set '-vv'\n");
216 verbose = 2;
217 } else
218 pr2serr("keep verbose=%d\n", verbose);
219 #else
220 if (verbose_given && version_given)
221 pr2serr("Not in DEBUG mode, so '-vV' has no special action\n");
222 #endif
223 if (version_given) {
224 pr2serr("version: %s\n", version_str);
225 return 0;
226 }
227
228 if (NULL == device_name) {
229 pr2serr("missing device name!\n\n");
230 usage();
231 return SG_LIB_SYNTAX_ERROR;
232 }
233
234 sg_fd = sg_cmds_open_device(device_name, false, verbose);
235 if (sg_fd < 0) {
236 if (verbose)
237 pr2serr("open error: %s: %s\n", device_name,
238 safe_strerror(-sg_fd));
239 ret = sg_convert_errno(-sg_fd);
240 goto fini;
241 }
242
243 res = sg_ll_background_control(sg_fd, ctl, time_tnth, true, verbose);
244 ret = res;
245 if (res) {
246 if (SG_LIB_CAT_INVALID_OP == res)
247 pr2serr("%s command not supported\n", cmd_name);
248 else {
249 char b[80];
250
251 sg_get_category_sense_str(res, sizeof(b), b, verbose);
252 pr2serr("%s command: %s\n", cmd_name, b);
253 }
254 }
255
256 fini:
257 if (0 == verbose) {
258 if (! sg_if_can2stderr("sg_bg_ctl failed: ", ret))
259 pr2serr("Some error occurred, try again with '-v' or '-vv' for "
260 "more information\n");
261 }
262 if (sg_fd >= 0) {
263 res = sg_cmds_close_device(sg_fd);
264 if (res < 0) {
265 pr2serr("close error: %s\n", safe_strerror(-res));
266 if (0 == ret)
267 ret = sg_convert_errno(-res);
268 }
269 }
270 return (ret >= 0) ? ret : SG_LIB_CAT_OTHER;
271 }
272