xref: /freebsd/lib/libcam/cam.3 (revision fe6060f10f634930ff71b7c50291ddc610da2475)
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 November 23, 2020
31.Dt CAM 3
32.Os
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	uint32_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	uint32_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	uint32_t	sim_unit_number; /* Controller unit number */
165	uint32_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	uint16_t	pd_type;	 /* type of peripheral device */
170	struct scsi_inquiry_data inq_data;  /* SCSI Inquiry data */
171	uint8_t		serial_num[252]; /* device serial number */
172	uint8_t		serial_num_len;  /* length of the serial number */
173	uint8_t		sync_period;	 /* Negotiated sync period */
174	uint8_t		sync_offset;	 /* Negotiated sync offset */
175	uint8_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.Pp
194.Fn cam_open_spec_device
195opens the
196.Xr pass 4
197device that corresponds to the device name and unit number passed in.
198The
199.Ar flags
200should be flags suitable for passing to
201.Xr open 2 .
202The
203.Ar device
204argument is optional.
205The user may supply pre-allocated space for the
206.Va cam_device
207structure.
208If the
209.Ar device
210argument is
211.Dv NULL ,
212.Fn cam_open_spec_device
213will allocate space for the
214.Va cam_device
215structure using
216.Xr malloc 3 .
217.Pp
218.Fn cam_open_btl
219is similar to
220.Fn cam_open_spec_device ,
221except that it takes a SCSI bus,
222target and logical unit instead of a device name and unit number as
223arguments.
224The
225.Va path_id
226argument is the CAM equivalent of a SCSI bus number.
227It represents the logical bus number in the system.
228The
229.Ar flags
230should be flags suitable for passing to
231.Xr open 2 .
232As with
233.Fn cam_open_spec_device ,
234the
235.Fa device
236argument is optional.
237.Pp
238.Fn cam_open_pass
239takes as an argument the
240.Fa path
241of a
242.Xr pass 4
243device to open.
244No translation or lookup is performed, so the path passed
245in must be that of a CAM
246.Xr pass 4
247device.
248The
249.Fa flags
250should be flags suitable for passing to
251.Xr open 2 .
252The
253.Fa device
254argument, as with
255.Fn cam_open_spec_device
256and
257.Fn cam_open_btl ,
258should be
259.Dv NULL
260if the user wants the CAM library to allocate space for the
261.Va cam_device
262structure.
263.Pp
264.Fn cam_close_device
265frees the
266.Va cam_device
267structure allocated by one of the above
268.Xr open 2
269calls, and closes the file
270descriptor to the passthrough device.
271This routine should not be called if
272the user allocated space for the
273.Va cam_device
274structure.
275Instead, the user should call
276.Fn cam_close_spec_device .
277.Pp
278.Fn cam_close_spec_device
279merely closes the file descriptor opened in one of the
280.Xr open 2
281routines
282described above.
283This function should be called when the
284.Va cam_device
285structure was allocated by the caller, rather than the CAM library.
286.Pp
287.Fn cam_getccb
288allocates a prezeroed CCB
289using
290.Xr calloc 3
291and sets fields in the CCB header using values from the
292.Va cam_device
293structure.
294.Pp
295.Fn cam_send_ccb
296sends the given
297.Va ccb
298to the
299.Fa device
300described in the
301.Va cam_device
302structure.
303.Pp
304.Fn cam_freeccb
305frees CCBs allocated by
306.Fn cam_getccb .
307If
308.Va ccb
309is
310.Dv NULL ,
311no action is taken.
312.Pp
313.Fn cam_path_string
314takes as arguments a
315.Va cam_device
316structure, and a string with length
317.Fa len .
318It creates a colon-terminated printing prefix string similar to the ones
319used by the kernel.
320e.g.: "(cd0:ahc1:0:4:0): ".
321.Fn cam_path_string
322will place at most
323.Fa len Ns \-1
324characters into
325.Ar str .
326The
327.Ar len Ns 'th
328character will be the terminating
329.Ql \e0 .
330.Pp
331.Fn cam_device_dup
332operates in a fashion similar to
333.Xr strdup 3 .
334It allocates space for a
335.Va cam_device
336structure and copies the contents of the passed-in
337.Fa device
338structure to the newly allocated structure.
339.Pp
340.Fn cam_device_copy
341copies the
342.Fa src
343structure to
344.Fa dst .
345.Pp
346.Fn cam_get_device
347takes a
348.Fa path
349argument containing a string with a device name followed by a unit number.
350It then breaks the string down into a device name and unit number, and
351passes them back in
352.Fa dev_name
353and
354.Fa unit ,
355respectively.
356.Fn cam_get_device
357can handle strings of the following forms, at least:
358.Pp
359.Bl -tag -width 1234 -compact
360.It /dev/foo1
361.It foo0
362.It nsa2
363.El
364.Pp
365.Fn cam_get_device
366is provided as a convenience function for applications that need to provide
367functionality similar to
368.Fn cam_open_device .
369.Sh RETURN VALUES
370.Fn cam_open_device ,
371.Fn cam_open_spec_device ,
372.Fn cam_open_btl ,
373and
374.Fn cam_open_pass
375return a pointer to a
376.Va cam_device
377structure, or
378.Dv NULL
379if there was an error.
380.Pp
381.Fn cam_getccb
382returns an allocated and partially initialized CCB, or
383.Dv NULL
384if allocation of the CCB failed.
385.Pp
386.Fn cam_send_ccb
387returns a value of -1 if an error occurred, and
388.Va errno
389is set to indicate the error.
390.Pp
391.Fn cam_path_string
392returns a filled printing prefix string as a convenience.
393This is the same
394.Fa str
395that is passed into
396.Fn cam_path_string .
397.Pp
398.Fn cam_device_dup
399returns a copy of the
400.Va device
401passed in, or
402.Dv NULL
403if an error occurred.
404.Pp
405.Fn cam_get_device
406returns 0 for success, and -1 to indicate failure.
407.Pp
408If an error is returned from one of the base CAM library functions
409described here, the reason for the error is generally printed in the global
410string
411.Va cam_errbuf
412which is
413.Dv CAM_ERRBUF_SIZE
414characters long.
415.Sh SEE ALSO
416.Xr cam_cdbparse 3 ,
417.Xr pass 4 ,
418.Xr camcontrol 8
419.Sh HISTORY
420The CAM library first appeared in
421.Fx 3.0 .
422.Sh AUTHORS
423.An Kenneth Merry Aq Mt ken@FreeBSD.org
424.Sh BUGS
425.Fn cam_open_device
426does not check to see if the
427.Fa path
428passed in is a symlink to something.
429It also does not check to see if the
430.Fa path
431passed in is an actual
432.Xr pass 4
433device.
434The former would be rather easy to implement, but the latter would
435require a definitive way to identify a device node as a
436.Xr pass 4
437device.
438.Pp
439Some of the functions are possibly misnamed or poorly named.
440