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 */ 59 typedef struct tv_input_module { 60 struct hw_module_t common; 61 } tv_input_module_t; 62 63 /*****************************************************************************/ 64 65 enum { 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 }; 80 typedef uint32_t tv_input_type_t; 81 82 typedef 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. */ 114 enum { 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 }; 188 typedef uint32_t tv_input_event_type_t; 189 190 typedef 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 214 typedef 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 233 typedef 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 246 enum { 247 TV_STREAM_TYPE_INDEPENDENT_VIDEO_SOURCE = 1, 248 TV_STREAM_TYPE_BUFFER_PRODUCER = 2, 249 }; 250 typedef uint32_t tv_stream_type_t; 251 252 typedef 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 267 typedef 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 283 typedef 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 */ 304 typedef 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