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 <system/window.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 enum { 114 /* 115 * Hardware notifies the framework that a device is available. 116 */ 117 TV_INPUT_EVENT_DEVICE_AVAILABLE = 1, 118 /* 119 * Hardware notifies the framework that a device is unavailable. 120 */ 121 TV_INPUT_EVENT_DEVICE_UNAVAILABLE = 2, 122 /* 123 * Stream configurations are changed. Client should regard all open streams 124 * at the specific device are closed, and should call 125 * get_stream_configurations() again, opening some of them if necessary. 126 */ 127 TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED = 3, 128 /* 129 * Hardware is done with capture request with the buffer. Client can assume 130 * ownership of the buffer again. 131 */ 132 TV_INPUT_EVENT_CAPTURE_SUCCEEDED = 4, 133 /* 134 * Hardware met a failure while processing a capture request or client 135 * canceled the request. Client can assume ownership of the buffer again. 136 */ 137 TV_INPUT_EVENT_CAPTURE_FAILED = 5, 138 }; 139 typedef uint32_t tv_input_event_type_t; 140 141 typedef struct tv_input_capture_result { 142 /* Device ID */ 143 int device_id; 144 145 /* Stream ID */ 146 int stream_id; 147 148 /* Sequence number of the request */ 149 uint32_t seq; 150 151 /* 152 * The buffer passed to hardware in request_capture(). The content of 153 * buffer is undefined (although buffer itself is valid) for 154 * TV_INPUT_CAPTURE_FAILED event. 155 */ 156 buffer_handle_t buffer; 157 158 /* 159 * Error code for the request. -ECANCELED if request is cancelled; other 160 * error codes are unknown errors. 161 */ 162 int error_code; 163 } tv_input_capture_result_t; 164 165 typedef struct tv_input_event { 166 tv_input_event_type_t type; 167 168 union { 169 /* 170 * TV_INPUT_EVENT_DEVICE_AVAILABLE: all fields are relevant 171 * TV_INPUT_EVENT_DEVICE_UNAVAILABLE: only device_id is relevant 172 * TV_INPUT_EVENT_STREAM_CONFIGURATIONS_CHANGED: only device_id is 173 * relevant 174 */ 175 tv_input_device_info_t device_info; 176 /* 177 * TV_INPUT_EVENT_CAPTURE_SUCCEEDED: error_code is not relevant 178 * TV_INPUT_EVENT_CAPTURE_FAILED: all fields are relevant 179 */ 180 tv_input_capture_result_t capture_result; 181 }; 182 } tv_input_event_t; 183 184 typedef struct tv_input_callback_ops { 185 /* 186 * event contains the type of the event and additional data if necessary. 187 * The event object is guaranteed to be valid only for the duration of the 188 * call. 189 * 190 * data is an object supplied at device initialization, opaque to the 191 * hardware. 192 */ 193 void (*notify)(struct tv_input_device* dev, 194 tv_input_event_t* event, void* data); 195 } tv_input_callback_ops_t; 196 197 enum { 198 TV_STREAM_TYPE_INDEPENDENT_VIDEO_SOURCE = 1, 199 TV_STREAM_TYPE_BUFFER_PRODUCER = 2, 200 }; 201 typedef uint32_t tv_stream_type_t; 202 203 typedef struct tv_stream_config { 204 /* 205 * ID number of the stream. This value is used to identify the whole stream 206 * configuration. 207 */ 208 int stream_id; 209 210 /* Type of the stream */ 211 tv_stream_type_t type; 212 213 /* Max width/height of the stream. */ 214 uint32_t max_video_width; 215 uint32_t max_video_height; 216 } tv_stream_config_t; 217 218 typedef struct buffer_producer_stream { 219 /* 220 * IN/OUT: Width / height of the stream. Client may request for specific 221 * size but hardware may change it. Client must allocate buffers with 222 * specified width and height. 223 */ 224 uint32_t width; 225 uint32_t height; 226 227 /* OUT: Client must set this usage when allocating buffer. */ 228 uint32_t usage; 229 230 /* OUT: Client must allocate a buffer with this format. */ 231 uint32_t format; 232 } buffer_producer_stream_t; 233 234 typedef struct tv_stream { 235 /* IN: ID in the stream configuration */ 236 int stream_id; 237 238 /* OUT: Type of the stream (for convenience) */ 239 tv_stream_type_t type; 240 241 /* Data associated with the stream for client's use */ 242 union { 243 /* OUT: A native handle describing the sideband stream source */ 244 native_handle_t* sideband_stream_source_handle; 245 246 /* IN/OUT: Details are in buffer_producer_stream_t */ 247 buffer_producer_stream_t buffer_producer; 248 }; 249 } tv_stream_t; 250 251 /* 252 * Every device data structure must begin with hw_device_t 253 * followed by module specific public methods and attributes. 254 */ 255 typedef struct tv_input_device { 256 struct hw_device_t common; 257 258 /* 259 * initialize: 260 * 261 * Provide callbacks to the device and start operation. At first, no device 262 * is available and after initialize() completes, currently available 263 * devices including static devices should notify via callback. 264 * 265 * Framework owns callbacks object. 266 * 267 * data is a framework-owned object which would be sent back to the 268 * framework for each callback notifications. 269 * 270 * Return 0 on success. 271 */ 272 int (*initialize)(struct tv_input_device* dev, 273 const tv_input_callback_ops_t* callback, void* data); 274 275 /* 276 * get_stream_configurations: 277 * 278 * Get stream configurations for a specific device. An input device may have 279 * multiple configurations. 280 * 281 * The configs object is guaranteed to be valid only until the next call to 282 * get_stream_configurations() or STREAM_CONFIGURATIONS_CHANGED event. 283 * 284 * Return 0 on success. 285 */ 286 int (*get_stream_configurations)(const struct tv_input_device* dev, 287 int device_id, int* num_configurations, 288 const tv_stream_config_t** configs); 289 290 /* 291 * open_stream: 292 * 293 * Open a stream with given stream ID. Caller owns stream object, and the 294 * populated data is only valid until the stream is closed. 295 * 296 * Return 0 on success; -EBUSY if the client should close other streams to 297 * open the stream; -EEXIST if the stream with the given ID is already open; 298 * -EINVAL if device_id and/or stream_id are invalid; other non-zero value 299 * denotes unknown error. 300 */ 301 int (*open_stream)(struct tv_input_device* dev, int device_id, 302 tv_stream_t* stream); 303 304 /* 305 * close_stream: 306 * 307 * Close a stream to a device. data in tv_stream_t* object associated with 308 * the stream_id is obsolete once this call finishes. 309 * 310 * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if 311 * device_id and/or stream_id are invalid. 312 */ 313 int (*close_stream)(struct tv_input_device* dev, int device_id, 314 int stream_id); 315 316 /* 317 * request_capture: 318 * 319 * Request buffer capture for a stream. This is only valid for buffer 320 * producer streams. The buffer should be created with size, format and 321 * usage specified in the stream. Framework provides seq in an 322 * increasing sequence per each stream. Hardware should provide the picture 323 * in a chronological order according to seq. For example, if two 324 * requests are being processed at the same time, the request with the 325 * smaller seq should get an earlier frame. 326 * 327 * The framework releases the ownership of the buffer upon calling this 328 * function. When the buffer is filled, hardware notifies the framework 329 * via TV_INPUT_EVENT_CAPTURE_FINISHED callback, and the ownership is 330 * transferred back to framework at that time. 331 * 332 * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if 333 * device_id and/or stream_id are invalid; -EWOULDBLOCK if HAL cannot take 334 * additional requests until it releases a buffer. 335 */ 336 int (*request_capture)(struct tv_input_device* dev, int device_id, 337 int stream_id, buffer_handle_t buffer, uint32_t seq); 338 339 /* 340 * cancel_capture: 341 * 342 * Cancel an ongoing capture. Hardware should release the buffer as soon as 343 * possible via TV_INPUT_EVENT_CAPTURE_FAILED callback. 344 * 345 * Return 0 on success; -ENOENT if the stream is not open; -EINVAL if 346 * device_id, stream_id, and/or seq are invalid. 347 */ 348 int (*cancel_capture)(struct tv_input_device* dev, int device_id, 349 int stream_id, uint32_t seq); 350 351 void* reserved[16]; 352 } tv_input_device_t; 353 354 __END_DECLS 355 356 #endif // ANDROID_TV_INPUT_INTERFACE_H 357