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