1 /* 2 * V4L2 subdev interface library 3 * 4 * Copyright (C) 2010-2014 Ideas on board SPRL 5 * 6 * Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> 7 * 8 * This program is free software; you can redistribute it and/or modify 9 * it under the terms of the GNU Lesser General Public License as published 10 * by the Free Software Foundation; either version 2.1 of the License, or 11 * (at your option) any later version. 12 * 13 * This program 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 16 * GNU Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public License 19 * along with this program. If not, see <http://www.gnu.org/licenses/>. 20 */ 21 22 #ifndef __SUBDEV_H__ 23 #define __SUBDEV_H__ 24 25 #include <linux/v4l2-subdev.h> 26 27 struct media_device; 28 struct media_entity; 29 30 /** 31 * @brief Open a sub-device. 32 * @param entity - sub-device media entity. 33 * 34 * Open the V4L2 subdev device node associated with @a entity. The file 35 * descriptor is stored in the media_entity structure. 36 * 37 * @return 0 on success, or a negative error code on failure. 38 */ 39 int v4l2_subdev_open(struct media_entity *entity); 40 41 /** 42 * @brief Close a sub-device. 43 * @param entity - sub-device media entity. 44 * 45 * Close the V4L2 subdev device node associated with the @a entity and opened by 46 * a previous call to v4l2_subdev_open() (either explicit or implicit). 47 */ 48 void v4l2_subdev_close(struct media_entity *entity); 49 50 /** 51 * @brief Retrieve the format on a pad. 52 * @param entity - subdev-device media entity. 53 * @param format - format to be filled. 54 * @param pad - pad number. 55 * @param stream - stream number. 56 * @param which - identifier of the format to get. 57 * 58 * Retrieve the current format on the @a entity @a pad and store it in the 59 * @a format structure. 60 * 61 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try format stored 62 * in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the current 63 * active format. 64 * 65 * @return 0 on success, or a negative error code on failure. 66 */ 67 int v4l2_subdev_get_format(struct media_entity *entity, 68 struct v4l2_mbus_framefmt *format, unsigned int pad, unsigned int stream, 69 enum v4l2_subdev_format_whence which); 70 71 /** 72 * @brief Set the format on a pad. 73 * @param entity - subdev-device media entity. 74 * @param format - format. 75 * @param pad - pad number. 76 * @param stream - stream number. 77 * @param which - identifier of the format to set. 78 * 79 * Set the format on the @a entity @a pad to @a format. The driver is allowed to 80 * modify the requested format, in which case @a format is updated with the 81 * modifications. 82 * 83 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try format stored in the 84 * file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the device with an 85 * active format. 86 * 87 * @return 0 on success, or a negative error code on failure. 88 */ 89 int v4l2_subdev_set_format(struct media_entity *entity, 90 struct v4l2_mbus_framefmt *format, unsigned int pad, 91 unsigned int stream, 92 enum v4l2_subdev_format_whence which); 93 94 /** 95 * @brief Retrieve a selection rectangle on a pad. 96 * @param entity - subdev-device media entity. 97 * @param r - rectangle to be filled. 98 * @param pad - pad number. 99 * @param stream - stream number. 100 * @param target - selection target 101 * @param which - identifier of the format to get. 102 * 103 * Retrieve the @a target selection rectangle on the @a entity @a pad 104 * and store it in the @a rect structure. 105 * 106 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try 107 * selection rectangle stored in the file handle, or 108 * V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the current active selection 109 * rectangle. 110 * 111 * @return 0 on success, or a negative error code on failure. 112 */ 113 int v4l2_subdev_get_selection(struct media_entity *entity, 114 struct v4l2_rect *rect, unsigned int pad, unsigned int stream, 115 unsigned int target, enum v4l2_subdev_format_whence which); 116 117 /** 118 * @brief Set a selection rectangle on a pad. 119 * @param entity - subdev-device media entity. 120 * @param rect - crop rectangle. 121 * @param pad - pad number. 122 * @param stream - stream number. 123 * @param target - selection target 124 * @param which - identifier of the format to set. 125 * 126 * Set the @a target selection rectangle on the @a entity @a pad to @a 127 * rect. The driver is allowed to modify the requested rectangle, in 128 * which case @a rect is updated with the modifications. 129 * 130 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try crop rectangle 131 * stored in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the 132 * device with an active crop rectangle. 133 * 134 * @return 0 on success, or a negative error code on failure. 135 */ 136 int v4l2_subdev_set_selection(struct media_entity *entity, 137 struct v4l2_rect *rect, unsigned int pad, unsigned int stream, 138 unsigned int target, enum v4l2_subdev_format_whence which); 139 140 /** 141 * @brief Get the routing table of a subdev media entity. 142 * @param entity - subdev-device media entity. 143 * @param routes - routes of the subdev. 144 * @param num_routes - number of routes. 145 * @param which - identifier of the routes to get. 146 * 147 * Get the routes of @a entity and return them in an allocated array in @a routes 148 * and the number of routes in @a num_routes. 149 * 150 * The caller is responsible for freeing the routes array after use. 151 * 152 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to get the routing table stored in 153 * the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to get the device's active 154 * routing table. 155 * 156 * @return 0 on success, or a negative error code on failure. 157 */ 158 int v4l2_subdev_get_routing(struct media_entity *entity, 159 struct v4l2_subdev_route **routes, 160 unsigned int *num_routes, 161 enum v4l2_subdev_format_whence which); 162 163 /** 164 * @brief Set the routing table of a subdev media entity. 165 * @param entity - subdev-device media entity. 166 * @param routes - routes of the subdev. 167 * @param num_routes - number of routes. 168 * @param which - identifier of the routes to set. 169 * 170 * Set the routes of @a entity. The routes are given in @a routes with the 171 * length of @a num_routes. 172 * 173 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the routing table stored in 174 * the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to set the device's active 175 * routing table. 176 * 177 * @return 0 on success, or a negative error code on failure. 178 */ 179 int v4l2_subdev_set_routing(struct media_entity *entity, 180 struct v4l2_subdev_route *route, 181 unsigned int num_routes, 182 enum v4l2_subdev_format_whence which); 183 184 /** 185 * @brief Query the digital video capabilities of a pad. 186 * @param entity - subdev-device media entity. 187 * @param cap - capabilities to be filled. 188 * 189 * Retrieve the digital video capabilities of the @a entity pad specified by 190 * @a cap.pad and store it in the @a cap structure. 191 * 192 * @return 0 on success, or a negative error code on failure. 193 */ 194 int v4l2_subdev_get_dv_timings_caps(struct media_entity *entity, 195 struct v4l2_dv_timings_cap *caps); 196 197 /** 198 * @brief Query the digital video timings of a sub-device 199 * @param entity - subdev-device media entity. 200 * @param timings timings to be filled. 201 * 202 * Retrieve the detected digital video timings for the currently selected input 203 * of @a entity and store them in the @a timings structure. 204 * 205 * @return 0 on success, or a negative error code on failure. 206 */ 207 int v4l2_subdev_query_dv_timings(struct media_entity *entity, 208 struct v4l2_dv_timings *timings); 209 210 /** 211 * @brief Get the current digital video timings of a sub-device 212 * @param entity - subdev-device media entity. 213 * @param timings timings to be filled. 214 * 215 * Retrieve the current digital video timings for the currently selected input 216 * of @a entity and store them in the @a timings structure. 217 * 218 * @return 0 on success, or a negative error code on failure. 219 */ 220 int v4l2_subdev_get_dv_timings(struct media_entity *entity, 221 struct v4l2_dv_timings *timings); 222 223 /** 224 * @brief Set the digital video timings of a sub-device 225 * @param entity - subdev-device media entity. 226 * @param timings timings to be set. 227 * 228 * Set the digital video timings of @a entity to @a timings. The driver is 229 * allowed to modify the requested format, in which case @a timings is updated 230 * with the modifications. 231 * 232 * @return 0 on success, or a negative error code on failure. 233 */ 234 int v4l2_subdev_set_dv_timings(struct media_entity *entity, 235 struct v4l2_dv_timings *timings); 236 237 /** 238 * @brief Retrieve the frame interval on a sub-device. 239 * @param entity - subdev-device media entity. 240 * @param interval - frame interval to be filled. 241 * @param pad - pad number. 242 * @param stream - stream number. 243 * @param which - identifier of the interval to get. 244 * 245 * Retrieve the current frame interval on subdev @a entity and store it in the 246 * @a interval structure. 247 * 248 * Frame interval retrieving is usually supported only on devices at the 249 * beginning of video pipelines, such as sensors. 250 * 251 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to get the frame interval stored 252 * in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to get the device's active 253 * frame interval. 254 * 255 * @return 0 on success, or a negative error code on failure. 256 */ 257 258 int v4l2_subdev_get_frame_interval(struct media_entity *entity, 259 struct v4l2_fract *interval, unsigned int pad, unsigned int stream, 260 enum v4l2_subdev_format_whence which); 261 262 /** 263 * @brief Set the frame interval on a sub-device. 264 * @param entity - subdev-device media entity. 265 * @param interval - frame interval. 266 * @param pad - pad number. 267 * @param stream - stream number. 268 * @param which - identifier of the interval to set. 269 * 270 * Set the frame interval on subdev @a entity to @a interval. The driver is 271 * allowed to modify the requested frame interval, in which case @a interval is 272 * updated with the modifications. 273 * 274 * Frame interval setting is usually supported only on devices at the beginning 275 * of video pipelines, such as sensors. 276 * 277 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the frame interval stored 278 * in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to set the device's active 279 * frame interval. 280 * 281 * @return 0 on success, or a negative error code on failure. 282 */ 283 int v4l2_subdev_set_frame_interval(struct media_entity *entity, 284 struct v4l2_fract *interval, unsigned int pad, unsigned int stream, 285 enum v4l2_subdev_format_whence which); 286 287 /** 288 * @brief Parse a string and apply format, crop and frame interval settings. 289 * @param media - media device. 290 * @param which - identifier of the parameters to set. 291 * @param p - input string 292 * @param endp - pointer to string p where parsing ended (return) 293 * 294 * Parse string @a p and apply format, crop and frame interval settings to a 295 * subdev pad specified in @a p. @a endp will be written a pointer where 296 * parsing of @a p ended. 297 * 298 * Format strings are separeted by commas (,). 299 * 300 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the parameters stored in the 301 * file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to set the device's active 302 * parameters. 303 * 304 * @return 0 on success, or a negative error code on failure. 305 */ 306 int v4l2_subdev_parse_setup_formats(struct media_device *media, 307 enum v4l2_subdev_format_whence which, 308 const char *p); 309 310 /** 311 * @brief Parse a string and apply route settings. 312 * @param media - media device. 313 * @param which - identifier of the routes to set. 314 * @param p - input string 315 * 316 * Parse string @a p and apply route settings to a subdev. 317 * 318 * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the routes stored in the 319 * file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to set the device's active routes. 320 * 321 * @return 0 on success, or a negative error code on failure. 322 */ 323 int v4l2_subdev_parse_setup_routes(struct media_device *media, 324 enum v4l2_subdev_format_whence which, 325 const char *p); 326 327 /** 328 * @brief Convert media bus pixel code to string. 329 * @param code - input string 330 * 331 * Convert media bus pixel code @a code to a human-readable string. 332 * 333 * @return A pointer to a string on success, NULL on failure. 334 */ 335 const char *v4l2_subdev_pixelcode_to_string(enum v4l2_mbus_pixelcode code); 336 337 /** 338 * @brief Parse string to media bus pixel code. 339 * @param string - nul terminalted string, textual media bus pixel code 340 * 341 * Parse human readable string @a string to an media bus pixel code. 342 * 343 * @return media bus pixelcode on success, -1 on failure. 344 */ 345 enum v4l2_mbus_pixelcode v4l2_subdev_string_to_pixelcode(const char *string); 346 347 /** 348 * @brief Convert a field order to string. 349 * @param field - field order 350 * 351 * Convert field order @a field to a human-readable string. 352 * 353 * @return A pointer to a string on success, NULL on failure. 354 */ 355 const char *v4l2_subdev_field_to_string(enum v4l2_field field); 356 357 /** 358 * @brief Parse string to field order. 359 * @param string - nul terminated string, textual media bus pixel code 360 * 361 * Parse human readable string @a string to field order. 362 * 363 * @return field order on success, -1 on failure. 364 */ 365 enum v4l2_field v4l2_subdev_string_to_field(const char *string); 366 367 /** 368 * @brief Convert a colorspace to string. 369 * @param colorspace - colorspace 370 * 371 * Convert colorspace @a colorspace to a human-readable string. 372 * 373 * @return A pointer to a string on success, NULL on failure. 374 */ 375 const char *v4l2_subdev_colorspace_to_string(enum v4l2_colorspace colorspace); 376 377 /** 378 * @brief Parse string to colorspace. 379 * @param string - nul terminated string, textual colorspace 380 * 381 * Parse human readable string @a string to colorspace. 382 * 383 * @return colorspace on success, -1 on failure. 384 */ 385 enum v4l2_colorspace v4l2_subdev_string_to_colorspace(const char *string); 386 387 /** 388 * @brief Convert a transfer function to string. 389 * @param xfer_func - transfer function 390 * 391 * Convert transfer function @a xfer_func to a human-readable string. 392 * 393 * @return A pointer to a string on success, NULL on failure. 394 */ 395 const char *v4l2_subdev_xfer_func_to_string(enum v4l2_xfer_func xfer_func); 396 397 /** 398 * @brief Parse string to transfer function. 399 * @param string - nul terminated string, textual transfer function 400 * 401 * Parse human readable string @a string to xfer_func. 402 * 403 * @return xfer_func on success, -1 on failure. 404 */ 405 enum v4l2_xfer_func v4l2_subdev_string_to_xfer_func(const char *string); 406 407 /** 408 * @brief Convert a YCbCr encoding to string. 409 * @param ycbcr_enc - YCbCr encoding 410 * 411 * Convert YCbCr encoding @a ycbcr_enc to a human-readable string. 412 * 413 * @return A pointer to a string on success, NULL on failure. 414 */ 415 const char *v4l2_subdev_ycbcr_encoding_to_string(enum v4l2_ycbcr_encoding ycbcr_enc); 416 417 /** 418 * @brief Parse string to YCbCr encoding. 419 * @param string - nul terminated string, textual YCbCr encoding 420 * 421 * Parse human readable string @a string to YCbCr encoding. 422 * 423 * @return ycbcr_enc on success, -1 on failure. 424 */ 425 enum v4l2_ycbcr_encoding v4l2_subdev_string_to_ycbcr_encoding(const char *string); 426 427 /** 428 * @brief Convert a quantization to string. 429 * @param quantization - quantization 430 * 431 * Convert quantization @a quantization to a human-readable string. 432 * 433 * @return A pointer to a string on success, NULL on failure. 434 */ 435 const char *v4l2_subdev_quantization_to_string(enum v4l2_quantization quantization); 436 437 /** 438 * @brief Parse string to quantization. 439 * @param string - nul terminated string, textual quantization 440 * 441 * Parse human readable string @a string to quantization. 442 * 443 * @return quantization on success, -1 on failure. 444 */ 445 enum v4l2_quantization v4l2_subdev_string_to_quantization(const char *string); 446 447 /** 448 * @brief Enumerate library supported media bus pixel codes. 449 * @param length - the number of the supported pixel codes 450 * 451 * Obtain pixel codes supported by libv4l2subdev. 452 * 453 * @return A pointer to the pixel code array 454 */ 455 const enum v4l2_mbus_pixelcode *v4l2_subdev_pixelcode_list( 456 unsigned int *length); 457 458 #endif 459