lib/libcam/cam.3

   1 .\"
   2 .\" Copyright (c) 1998 Kenneth D. Merry.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd July 6, 2020
  31 .Dt CAM 3
  32 .Os
  33 .Sh NAME
  34 .Nm cam_open_device ,
  35 .Nm cam_open_spec_device ,
  36 .Nm cam_open_btl ,
  37 .Nm cam_open_pass ,
  38 .Nm cam_close_device ,
  39 .Nm cam_close_spec_device ,
  40 .Nm cam_getccb ,
  41 .Nm cam_send_ccb ,
  42 .Nm cam_freeccb ,
  43 .Nm cam_path_string ,
  44 .Nm cam_device_dup ,
  45 .Nm cam_device_copy ,
  46 .Nm cam_get_device
  47 .Nd CAM user library
  48 .Sh LIBRARY
  49 .Lb libcam
  50 .Sh SYNOPSIS
  51 .In stdio.h
  52 .In camlib.h
  53 .Ft struct cam_device *
  54 .Fo cam_open_device
  55 .Fa "const char *path"
  56 .Fa "int flags"
  57 .Fc
  58 .Ft struct cam_device *
  59 .Fo cam_open_spec_device
  60 .Fa "const char *dev_name"
  61 .Fa "int unit"
  62 .Fa "int flags"
  63 .Fa "struct cam_device *device"
  64 .Fc
  65 .Ft struct cam_device *
  66 .Fo cam_open_btl
  67 .Fa "path_id_t path_id"
  68 .Fa "target_id_t target_id"
  69 .Fa "lun_id_t target_lun"
  70 .Fa "int flags"
  71 .Fa "struct cam_device *device"
  72 .Fc
  73 .Ft struct cam_device *
  74 .Fo cam_open_pass
  75 .Fa "const char *path"
  76 .Fa "int flags"
  77 .Fa "struct cam_device *device"
  78 .Fc
  79 .Ft void
  80 .Fo cam_close_device
  81 .Fa "struct cam_device *dev"
  82 .Fc
  83 .Ft void
  84 .Fo cam_close_spec_device
  85 .Fa "struct cam_device *dev"
  86 .Fc
  87 .Ft union ccb *
  88 .Fo cam_getccb
  89 .Fa "struct cam_device *dev"
  90 .Fc
  91 .Ft int
  92 .Fo cam_send_ccb
  93 .Fa "struct cam_device *device"
  94 .Fa "union ccb *ccb"
  95 .Fc
  96 .Ft void
  97 .Fo cam_freeccb
  98 .Fa "union ccb *ccb"
  99 .Fc
 100 .Ft char *
 101 .Fo cam_path_string
 102 .Fa "struct cam_device *dev"
 103 .Fa "char *str"
 104 .Fa "int len"
 105 .Fc
 106 .Ft struct cam_device *
 107 .Fo cam_device_dup
 108 .Fa "struct cam_device *device"
 109 .Fc
 110 .Ft void
 111 .Fo cam_device_copy
 112 .Fa "struct cam_device *src"
 113 .Fa "struct cam_device *dst"
 114 .Fc
 115 .Ft int
 116 .Fo cam_get_device
 117 .Fa "const char *path"
 118 .Fa "char *dev_name"
 119 .Fa "int devnamelen"
 120 .Fa "int *unit"
 121 .Fc
 122 .Sh DESCRIPTION
 123 The CAM library consists of a number of functions designed to aid in
 124 programming with the CAM subsystem.
 125 This man page covers the basic set of
 126 library functions.
 127 More functions are documented in the man pages listed
 128 below.
 129 .Pp
 130 Many of the CAM library functions use the
 131 .Va cam_device
 132 structure:
 133 .Bd -literal
 134 struct cam_device {
 135         char            device_path[MAXPATHLEN+1];/*
 136                                                    * Pathname of the
 137                                                    * device given by the
 138                                                    * user. This may be
 139                                                    * null if the user
 140                                                    * states the device
 141                                                    * name and unit number
 142                                                    * separately.
 143                                                    */
 144         char            given_dev_name[DEV_IDLEN+1];/*
 145                                                      * Device name given by
 146                                                      * the user.
 147                                                      */
 148         uint32_t        given_unit_number;          /*
 149                                                      * Unit number given by
 150                                                      * the user.
 151                                                      */
 152         char            device_name[DEV_IDLEN+1];/*
 153                                                   * Name of the device,
 154                                                   * e.g., 'pass'
 155                                                   */
 156         uint32_t        dev_unit_num;   /* Unit number of the passthrough
 157                                          * device associated with this
 158                                          * particular device.
 159                                          */
 160
 161         char            sim_name[SIM_IDLEN+1];/*
 162                                                * Controller name, e.g., 'ahc'
 163                                                */
 164         uint32_t        sim_unit_number; /* Controller unit number */
 165         uint32_t        bus_id;          /* Controller bus number */
 166         lun_id_t        target_lun;      /* Logical Unit Number */
 167         target_id_t     target_id;       /* Target ID */
 168         path_id_t       path_id;         /* System SCSI bus number */
 169         uint16_t        pd_type;         /* type of peripheral device */
 170         struct scsi_inquiry_data inq_data;  /* SCSI Inquiry data */
 171         uint8_t         serial_num[252]; /* device serial number */
 172         uint8_t         serial_num_len;  /* length of the serial number */
 173         uint8_t         sync_period;     /* Negotiated sync period */
 174         uint8_t         sync_offset;     /* Negotiated sync offset */
 175         uint8_t         bus_width;       /* Negotiated bus width */
 176         int             fd;              /* file descriptor for device */
 177 };
 178 .Ed
 179 .Pp
 180 .Fn cam_open_device
 181 takes as arguments a string describing the device it is to open, and
 182 .Ar flags
 183 suitable for passing to
 184 .Xr open 2 .
 185 The "path" passed in may actually be most any type of string that contains
 186 a device name and unit number to be opened.
 187 The string will be parsed by
 188 .Fn cam_get_device
 189 into a device name and unit number.
 190 Once the device name and unit number
 191 are determined, a lookup is performed to determine the passthrough device
 192 that corresponds to the given device.
 193 .Pp
 194 .Fn cam_open_spec_device
 195 opens the
 196 .Xr pass 4
 197 device that corresponds to the device name and unit number passed in.
 198 The
 199 .Ar flags
 200 should be flags suitable for passing to
 201 .Xr open 2 .
 202 The
 203 .Ar device
 204 argument is optional.
 205 The user may supply pre-allocated space for the
 206 .Va cam_device
 207 structure.
 208 If the
 209 .Ar device
 210 argument is
 211 .Dv NULL ,
 212 .Fn cam_open_spec_device
 213 will allocate space for the
 214 .Va cam_device
 215 structure using
 216 .Xr malloc 3 .
 217 .Pp
 218 .Fn cam_open_btl
 219 is similar to
 220 .Fn cam_open_spec_device ,
 221 except that it takes a SCSI bus,
 222 target and logical unit instead of a device name and unit number as
 223 arguments.
 224 The
 225 .Va path_id
 226 argument is the CAM equivalent of a SCSI bus number.
 227 It represents the logical bus number in the system.
 228 The
 229 .Ar flags
 230 should be flags suitable for passing to
 231 .Xr open 2 .
 232 As with
 233 .Fn cam_open_spec_device ,
 234 the
 235 .Fa device
 236 argument is optional.
 237 .Pp
 238 .Fn cam_open_pass
 239 takes as an argument the
 240 .Fa path
 241 of a
 242 .Xr pass 4
 243 device to open.
 244 No translation or lookup is performed, so the path passed
 245 in must be that of a CAM
 246 .Xr pass 4
 247 device.
 248 The
 249 .Fa flags
 250 should be flags suitable for passing to
 251 .Xr open 2 .
 252 The
 253 .Fa device
 254 argument, as with
 255 .Fn cam_open_spec_device
 256 and
 257 .Fn cam_open_btl ,
 258 should be
 259 .Dv NULL
 260 if the user wants the CAM library to allocate space for the
 261 .Va cam_device
 262 structure.
 263 .Pp
 264 .Fn cam_close_device
 265 frees the
 266 .Va cam_device
 267 structure allocated by one of the above
 268 .Xr open 2
 269 calls, and closes the file
 270 descriptor to the passthrough device.
 271 This routine should not be called if
 272 the user allocated space for the
 273 .Va cam_device
 274 structure.
 275 Instead, the user should call
 276 .Fn cam_close_spec_device .
 277 .Pp
 278 .Fn cam_close_spec_device
 279 merely closes the file descriptor opened in one of the
 280 .Xr open 2
 281 routines
 282 described above.
 283 This function should be called when the
 284 .Va cam_device
 285 structure was allocated by the caller, rather than the CAM library.
 286 .Pp
 287 .Fn cam_getccb
 288 allocates a CCB
 289 using
 290 .Xr malloc 3
 291 and sets fields in the CCB header using values from the
 292 .Va cam_device
 293 structure.
 294 .Pp
 295 .Fn cam_send_ccb
 296 sends the given
 297 .Va ccb
 298 to the
 299 .Fa device
 300 described in the
 301 .Va cam_device
 302 structure.
 303 .Pp
 304 .Fn cam_freeccb
 305 frees CCBs allocated by
 306 .Fn cam_getccb .
 307 If
 308 .Va ccb
 309 is
 310 .Dv NULL ,
 311 no action is taken.
 312 .Pp
 313 .Fn cam_path_string
 314 takes as arguments a
 315 .Va cam_device
 316 structure, and a string with length
 317 .Fa len .
 318 It creates a colon-terminated printing prefix string similar to the ones
 319 used by the kernel.
 320 e.g.: "(cd0:ahc1:0:4:0): ".
 321 .Fn cam_path_string
 322 will place at most
 323 .Fa len Ns \-1
 324 characters into
 325 .Ar str .
 326 The
 327 .Ar len Ns 'th
 328 character will be the terminating
 329 .Ql \e0 .
 330 .Pp
 331 .Fn cam_device_dup
 332 operates in a fashion similar to
 333 .Xr strdup 3 .
 334 It allocates space for a
 335 .Va cam_device
 336 structure and copies the contents of the passed-in
 337 .Fa device
 338 structure to the newly allocated structure.
 339 .Pp
 340 .Fn cam_device_copy
 341 copies the
 342 .Fa src
 343 structure to
 344 .Fa dst .
 345 .Pp
 346 .Fn cam_get_device
 347 takes a
 348 .Fa path
 349 argument containing a string with a device name followed by a unit number.
 350 It then breaks the string down into a device name and unit number, and
 351 passes them back in
 352 .Fa dev_name
 353 and
 354 .Fa unit ,
 355 respectively.
 356 .Fn cam_get_device
 357 can handle strings of the following forms, at least:
 358 .Pp
 359 .Bl -tag -width 1234 -compact
 360 .It /dev/foo1
 361 .It foo0
 362 .It nsa2
 363 .El
 364 .Pp
 365 .Fn cam_get_device
 366 is provided as a convenience function for applications that need to provide
 367 functionality similar to
 368 .Fn cam_open_device .
 369 .Sh RETURN VALUES
 370 .Fn cam_open_device ,
 371 .Fn cam_open_spec_device ,
 372 .Fn cam_open_btl ,
 373 and
 374 .Fn cam_open_pass
 375 return a pointer to a
 376 .Va cam_device
 377 structure, or
 378 .Dv NULL
 379 if there was an error.
 380 .Pp
 381 .Fn cam_getccb
 382 returns an allocated and partially initialized CCB, or
 383 .Dv NULL
 384 if allocation of the CCB failed.
 385 .Pp
 386 .Fn cam_send_ccb
 387 returns a value of -1 if an error occurred, and
 388 .Va errno
 389 is set to indicate the error.
 390 .Pp
 391 .Fn cam_path_string
 392 returns a filled printing prefix string as a convenience.
 393 This is the same
 394 .Fa str
 395 that is passed into
 396 .Fn cam_path_string .
 397 .Pp
 398 .Fn cam_device_dup
 399 returns a copy of the
 400 .Va device
 401 passed in, or
 402 .Dv NULL
 403 if an error occurred.
 404 .Pp
 405 .Fn cam_get_device
 406 returns 0 for success, and -1 to indicate failure.
 407 .Pp
 408 If an error is returned from one of the base CAM library functions
 409 described here, the reason for the error is generally printed in the global
 410 string
 411 .Va cam_errbuf
 412 which is
 413 .Dv CAM_ERRBUF_SIZE
 414 characters long.
 415 .Sh SEE ALSO
 416 .Xr cam_cdbparse 3 ,
 417 .Xr pass 4 ,
 418 .Xr camcontrol 8
 419 .Sh HISTORY
 420 The CAM library first appeared in
 421 .Fx 3.0 .
 422 .Sh AUTHORS
 423 .An Kenneth Merry Aq Mt ken@FreeBSD.org
 424 .Sh BUGS
 425 .Fn cam_open_device
 426 does not check to see if the
 427 .Fa path
 428 passed in is a symlink to something.
 429 It also does not check to see if the
 430 .Fa path
 431 passed in is an actual
 432 .Xr pass 4
 433 device.
 434 The former would be rather easy to implement, but the latter would
 435 require a definitive way to identify a device node as a
 436 .Xr pass 4
 437 device.
 438 .Pp
 439 Some of the functions are possibly misnamed or poorly named.