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