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.\" $Id: cam.3,v 1.1 1998/10/14 06:20:36 ken Exp $ 29.\" 30.Dd October 10, 1998 31.Os FreeBSD 3.0 32.Dt CAM 3 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 SYNOPSIS 49.Fd #include <stdio.h> 50.Fd #include <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 121The CAM library consists of a number of functions designed to aid in 122programming with the CAM subsystem. This man page covers the basic set of 123library functions. More functions are documented in the man pages listed 124below. 125.Pp 126Many of the CAM library functions use the 127.Va cam_device 128structure: 129.Bd -literal 130struct cam_device { 131 char device_path[MAXPATHLEN+1];/* 132 * Pathname of the 133 * device given by the 134 * user. This may be 135 * null if the user 136 * states the device 137 * name and unit number 138 * separately. 139 */ 140 char given_dev_name[DEV_IDLEN+1];/* 141 * Device name given by 142 * the user. 143 */ 144 u_int32_t given_unit_number; /* 145 * Unit number given by 146 * the user. 147 */ 148 char device_name[DEV_IDLEN+1];/* 149 * Name of the device, 150 * e.g. 'pass' 151 */ 152 u_int32_t dev_unit_num; /* Unit number of the passthrough 153 * device associated with this 154 * particular device. 155 */ 156 157 char sim_name[SIM_IDLEN+1];/* 158 * Controller name, e.g.'ahc' 159 */ 160 u_int32_t sim_unit_number; /* Controller unit number */ 161 u_int32_t bus_id; /* Controller bus number */ 162 lun_id_t target_lun; /* Logical Unit Number */ 163 target_id_t target_id; /* Target ID */ 164 path_id_t path_id; /* System SCSI bus number */ 165 u_int16_t pd_type; /* type of peripheral device */ 166 struct scsi_inquiry_data inq_data; /* SCSI Inquiry data */ 167 u_int8_t serial_num[252]; /* device serial number */ 168 u_int8_t serial_num_len; /* length of the serial number */ 169 u_int8_t sync_period; /* Negotiated sync period */ 170 u_int8_t sync_offset; /* Negotiated sync offset */ 171 u_int8_t bus_width; /* Negotiated bus width */ 172 int fd; /* file descriptor for device */ 173}; 174.Ed 175.Pp 176.Fn cam_open_device 177takes as arguments a string describing the device it is to open, and 178.Ar flags 179suitable for passing to 180.Xr open 2 . 181The "path" passed in may actually be most any type of string that contains 182a device name and unit number to be opened. The string will be parsed by 183.Fn cam_get_device 184into a device name and unit number. Once the device name and unit number 185are determined, a lookup is performed to determine the passthrough device 186that corresponds to the given device. 187.Fn cam_open_device 188is rather simple to use, but it isn't really suitable for general use 189because its behavior isn't necessarily deterministic. Programmers writing 190new applications should make the extra effort to use one of the other open 191routines documented below. 192.Pp 193.Fn cam_open_spec_device 194opens the 195.Xr pass 4 196device that corresponds to the device name and unit number passed in. The 197.Ar flags 198should be flags suitable for passing to 199.Xr open 2 . 200The 201.Ar device 202argument is optional. The user may supply pre-allocated space for the 203.Va cam_device 204structure. If the 205.Ar device 206argument is 207.Va NULL , 208.Fn cam_open_spec_device 209will allocate space for the 210.Va cam_device 211structure using 212.Xr malloc 3 . 213.Pp 214.Fn cam_open_btl 215is similar to 216.Fn cam_open_spec_device , 217except that it takes a 218.Tn SCSI 219bus, target and logical unit instead of a device name and unit number as 220arguments. The 221.Va path_id 222argument is the CAM equivalent of a 223.Tn SCSI 224bus number. It represents the logical bus number in the system. The 225.Ar flags 226should be flags suitable for passing to 227.Xr open 2 . 228As with 229.Fn cam_open_spec_device , 230the 231.Fa device 232argument is optional. 233.Pp 234.Fn cam_open_pass 235takes as an argument the 236.Fa path 237of a 238.Xr pass 4 239device to open. No translation or lookup is performed, so the path passed 240in must be that of a CAM 241.Xr pass 4 242device. The 243.Fa flags 244should be flags suitable for passing to 245.Xr open 2 . 246The 247.Fa device 248argument, as with 249.Fn cam_open_spec_device 250and 251.Fn cam_open_btl , 252should be NULL if the user wants the CAM library to allocate space for the 253.Va cam_device 254structure. 255.Fn cam_close_device 256frees the 257.Va cam_device 258structure allocated by one of the above open() calls, and closes the file 259descriptor to the passthrough device. This routine should not be called if 260the user allocated space for the 261.Va cam_device 262structure. Instead, the user should call 263.Fn cam_close_spec_device . 264.Pp 265.Fn cam_close_spec_device 266merely closes the file descriptor opened in one of the open() routines 267described above. This function should be called when the 268.Va cam_device 269structure was allocated by the caller, rather than the CAM library. 270.Pp 271.Fn cam_getccb 272allocates a CCB (see 273.Xr ccb 4 ) 274using 275.Xr malloc 3 276and sets fields in the CCB header using values from the 277.Va cam_device 278structure. 279.Pp 280.Fn cam_send_ccb 281sends the given 282.Va ccb 283to the 284.Fa device 285described in the 286.Va cam_device 287structure. 288.Pp 289.Fn cam_freeccb 290frees CCBs allocated by 291.Fn cam_getccb . 292.Pp 293.Fn cam_path_string 294takes as arguments a 295.Va cam_device 296structure, and a string with length 297.Fa len . 298It creates a colon-terminated printing prefix string similar to the ones 299used by the kernel. e.g.: "(cd0:ahc1:0:4:0): ". 300.Fn cam_path_string 301will place at most 302.Fa len Ns \-1 303characters into 304.Ar str . 305The 306.Ar len Ns 'th 307character will be the terminating 308.Ql \e0 . 309.Pp 310.Fn cam_device_dup 311operates in a fashion similar to 312.Xr strdup 3 . 313It allocates space for a 314.Va cam_device 315structure and copies the contents of the passed-in 316.Fa device 317structure to the newly allocated structure. 318.Pp 319.Fn cam_device_copy 320copies the 321.Fa src 322structure to 323.Fa dst . 324.Pp 325.Fn cam_get_device 326takes a 327.Fa path 328argument containing a string with a device name followed by a unit number. 329It then breaks the string down into a device name and unit number, and 330passes them back in 331.Fa dev_name 332and 333.Fa unit , 334respectively. 335.Fn cam_get_device 336can handle strings of the following forms, at least: 337.Pp 338.Bl -tag -width 1234 -compact 339.It /dev/foo0a 340.It /dev/rfoo0a 341.It /dev/rfoo1s2c 342.It foo0 343.It foo0a 344.It rfoo0 345.It rfoo0a 346.It nrfoo0 347.El 348.Pp 349.Fn cam_get_device 350is provided as a convenience function for applications that need to provide 351functionality similar to 352.Fn cam_open_device . 353Programmers are encouraged to use more deterministic methods of obtaining 354device names and unit numbers if possible. 355.Sh RETURN VALUES 356.Fn cam_open_device , 357.Fn cam_open_spec_device , 358.Fn cam_open_btl , 359and 360.Fn cam_open_pass 361return a pointer to a 362.Va cam_device 363structure, or NULL if there was an error. 364.Pp 365.Fn cam_getccb 366returns an allocated and partially initialized CCB, or NULL if allocation 367of the CCB failed. 368.Pp 369.Fn cam_send_ccb 370returns a value of -1 if an error occured, and 371.Va errno 372is set to indicate the error. 373.Pp 374.Fn cam_path_string 375returns a filled printing prefix string as a convenience. This is the same 376.Fa str 377that is passed into 378.Fn cam_path_string . 379.Pp 380.Fn cam_device_dup 381returns a copy of the 382.Va device 383passed in, or NULL if an error occurred. 384.Pp 385.Fn cam_get_device 386returns 0 for success, and -1 to indicate failure. 387.Pp 388If an error is returned from one of the base CAM library functions 389described here, the reason for the error is generally printed in the global 390string 391.Va cam_errbuf 392which is 393.Dv CAM_ERRBUF_SIZE 394characters long. 395.Sh SEE ALSO 396.Xr cam_cdbparse 3 , 397.Xr pass 4 , 398.Xr camcontrol 8 , 399.Sh HISTORY 400The CAM library first appeared in 401.Fx 3.0 . 402.Sh AUTHORS 403.An Kenneth Merry Aq ken@FreeBSD.ORG 404.Sh BUGS 405.Fn cam_open_device 406doesn't check to see if the 407.Fa path 408passed in is a symlink to something. It also doesn't check to see if the 409.Fa path 410passed in is an actual 411.Xr pass 4 412device. The former would be rather easy to implement, but the latter would 413require a definitive way to identify a device node as a 414.Xr pass 4 415device. 416.Pp 417Some of the functions are possibly mis-named or poorly named. 418