1/*
2 * Copyright 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ANDROID_TV_INPUT_INTERFACE_H
18#define ANDROID_TV_INPUT_INTERFACE_H
19
20#include <stdint.h>
21#include <sys/cdefs.h>
22#include <sys/types.h>
23
24#include <hardware/hardware.h>
25#include <system/audio.h>
26#include <cutils/native_handle.h>
27
28__BEGIN_DECLS
29
30/*
31 * Module versioning information for the TV input hardware module, based on
32 * tv_input_module_t.common.module_api_version.
33 *
34 * Version History:
35 *
36 * TV_INPUT_MODULE_API_VERSION_0_1:
37 * Initial TV input hardware module API.
38 *
39 */
40
41#define TV_INPUT_MODULE_API_VERSION_0_1  HARDWARE_MODULE_API_VERSION(0, 1)
42
43#define TV_INPUT_DEVICE_API_VERSION_0_1  HARDWARE_DEVICE_API_VERSION(0, 1)
44
45/*
46 * The id of this module
47 */
48#define TV_INPUT_HARDWARE_MODULE_ID "tv_input"
49
50#define TV_INPUT_DEFAULT_DEVICE "default"
51
52/*****************************************************************************/
53
54/*
55 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
56 * and the fields of this data structure must begin with hw_module_t
57 * followed by module specific information.
58 */
59typedef struct tv_input_module {
60    struct hw_module_t common;
61} tv_input_module_t;
62
63/*****************************************************************************/
64
65enum {
66    /* Generic hardware. */
67    TV_INPUT_TYPE_OTHER_HARDWARE = 1,
68    /* Tuner. (e.g. built-in terrestrial tuner) */
69    TV_INPUT_TYPE_TUNER = 2,
70    TV_INPUT_TYPE_COMPOSITE = 3,
71    TV_INPUT_TYPE_SVIDEO = 4,
72    TV_INPUT_TYPE_SCART = 5,
73    TV_INPUT_TYPE_COMPONENT = 6,
74    TV_INPUT_TYPE_VGA = 7,
75    TV_INPUT_TYPE_DVI = 8,
76    /* Physical HDMI port. (e.g. HDMI 1) */
77    TV_INPUT_TYPE_HDMI = 9,
78    TV_INPUT_TYPE_DISPLAY_PORT = 10,
79};
80typedef uint32_t tv_input_type_t;
81
82typedef struct tv_input_device_info {
83    /* Device ID */
84    int device_id;
85
86    /* Type of physical TV input. */
87    tv_input_type_t type;
88
89    union {
90        struct {
91            /* HDMI port ID number */
92            uint32_t port_id;
93        } hdmi;
94
95        /* TODO: add other type specific information. */
96
97        int32_t type_info_reserved[16];
98    };
99
100    /* TODO: Add capability if necessary. */
101
102    /*
103     * Audio info
104     *
105     * audio_type == AUDIO_DEVICE_NONE if this input has no audio.
106     */
107    audio_devices_t audio_type;
108    const char* audio_address;
109
110    int32_t reserved[16];
111} tv_input_device_info_t;
112
113/* See tv_input_event_t for more details. */
114enum {
115    /*
116     * Hardware notifies the framework that a device is available.
117     *
118     * Note that DEVICE_AVAILABLE and DEVICE_UNAVAILABLE events do not represent
119     * hotplug events (i.e. plugging cable into or out of the physical port).
120     * These events notify the framework whether the port is available or not.
121     * For a concrete example, when a user plugs in or pulls out the HDMI cable
122     * from a HDMI port, it does not generate DEVICE_AVAILABLE and/or
123     * DEVICE_UNAVAILABLE events. However, if a user inserts a pluggable USB
124     * tuner into the Android device, it will generate a DEVICE_AVAILABLE event
125     * and when the port is removed, it should generate a DEVICE_UNAVAILABLE
126     * event.
127     *
128     * For hotplug events, please see STREAM_CONFIGURATION_CHANGED for more
129     * details.
130     *
131     * HAL implementation should register devices by using this event when the
132     * device boots up. The framework will recognize device reported via this
133     * event only. In addition, the implementation could use this event to
134     * notify the framework that a removable TV input device (such as USB tuner
135     * as stated in the example above) is attached.
136     */
137    TV_INPUT_EVENT_DEVICE_AVAILABLE = 1,
138    /*
139     * Hardware notifies the framework that a device is unavailable.
140     *
141     * HAL implementation should generate this event when a device registered
142     * by TV_INPUT_EVENT_DEVICE_AVAILABLE is no longer available. For example,
143     * the event can indicate that a USB tuner is plugged out from the Android
144     * device.
145     *
146     * Note that this event is not for indicating cable plugged out of the port;
147     * for that purpose, the implementation should use
148     * STREAM_CONFIGURATION_CHANGED event. This event represents the port itself
149     * being no longer available.
150     */
151    TV_INPUT_EVENT_DEVICE_UNAVAILABLE = 2,
152    /*
153     * Stream configurations are changed. Client should regard all open streams
154     * at the specific device are closed, and should call
155     * get_stream_configurations() again, opening some of them if necessary.
156     *
157     * HAL implementation should generate this event when the available stream
158     * configurations change for any reason. A typical use case of this event
159     * would be to notify the framework that the input signal has changed
160     * resolution, or that the cable is plugged out so that the number of
161     * available streams is 0.
162     *
163     * The implementation may use this event to indicate hotplug status of the
164     * port. the framework regards input devices with no available streams as
165     * disconnected, so the implementation can generate this event with no
166     * available streams to indicate that this device is disconnected, and vice
167     * versa.
168     */
169    TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED = 3,
170    /*
171     * Hardware is done with capture request with the buffer. Client can assume
172     * ownership of the buffer again.
173     *
174     * HAL implementation should generate this event after request_capture() if
175     * it succeeded. The event shall have the buffer with the captured image.
176     */
177    TV_INPUT_EVENT_CAPTURE_SUCCEEDED = 4,
178    /*
179     * Hardware met a failure while processing a capture request or client
180     * canceled the request. Client can assume ownership of the buffer again.
181     *
182     * The event is similar to TV_INPUT_EVENT_CAPTURE_SUCCEEDED, but HAL
183     * implementation generates this event upon a failure to process
184     * request_capture(), or a request cancellation.
185     */
186    TV_INPUT_EVENT_CAPTURE_FAILED = 5,
187};
188typedef uint32_t tv_input_event_type_t;
189
190typedef struct tv_input_capture_result {
191    /* Device ID */
192    int device_id;
193
194    /* Stream ID */
195    int stream_id;
196
197    /* Sequence number of the request */
198    uint32_t seq;
199
200    /*
201     * The buffer passed to hardware in request_capture(). The content of
202     * buffer is undefined (although buffer itself is valid) for
203     * TV_INPUT_CAPTURE_FAILED event.
204     */
205    buffer_handle_t buffer;
206
207    /*
208     * Error code for the request. -ECANCELED if request is cancelled; other
209     * error codes are unknown errors.
210     */
211    int error_code;
212} tv_input_capture_result_t;
213
214typedef struct tv_input_event {
215    tv_input_event_type_t type;
216
217    union {
218        /*
219         * TV_INPUT_EVENT_DEVICE_AVAILABLE: all fields are relevant
220         * TV_INPUT_EVENT_DEVICE_UNAVAILABLE: only device_id is relevant
221         * TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED: only device_id is
222         *    relevant
223         */
224        tv_input_device_info_t device_info;
225        /*
226         * TV_INPUT_EVENT_CAPTURE_SUCCEEDED: error_code is not relevant
227         * TV_INPUT_EVENT_CAPTURE_FAILED: all fields are relevant
228         */
229        tv_input_capture_result_t capture_result;
230    };
231} tv_input_event_t;
232
233typedef struct tv_input_callback_ops {
234    /*
235     * event contains the type of the event and additional data if necessary.
236     * The event object is guaranteed to be valid only for the duration of the
237     * call.
238     *
239     * data is an object supplied at device initialization, opaque to the
240     * hardware.
241     */
242    void (*notify)(struct tv_input_device* dev,
243            tv_input_event_t* event, void* data);
244} tv_input_callback_ops_t;
245
246enum {
247    TV_STREAM_TYPE_INDEPENDENT_VIDEO_SOURCE = 1,
248    TV_STREAM_TYPE_BUFFER_PRODUCER = 2,
249};
250typedef uint32_t tv_stream_type_t;
251
252typedef struct tv_stream_config {
253    /*
254     * ID number of the stream. This value is used to identify the whole stream
255     * configuration.
256     */
257    int stream_id;
258
259    /* Type of the stream */
260    tv_stream_type_t type;
261
262    /* Max width/height of the stream. */
263    uint32_t max_video_width;
264    uint32_t max_video_height;
265} tv_stream_config_t;
266
267typedef struct buffer_producer_stream {
268    /*
269     * IN/OUT: Width / height of the stream. Client may request for specific
270     * size but hardware may change it. Client must allocate buffers with
271     * specified width and height.
272     */
273    uint32_t width;
274    uint32_t height;
275
276    /* OUT: Client must set this usage when allocating buffer. */
277    uint32_t usage;
278
279    /* OUT: Client must allocate a buffer with this format. */
280    uint32_t format;
281} buffer_producer_stream_t;
282
283typedef struct tv_stream {
284    /* IN: ID in the stream configuration */
285    int stream_id;
286
287    /* OUT: Type of the stream (for convenience) */
288    tv_stream_type_t type;
289
290    /* Data associated with the stream for client's use */
291    union {
292        /* OUT: A native handle describing the sideband stream source */
293        native_handle_t* sideband_stream_source_handle;
294
295        /* IN/OUT: Details are in buffer_producer_stream_t */
296        buffer_producer_stream_t buffer_producer;
297    };
298} tv_stream_t;
299
300/*
301 * Every device data structure must begin with hw_device_t
302 * followed by module specific public methods and attributes.
303 */
304typedef struct tv_input_device {
305    struct hw_device_t common;
306
307    /*
308     * initialize:
309     *
310     * Provide callbacks to the device and start operation. At first, no device
311     * is available and after initialize() completes, currently available
312     * devices including static devices should notify via callback.
313     *
314     * Framework owns callbacks object.
315     *
316     * data is a framework-owned object which would be sent back to the
317     * framework for each callback notifications.
318     *
319     * Return 0 on success.
320     */
321    int (*initialize)(struct tv_input_device* dev,
322            const tv_input_callback_ops_t* callback, void* data);
323
324    /*
325     * get_stream_configurations:
326     *
327     * Get stream configurations for a specific device. An input device may have
328     * multiple configurations.
329     *
330     * The configs object is guaranteed to be valid only until the next call to
331     * get_stream_configurations() or STREAM_CONFIGURATIONS_CHANGED event.
332     *
333     * Return 0 on success.
334     */
335    int (*get_stream_configurations)(const struct tv_input_device* dev,
336            int device_id, int* num_configurations,
337            const tv_stream_config_t** configs);
338
339    /*
340     * open_stream:
341     *
342     * Open a stream with given stream ID. Caller owns stream object, and the
343     * populated data is only valid until the stream is closed.
344     *
345     * Return 0 on success; -EBUSY if the client should close other streams to
346     * open the stream; -EEXIST if the stream with the given ID is already open;
347     * -EINVAL if device_id and/or stream_id are invalid; other non-zero value
348     * denotes unknown error.
349     */
350    int (*open_stream)(struct tv_input_device* dev, int device_id,
351            tv_stream_t* stream);
352
353    /*
354     * close_stream:
355     *
356     * Close a stream to a device. data in tv_stream_t* object associated with
357     * the stream_id is obsolete once this call finishes.
358     *
359     * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if
360     * device_id and/or stream_id are invalid.
361     */
362    int (*close_stream)(struct tv_input_device* dev, int device_id,
363            int stream_id);
364
365    /*
366     * request_capture:
367     *
368     * Request buffer capture for a stream. This is only valid for buffer
369     * producer streams. The buffer should be created with size, format and
370     * usage specified in the stream. Framework provides seq in an
371     * increasing sequence per each stream. Hardware should provide the picture
372     * in a chronological order according to seq. For example, if two
373     * requests are being processed at the same time, the request with the
374     * smaller seq should get an earlier frame.
375     *
376     * The framework releases the ownership of the buffer upon calling this
377     * function. When the buffer is filled, hardware notifies the framework
378     * via TV_INPUT_EVENT_CAPTURE_FINISHED callback, and the ownership is
379     * transferred back to framework at that time.
380     *
381     * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if
382     * device_id and/or stream_id are invalid; -EWOULDBLOCK if HAL cannot take
383     * additional requests until it releases a buffer.
384     */
385    int (*request_capture)(struct tv_input_device* dev, int device_id,
386            int stream_id, buffer_handle_t buffer, uint32_t seq);
387
388    /*
389     * cancel_capture:
390     *
391     * Cancel an ongoing capture. Hardware should release the buffer as soon as
392     * possible via TV_INPUT_EVENT_CAPTURE_FAILED callback.
393     *
394     * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if
395     * device_id, stream_id, and/or seq are invalid.
396     */
397    int (*cancel_capture)(struct tv_input_device* dev, int device_id,
398            int stream_id, uint32_t seq);
399
400    void* reserved[16];
401} tv_input_device_t;
402
403__END_DECLS
404
405#endif  // ANDROID_TV_INPUT_INTERFACE_H
406