xref: /freebsd/lib/libcam/cam.3 (revision 7f3dea244c40159a41ab22da77a434d7c5b5e85a)
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 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
273using
274.Xr malloc 3
275and sets fields in the CCB header using values from the
276.Va cam_device
277structure.
278.Pp
279.Fn cam_send_ccb
280sends the given
281.Va ccb
282to the
283.Fa device
284described in the
285.Va cam_device
286structure.
287.Pp
288.Fn cam_freeccb
289frees CCBs allocated by
290.Fn cam_getccb .
291.Pp
292.Fn cam_path_string
293takes as arguments a
294.Va cam_device
295structure, and a string with length
296.Fa len .
297It creates a colon-terminated printing prefix string similar to the ones
298used by the kernel.  e.g.:  "(cd0:ahc1:0:4:0): ".
299.Fn cam_path_string
300will place at most
301.Fa len Ns \-1
302characters into
303.Ar str .
304The
305.Ar len Ns 'th
306character will be the terminating
307.Ql \e0 .
308.Pp
309.Fn cam_device_dup
310operates in a fashion similar to
311.Xr strdup 3 .
312It allocates space for a
313.Va cam_device
314structure and copies the contents of the passed-in
315.Fa device
316structure to the newly allocated structure.
317.Pp
318.Fn cam_device_copy
319copies the
320.Fa src
321structure to
322.Fa dst .
323.Pp
324.Fn cam_get_device
325takes a
326.Fa path
327argument containing a string with a device name followed by a unit number.
328It then breaks the string down into a device name and unit number, and
329passes them back in
330.Fa dev_name
331and
332.Fa unit ,
333respectively.
334.Fn cam_get_device
335can handle strings of the following forms, at least:
336.Pp
337.Bl -tag -width 1234 -compact
338.It /dev/foo0a
339.It /dev/rfoo0a
340.It /dev/rfoo1s2c
341.It foo0
342.It foo0a
343.It rfoo0
344.It rfoo0a
345.It nrfoo0
346.El
347.Pp
348.Fn cam_get_device
349is provided as a convenience function for applications that need to provide
350functionality similar to
351.Fn cam_open_device .
352Programmers are encouraged to use more deterministic methods of obtaining
353device 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 ,
358and
359.Fn cam_open_pass
360return a pointer to a
361.Va cam_device
362structure, or NULL if there was an error.
363.Pp
364.Fn cam_getccb
365returns an allocated and partially initialized CCB, or NULL if allocation
366of the CCB failed.
367.Pp
368.Fn cam_send_ccb
369returns a value of -1 if an error occured, and
370.Va errno
371is set to indicate the error.
372.Pp
373.Fn cam_path_string
374returns a filled printing prefix string as a convenience.  This is the same
375.Fa str
376that is passed into
377.Fn cam_path_string .
378.Pp
379.Fn cam_device_dup
380returns a copy of the
381.Va device
382passed in, or NULL if an error occurred.
383.Pp
384.Fn cam_get_device
385returns 0 for success, and -1 to indicate failure.
386.Pp
387If an error is returned from one of the base CAM library functions
388described here, the reason for the error is generally printed in the global
389string
390.Va cam_errbuf
391which is
392.Dv CAM_ERRBUF_SIZE
393characters long.
394.Sh SEE ALSO
395.Xr cam_cdbparse 3 ,
396.Xr pass 4 ,
397.Xr camcontrol 8
398.Sh HISTORY
399The 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
405doesn't check to see if the
406.Fa path
407passed in is a symlink to something.  It also doesn't check to see if the
408.Fa path
409passed in is an actual
410.Xr pass 4
411device.  The former would be rather easy to implement, but the latter would
412require a definitive way to identify a device node as a
413.Xr pass 4
414device.
415.Pp
416Some of the functions are possibly mis-named or poorly named.
417