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