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: src/lib/libcam/cam.3,v 1.5.2.6 2001/12/17 10:08:28 ru Exp $
  29 .\" $DragonFly: src/lib/libcam/cam.3,v 1.3 2007/05/13 18:33:56 swildner Exp $
  30 .\"
  31 .Dd October 10, 1998
  32 .Os
  33 .Dt CAM 3
  34 .Sh NAME
  35 .Nm cam_open_device ,
  36 .Nm cam_open_spec_device ,
  37 .Nm cam_open_btl ,
  38 .Nm cam_open_pass ,
  39 .Nm cam_close_device ,
  40 .Nm cam_close_spec_device ,
  41 .Nm cam_getccb ,
  42 .Nm cam_send_ccb ,
  43 .Nm cam_freeccb ,
  44 .Nm cam_path_string ,
  45 .Nm cam_device_dup ,
  46 .Nm cam_device_copy ,
  47 .Nm cam_get_device
  48 .Nd CAM user library
  49 .Sh LIBRARY
  50 .Lb libcam
  51 .Sh SYNOPSIS
  52 .In stdio.h
  53 .In camlib.h
  54 .Ft struct cam_device *
  55 .Fo cam_open_device
  56 .Fa "const char *path"
  57 .Fa "int flags"
  58 .Fc
  59 .Ft struct cam_device *
  60 .Fo cam_open_spec_device
  61 .Fa "const char *dev_name"
  62 .Fa "int unit"
  63 .Fa "int flags"
  64 .Fa "struct cam_device *device"
  65 .Fc
  66 .Ft struct cam_device *
  67 .Fo cam_open_btl
  68 .Fa "path_id_t path_id"
  69 .Fa "target_id_t target_id"
  70 .Fa "lun_id_t target_lun"
  71 .Fa "int flags"
  72 .Fa "struct cam_device *device"
  73 .Fc
  74 .Ft struct cam_device *
  75 .Fo cam_open_pass
  76 .Fa "const char *path"
  77 .Fa "int flags"
  78 .Fa "struct cam_device *device"
  79 .Fc
  80 .Ft void
  81 .Fo cam_close_device
  82 .Fa "struct cam_device *dev"
  83 .Fc
  84 .Ft void
  85 .Fo cam_close_spec_device
  86 .Fa "struct cam_device *dev"
  87 .Fc
  88 .Ft union ccb *
  89 .Fo cam_getccb
  90 .Fa "struct cam_device *dev"
  91 .Fc
  92 .Ft int
  93 .Fo cam_send_ccb
  94 .Fa "struct cam_device *device"
  95 .Fa "union ccb *ccb"
  96 .Fc
  97 .Ft void
  98 .Fo cam_freeccb
  99 .Fa "union ccb *ccb"
 100 .Fc
 101 .Ft char *
 102 .Fo cam_path_string
 103 .Fa "struct cam_device *dev"
 104 .Fa "char *str"
 105 .Fa "int len"
 106 .Fc
 107 .Ft struct cam_device *
 108 .Fo cam_device_dup
 109 .Fa "struct cam_device *device"
 110 .Fc
 111 .Ft void
 112 .Fo cam_device_copy
 113 .Fa "struct cam_device *src"
 114 .Fa "struct cam_device *dst"
 115 .Fc
 116 .Ft int
 117 .Fo cam_get_device
 118 .Fa "const char *path"
 119 .Fa "char *dev_name"
 120 .Fa "int devnamelen"
 121 .Fa "int *unit"
 122 .Fc
 123 .Sh DESCRIPTION
 124 The CAM library consists of a number of functions designed to aid in
 125 programming with the CAM subsystem.  This man page covers the basic set of
 126 library functions.  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         u_int32_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         u_int32_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         u_int32_t       sim_unit_number; /* Controller unit number */
 164         u_int32_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         u_int16_t       pd_type;         /* type of peripheral device */
 169         struct scsi_inquiry_data inq_data;  /* SCSI Inquiry data */
 170         u_int8_t        serial_num[252]; /* device serial number */
 171         u_int8_t        serial_num_len;  /* length of the serial number */
 172         u_int8_t        sync_period;     /* Negotiated sync period */
 173         u_int8_t        sync_offset;     /* Negotiated sync offset */
 174         u_int8_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.  The string will be parsed by
 186 .Fn cam_get_device
 187 into a device name and unit number.  Once the device name and unit number
 188 are determined, a lookup is performed to determine the passthrough device
 189 that corresponds to the given device.
 190 .Fn cam_open_device
 191 is rather simple to use, but it isn't really suitable for general use
 192 because its behavior isn't necessarily deterministic.  Programmers writing
 193 new applications should make the extra effort to use one of the other open
 194 routines documented below.
 195 .Pp
 196 .Fn cam_open_spec_device
 197 opens the
 198 .Xr pass 4
 199 device that corresponds to the device name and unit number passed in.  The
 200 .Ar flags
 201 should be flags suitable for passing to
 202 .Xr open 2 .
 203 The
 204 .Ar device
 205 argument is optional.  The user may supply pre-allocated space for the
 206 .Va cam_device
 207 structure.  If the
 208 .Ar device
 209 argument is
 210 .Va 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
 221 .Tn SCSI
 222 bus, target and logical unit instead of a device name and unit number as
 223 arguments.  The
 224 .Va path_id
 225 argument is the CAM equivalent of a
 226 .Tn SCSI
 227 bus number.  It represents the logical bus number in the system.  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.  No translation or lookup is performed, so the path passed
 243 in must be that of a CAM
 244 .Xr pass 4
 245 device.  The
 246 .Fa flags
 247 should be flags suitable for passing to
 248 .Xr open 2 .
 249 The
 250 .Fa device
 251 argument, as with
 252 .Fn cam_open_spec_device
 253 and
 254 .Fn cam_open_btl ,
 255 should be NULL if the user wants the CAM library to allocate space for the
 256 .Va cam_device
 257 structure.
 258 .Fn cam_close_device
 259 frees the
 260 .Va cam_device
 261 structure allocated by one of the above open() calls, and closes the file
 262 descriptor to the passthrough device.  This routine should not be called if
 263 the user allocated space for the
 264 .Va cam_device
 265 structure.  Instead, the user should call
 266 .Fn cam_close_spec_device .
 267 .Pp
 268 .Fn cam_close_spec_device
 269 merely closes the file descriptor opened in one of the open() routines
 270 described above.  This function should be called when the
 271 .Va cam_device
 272 structure was allocated by the caller, rather than the CAM library.
 273 .Pp
 274 .Fn cam_getccb
 275 allocates a CCB
 276 using
 277 .Xr malloc 3
 278 and sets fields in the CCB header using values from the
 279 .Va cam_device
 280 structure.
 281 .Pp
 282 .Fn cam_send_ccb
 283 sends the given
 284 .Va ccb
 285 to the
 286 .Fa device
 287 described in the
 288 .Va cam_device
 289 structure.
 290 .Pp
 291 .Fn cam_freeccb
 292 frees CCBs allocated by
 293 .Fn cam_getccb .
 294 .Pp
 295 .Fn cam_path_string
 296 takes as arguments a
 297 .Va cam_device
 298 structure, and a string with length
 299 .Fa len .
 300 It creates a colon-terminated printing prefix string similar to the ones
 301 used by the kernel.  e.g.:  "(cd0:ahc1:0:4:0): ".
 302 .Fn cam_path_string
 303 will place at most
 304 .Fa len Ns \-1
 305 characters into
 306 .Ar str .
 307 The
 308 .Ar len Ns 'th
 309 character will be the terminating
 310 .Ql \e0 .
 311 .Pp
 312 .Fn cam_device_dup
 313 operates in a fashion similar to
 314 .Xr strdup 3 .
 315 It allocates space for a
 316 .Va cam_device
 317 structure and copies the contents of the passed-in
 318 .Fa device
 319 structure to the newly allocated structure.
 320 .Pp
 321 .Fn cam_device_copy
 322 copies the
 323 .Fa src
 324 structure to
 325 .Fa dst .
 326 .Pp
 327 .Fn cam_get_device
 328 takes a
 329 .Fa path
 330 argument containing a string with a device name followed by a unit number.
 331 It then breaks the string down into a device name and unit number, and
 332 passes them back in
 333 .Fa dev_name
 334 and
 335 .Fa unit ,
 336 respectively.
 337 .Fn cam_get_device
 338 can handle strings of the following forms, at least:
 339 .Pp
 340 .Bl -tag -width 1234 -compact
 341 .It /dev/foo0a
 342 .It /dev/foo1s2c
 343 .It foo0
 344 .It foo0a
 345 .It nfoo0
 346 .El
 347 .Pp
 348 .Fn cam_get_device
 349 is provided as a convenience function for applications that need to provide
 350 functionality similar to
 351 .Fn cam_open_device .
 352 Programmers are encouraged to use more deterministic methods of obtaining
 353 device names and unit numbers if possible.
 354 .Sh RETURN VALUES
 355 .Fn cam_open_device ,
 356 .Fn cam_open_spec_device ,
 357 .Fn cam_open_btl ,
 358 and
 359 .Fn cam_open_pass
 360 return a pointer to a
 361 .Va cam_device
 362 structure, or NULL if there was an error.
 363 .Pp
 364 .Fn cam_getccb
 365 returns an allocated and partially initialized CCB, or NULL if allocation
 366 of the CCB failed.
 367 .Pp
 368 .Fn cam_send_ccb
 369 returns a value of -1 if an error occurred, and
 370 .Va errno
 371 is set to indicate the error.
 372 .Pp
 373 .Fn cam_path_string
 374 returns a filled printing prefix string as a convenience.  This is the same
 375 .Fa str
 376 that is passed into
 377 .Fn cam_path_string .
 378 .Pp
 379 .Fn cam_device_dup
 380 returns a copy of the
 381 .Va device
 382 passed in, or NULL if an error occurred.
 383 .Pp
 384 .Fn cam_get_device
 385 returns 0 for success, and -1 to indicate failure.
 386 .Pp
 387 If an error is returned from one of the base CAM library functions
 388 described here, the reason for the error is generally printed in the global
 389 string
 390 .Va cam_errbuf
 391 which is
 392 .Dv CAM_ERRBUF_SIZE
 393 characters long.
 394 .Sh SEE ALSO
 395 .Xr cam_cdbparse 3 ,
 396 .Xr pass 4 ,
 397 .Xr camcontrol 8
 398 .Sh HISTORY
 399 The CAM library first appeared in
 400 .Fx 3.0 .
 401 .Sh AUTHORS
 402 .An Kenneth Merry Aq ken@FreeBSD.org
 403 .Sh BUGS
 404 .Fn cam_open_device
 405 doesn't check to see if the
 406 .Fa path
 407 passed in is a symlink to something.  It also doesn't check to see if the
 408 .Fa path
 409 passed in is an actual
 410 .Xr pass 4
 411 device.  The former would be rather easy to implement, but the latter would
 412 require a definitive way to identify a device node as a
 413 .Xr pass 4
 414 device.
 415 .Pp
 416 Some of the functions are possibly mis-named or poorly named.