1/*
2 * 1394-Based Digital Camera Control Library
3 *
4 * Functions for the manual allocations of ISO ressources.
5 *
6 * Written by David Moore <dcm@acm.org>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library; if not, write to the Free Software
20 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 */
22
23#ifndef __DC1394_ISO_H__
24#define __DC1394_ISO_H__
25
26/*! \file dc1394/iso.h
27 \brief Functions to manually manage the ISO resources (channels and bandwidth)
28 \author Damien Douxchamps: coding
29 \author Peter Antoniac: documentation maintainer
30
31 More details soon
32*/
33
34#include <dc1394/log.h>
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * dc1394_iso_set_persist
42 * @param camera A camera handle.
43 *
44 * Calling this function will cause isochronous channel and bandwidth
45 * allocations to persist beyond the lifetime of this dc1394camera_t
46 * instance. Normally (when this function is not called), any allocations
47 * would be automatically released upon freeing this camera or a
48 * premature shutdown of the application (if possible). For this function
49 * to be used, it must be called prior to any allocations or an error will
50 * be returned.
51 *
52 * @return \a DC1394_SUCCESS if the operation succeeded.
53 * \a DC1394_FUNCTION_NOT_SUPPORTED if the current platform/driver does not
54 * allow persistent allocations.
55 */
56dc1394error_t dc1394_iso_set_persist (dc1394camera_t * camera);
57
58/**
59 * dc1394_iso_allocate_channel:
60 * @param camera A camera handle.
61 * @param channels_allowed A bitmask of acceptable channels for the allocation.
62 * The LSB corresponds to channel 0 and the MSB corresponds to channel
63 * 63. Only channels whose bit is set will be considered for the allocation.
64 * If \a channels_allowed = 0, the complete set of channels supported by
65 * this camera will be considered for the allocation.
66 * @param channel The allocated channel number is returned here.
67 *
68 * Allocates an isochronous channel. This
69 * function may be called multiple times, each time allocating an additional
70 * channel. The channel is automatically re-allocated if there is a bus
71 * reset. The channel is automatically released when this dc1394camera_t
72 * is freed or if the application shuts down prematurely. If the channel
73 * needs to persist beyond the lifetime of this application, call
74 * \a dc1394_iso_set_persist() first. Note that this function does _not_
75 * automatically program @a camera to use the allocated channel for isochronous
76 * streaming. You must do that manually using \a dc1394_video_set_iso_channel().
77 *
78 * @return \a DC1394_SUCCESS if the operation succeeded. The allocated
79 * channel is stored in \a channel. \a DC1394_FUNCTION_NOT_SUPPORTED if the
80 * current driver/platform does not allow channel allocation.
81 * \a DC1394_NO_ISO_CHANNEL if none of the requested channels are available.
82 */
83dc1394error_t dc1394_iso_allocate_channel (dc1394camera_t * camera,
84 uint64_t channels_allowed, int * channel);
85
86/**
87 * dc1394_iso_release_channel:
88 * @param camera A camera handle.
89 * @param channel The channel number to release.
90 *
91 * Releases a previously allocated channel. It is acceptable to release
92 * channels that were allocated by a different process or host. If
93 * attempting to release a channel that is already released, the function
94 * will succeed.
95 *
96 * @return \a DC1394_SUCCESS if the operation succeeded.
97 * \a DC1394_FUNCTION_NOT_SUPPORTED if the current driver/platform does not
98 * allow channel release.
99 */
100dc1394error_t dc1394_iso_release_channel (dc1394camera_t * camera,
101 int channel);
102
103/**
104 * dc1394_iso_allocate_bandwidth:
105 * @param camera A camera handle.
106 * @param bandwidth_units The number of isochronous bandwidth units to allocate.
107 *
108 * Allocates isochronous bandwidth. This functions allocates bandwidth
109 * _in addition_ to any previous allocations. It may be called multiple
110 * times. The bandwidth is automatically re-allocated if there is a bus
111 * reset. The bandwidth is automatically released if this camera is freed
112 * or the application shuts down prematurely. If the bandwidth needs to
113 * persist beyond the lifetime of this application, call
114 * \a dc1394_iso_set_persist() first.
115 *
116 * @return \a DC1394_SUCCESS if the operation succeeded.
117 * \a DC1394_FUNCTION_NOT_SUPPORTED if the current driver/platform does not
118 * allow bandwidth allocation. \a DC1394_NO_BANDWIDTH if there is not enough
119 * available bandwidth to support the allocation. In this case,
120 * no bandwidth is allocated.
121 */
122dc1394error_t dc1394_iso_allocate_bandwidth (dc1394camera_t * camera,
123 int bandwidth_units);
124
125/**
126 * dc1394_iso_release_bandwidth:
127 * @param camera A camera handle.
128 * @param bandwidth_units The number of isochronous bandwidth units to free.
129 *
130 * Releases previously allocated isochronous bandwidth. Each \a dc1394camera_t
131 * keeps track of a running total of bandwidth that has been allocated.
132 * Released bandwidth is subtracted from this total for the sake of
133 * automatic re-allocation and automatic release on shutdown. It is also
134 * acceptable for a camera to release more bandwidth than it has allocated
135 * (to clean up for another process for example). In this case, the
136 * running total of bandwidth is not affected. It is acceptable to
137 * release more bandwidth than is allocated in total for the bus. In this
138 * case, all bandwidth is released and the function succeeds.
139 *
140 * @return \a DC1394_SUCCESS if the operation succeeded.
141 * \a DC1394_FUNCTION_NOT_SUPPORTED if the current driver/platform does not
142 * allow bandwidth release.
143 */
144dc1394error_t dc1394_iso_release_bandwidth (dc1394camera_t * camera,
145 int bandwidth_units);
146
147/**
148 * dc1394_iso_release_all:
149 * @param camera A camera handle.
150 *
151 * Releases all channels and bandwidth that have been previously allocated
152 * for this dc1394camera_t. Note that this information can only be tracked
153 * per process, and there is no knowledge of allocations for this camera
154 * by previous processes. To release resources in such a case, the manual
155 * release functions \a dc1394_iso_release_channel() and
156 * \a dc1394_iso_release_bandwidth() must be used.
157 *
158 * @return \a DC1394_SUCCESS if the operation succeeded. \a DC1394_FAILURE
159 * if some resources were not able to be released.
160 */
161dc1394error_t dc1394_iso_release_all (dc1394camera_t * camera);
162
163#ifdef __cplusplus
164}
165#endif
166
167#endif
168

source code of include/dc1394/iso.h