1page.title=Error and stream handling
2@jd:body
3
4<!--
5    Copyright 2013 The Android Open Source Project
6
7    Licensed under the Apache License, Version 2.0 (the "License");
8    you may not use this file except in compliance with the License.
9    You may obtain a copy of the License at
10
11        http://www.apache.org/licenses/LICENSE-2.0
12
13    Unless required by applicable law or agreed to in writing, software
14    distributed under the License is distributed on an "AS IS" BASIS,
15    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16    See the License for the specific language governing permissions and
17    limitations under the License.
18-->
19<div id="qv-wrapper">
20  <div id="qv">
21    <h2>In this document</h2>
22    <ol id="auto-toc">
23    </ol>
24  </div>
25</div>
26
27<h2 id="error-mgmt">Error management</h2>
28<p>Camera HAL device ops functions that have a return value will all return -ENODEV
29  / NULL in case of a serious error. This means the device cannot continue
30  operation, and must be closed by the framework. Once this error is returned by
31  some method, or if notify() is called with ERROR_DEVICE, only the close() method
32  can be called successfully. All other methods will return -ENODEV / NULL.<br/>
33  If a device op is called in the wrong sequence, for example if the framework
34  calls configure_streams() is called before initialize(), the device must return
35  -ENOSYS from the call, and do nothing.<br/>
36  Transient errors in image capture must be reported through notify() as follows:</p>
37<ul>
38  <li>The failure of an entire capture to occur must be reported by the HAL by
39    calling notify() with ERROR_REQUEST. Individual errors for the result metadata
40    or the output buffers must not be reported in this case.</li>
41  <li>If the metadata for a capture cannot be produced, but some image buffers were
42    filled, the HAL must call notify() with ERROR_RESULT.</li>
43  <li>If an output image buffer could not be filled, but either the metadata was
44    produced or some other buffers were filled, the HAL must call notify() with
45    ERROR_BUFFER for each failed buffer.</li>
46</ul>
47<p>In each of these transient failure cases, the HAL must still call
48  process_capture_result, with valid output buffer_handle_t. If the result
49  metadata could not be produced, it should be NULL. If some buffers could not be
50  filled, their sync fences must be set to the error state.<br/>
51  Invalid input arguments result in -EINVAL from the appropriate methods. In that
52  case, the framework must act as if that call had never been made.</p>
53<h2 id="stream-mgmt">Stream management</h2>
54<h3 id="configure_streams">configure_streams</h3>
55<p>Reset the HAL camera device processing pipeline and set up new input and output
56  streams. This call replaces any existing stream configuration with the streams
57  defined in the stream_list. This method will be called at least once after
58  initialize() before a request is submitted with process_capture_request().<br/>
59  The stream_list must contain at least one output-capable stream, and may not
60  contain more than one input-capable stream.<br/>
61  The stream_list may contain streams that are also in the currently-active set of
62  streams (from the previous call to configure_stream()). These streams will
63  already have valid values for usage, maxbuffers, and the private pointer. If
64  such a stream has already had its buffers registered, register_stream_buffers()
65  will not be called again for the stream, and buffers from the stream can be
66  immediately included in input requests.<br/>
67  If the HAL needs to change the stream configuration for an existing stream due
68  to the new configuration, it may rewrite the values of usage and/or maxbuffers
69  during the configure call. The framework will detect such a change, and will
70  then reallocate the stream buffers, and call register_stream_buffers() again
71  before using buffers from that stream in a request.<br/>
72  If a currently-active stream is not included in stream_list, the HAL may safely
73  remove any references to that stream. It will not be reused in a later
74  configure() call by the framework, and all the gralloc buffers for it will be
75  freed after the configure_streams() call returns.<br/>
76  The stream_list structure is owned by the framework, and may not be accessed
77  once this call completes. The address of an individual camera3streamt
78  structure will remain valid for access by the HAL until the end of the first
79  configure_stream() call which no longer includes that camera3streamt in the
80  stream_list argument. The HAL may not change values in the stream structure
81  outside of the private pointer, except for the usage and maxbuffers members
82  during the configure_streams() call itself.<br/>
83  If the stream is new, the usage, maxbuffer, and private pointer fields of the
84  stream structure will all be set to 0. The HAL device must set these fields
85  before the configure_streams() call returns. These fields are then used by the
86  framework and the platform gralloc module to allocate the gralloc buffers for
87  each stream.<br/>
88  Before such a new stream can have its buffers included in a capture request, the
89  framework will call register_stream_buffers() with that stream. However, the
90  framework is not required to register buffers for _all streams before
91  submitting a request. This allows for quick startup of (for example) a preview
92  stream, with allocation for other streams happening later or concurrently.</p>
93<h4><strong>Preconditions</strong></h4>
94<p>The framework will only call this method when no captures are being processed.
95  That is, all results have been returned to the framework, and all in-flight
96  input and output buffers have been returned and their release sync fences have
97  been signaled by the HAL. The framework will not submit new requests for capture
98  while the configure_streams() call is underway.</p>
99<h4><strong>Postconditions</strong></h4>
100<p>The HAL device must configure itself to provide maximum possible output frame
101  rate given the sizes and formats of the output streams, as documented in the
102  camera device's static metadata.</p>
103<h4><strong>Performance expectations</strong></h4>
104<p>This call is expected to be heavyweight and possibly take several hundred
105  milliseconds to complete, since it may require resetting and reconfiguring the
106  image sensor and the camera processing pipeline. Nevertheless, the HAL device
107  should attempt to minimize the reconfiguration delay to minimize the
108  user-visible pauses during application operational mode changes (such as
109  switching from still capture to video recording).</p>
110<h4><strong>Return values</strong></h4>
111<ul>
112  <li>0: On successful stream configuration</li>
113  <li>undefined</li>
114  <li>-EINVAL: If the requested stream configuration is invalid. Some examples of
115    invalid stream configurations include:
116    <ul>
117      <li>Including more than 1 input-capable stream (INPUT or BIDIRECTIONAL)</li>
118      <li>Not including any output-capable streams (OUTPUT or BIDIRECTIONAL)</li>
119      <li>Including streams with unsupported formats, or an unsupported size for
120        that format.</li>
121      <li>Including too many output streams of a certain format.</li>
122      <li>Note that the framework submitting an invalid stream configuration is not
123        normal operation, since stream configurations are checked before
124        configure. An invalid configuration means that a bug exists in the
125        framework code, or there is a mismatch between the HAL's static metadata
126        and the requirements on streams.</li>
127    </ul>
128  </li>
129  <li>-ENODEV: If there has been a fatal error and the device is no longer
130    operational. Only close() can be called successfully by the framework after
131    this error is returned.</li>
132</ul>
133<h3 id="register-stream">register_stream_buffers</h3>
134<p>Register buffers for a given stream with the HAL device. This method is called
135  by the framework after a new stream is defined by configure_streams, and before
136  buffers from that stream are included in a capture request. If the same stream
137  is listed in a subsequent configure_streams() call, register_stream_buffers will
138  not be called again for that stream.<br/>
139  The framework does not need to register buffers for all configured streams
140  before it submits the first capture request. This allows quick startup for
141  preview (or similar use cases) while other streams are still being allocated.<br/>
142  This method is intended to allow the HAL device to map or otherwise prepare the
143  buffers for later use. The buffers passed in will already be locked for use. At
144  the end of the call, all the buffers must be ready to be returned to the stream.
145  The bufferset argument is only valid for the duration of this call.<br/>
146  If the stream format was set to HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, the
147  camera HAL should inspect the passed-in buffers here to determine any
148  platform-private pixel format information.</p>
149<h4><strong>Return values</strong></h4>
150<ul>
151  <li>0: On successful registration of the new stream buffers</li>
152  <li>-EINVAL: If the streambufferset does not refer to a valid active stream, or
153    if the buffers array is invalid.</li>
154  <li>-ENOMEM: If there was a failure in registering the buffers. The framework must
155    consider all the stream buffers to be unregistered, and can try to register
156    again later.</li>
157  <li>-ENODEV: If there is a fatal error, and the device is no longer operational.
158    Only close() can be called successfully by the framework after this error is
159    returned.</li>
160</ul>
161