src/v4l2subdev.h

   1 /*
   2  * V4L2 subdev interface library
   3  *
   4  * Copyright (C) 2010-2011 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_entity;
  28
  29 /**
  30  * @brief Open a sub-device.
  31  * @param entity - sub-device media entity.
  32  *
  33  * Open the V4L2 subdev device node associated with @a entity. The file
  34  * descriptor is stored in the media_entity structure.
  35  *
  36  * @return 0 on success, or a negative error code on failure.
  37  */
  38 int v4l2_subdev_open(struct media_entity *entity);
  39
  40 /**
  41  * @brief Close a sub-device.
  42  * @param entity - sub-device media entity.
  43  *
  44  * Close the V4L2 subdev device node associated with the @a entity and opened by
  45  * a previous call to v4l2_subdev_open() (either explicit or implicit).
  46  */
  47 void v4l2_subdev_close(struct media_entity *entity);
  48
  49 /**
  50  * @brief Retrieve the format on a pad.
  51  * @param entity - subdev-device media entity.
  52  * @param format - format to be filled.
  53  * @param pad - pad number.
  54  * @param which - identifier of the format to get.
  55  *
  56  * Retrieve the current format on the @a entity @a pad and store it in the
  57  * @a format structure.
  58  *
  59  * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try format stored
  60  * in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the current
  61  * active format.
  62  *
  63  * @return 0 on success, or a negative error code on failure.
  64  */
  65 int v4l2_subdev_get_format(struct media_entity *entity,
  66         struct v4l2_mbus_framefmt *format, unsigned int pad,
  67         enum v4l2_subdev_format_whence which);
  68
  69 /**
  70  * @brief Set the format on a pad.
  71  * @param entity - subdev-device media entity.
  72  * @param format - format.
  73  * @param pad - pad number.
  74  * @param which - identifier of the format to set.
  75  *
  76  * Set the format on the @a entity @a pad to @a format. The driver is allowed to
  77  * modify the requested format, in which case @a format is updated with the
  78  * modifications.
  79  *
  80  * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try format stored in the
  81  * file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the device with an
  82  * active format.
  83  *
  84  * @return 0 on success, or a negative error code on failure.
  85  */
  86 int v4l2_subdev_set_format(struct media_entity *entity,
  87         struct v4l2_mbus_framefmt *format, unsigned int pad,
  88         enum v4l2_subdev_format_whence which);
  89
  90 /**
  91  * @brief Retrieve a selection rectangle on a pad.
  92  * @param entity - subdev-device media entity.
  93  * @param r - rectangle to be filled.
  94  * @param pad - pad number.
  95  * @param target - selection target
  96  * @param which - identifier of the format to get.
  97  *
  98  * Retrieve the @a target selection rectangle on the @a entity @a pad
  99  * and store it in the @a rect structure.
 100  *
 101  * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try
 102  * selection rectangle stored in the file handle, or
 103  * V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the current active selection
 104  * rectangle.
 105  *
 106  * @return 0 on success, or a negative error code on failure.
 107  */
 108 int v4l2_subdev_get_selection(struct media_entity *entity,
 109         struct v4l2_rect *rect, unsigned int pad, unsigned int target,
 110         enum v4l2_subdev_format_whence which);
 111
 112 /**
 113  * @brief Set a selection rectangle on a pad.
 114  * @param entity - subdev-device media entity.
 115  * @param rect - crop rectangle.
 116  * @param pad - pad number.
 117  * @param target - selection target
 118  * @param which - identifier of the format to set.
 119  *
 120  * Set the @a target selection rectangle on the @a entity @a pad to @a
 121  * rect. The driver is allowed to modify the requested rectangle, in
 122  * which case @a rect is updated with the modifications.
 123  *
 124  * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try crop rectangle
 125  * stored in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the
 126  * device with an active crop rectangle.
 127  *
 128  * @return 0 on success, or a negative error code on failure.
 129  */
 130 int v4l2_subdev_set_selection(struct media_entity *entity,
 131         struct v4l2_rect *rect, unsigned int pad, unsigned int target,
 132         enum v4l2_subdev_format_whence which);
 133
 134 /**
 135  * @brief Retrieve the frame interval on a sub-device.
 136  * @param entity - subdev-device media entity.
 137  * @param interval - frame interval to be filled.
 138  *
 139  * Retrieve the current frame interval on subdev @a entity and store it in the
 140  * @a interval structure.
 141  *
 142  * Frame interval retrieving is usually supported only on devices at the
 143  * beginning of video pipelines, such as sensors.
 144  *
 145  * @return 0 on success, or a negative error code on failure.
 146  */
 147
 148 int v4l2_subdev_get_frame_interval(struct media_entity *entity,
 149         struct v4l2_fract *interval);
 150
 151 /**
 152  * @brief Set the frame interval on a sub-device.
 153  * @param entity - subdev-device media entity.
 154  * @param interval - frame interval.
 155  *
 156  * Set the frame interval on subdev @a entity to @a interval. The driver is
 157  * allowed to modify the requested frame interval, in which case @a interval is
 158  * updated with the modifications.
 159  *
 160  * Frame interval setting is usually supported only on devices at the beginning
 161  * of video pipelines, such as sensors.
 162  *
 163  * @return 0 on success, or a negative error code on failure.
 164  */
 165 int v4l2_subdev_set_frame_interval(struct media_entity *entity,
 166         struct v4l2_fract *interval);
 167
 168 /**
 169  * @brief Parse a string and apply format, crop and frame interval settings.
 170  * @param media - media device.
 171  * @param p - input string
 172  * @param endp - pointer to string p where parsing ended (return)
 173  *
 174  * Parse string @a p and apply format, crop and frame interval settings to a
 175  * subdev pad specified in @a p. @a endp will be written a pointer where
 176  * parsing of @a p ended.
 177  *
 178  * Format strings are separeted by commas (,).
 179  *
 180  * @return 0 on success, or a negative error code on failure.
 181  */
 182 int v4l2_subdev_parse_setup_formats(struct media_device *media, const char *p);
 183
 184 /**
 185  * @brief Convert media bus pixel code to string.
 186  * @param code - input string
 187  *
 188  * Convert media bus pixel code @a code to a human-readable string.
 189  *
 190  * @return A pointer to a string on success, NULL on failure.
 191  */
 192 const char *v4l2_subdev_pixelcode_to_string(enum v4l2_mbus_pixelcode code);
 193
 194 /**
 195  * @brief Parse string to media bus pixel code.
 196  * @param string - input string
 197  * @param length - length of the string
 198  *
 199  * Parse human readable string @a string to an media bus pixel code.
 200  *
 201  * @return media bus pixelcode on success, -1 on failure.
 202  */
 203 enum v4l2_mbus_pixelcode v4l2_subdev_string_to_pixelcode(const char *string,
 204                                                          unsigned int length);
 205
 206 /**
 207  * @brief Convert a field order to string.
 208  * @param field - field order
 209  *
 210  * Convert field order @a field to a human-readable string.
 211  *
 212  * @return A pointer to a string on success, NULL on failure.
 213  */
 214 const char *v4l2_subdev_field_to_string(enum v4l2_field field);
 215
 216 /**
 217  * @brief Parse string to field order.
 218  * @param string - input string
 219  * @param length - length of the string
 220  *
 221  * Parse human readable string @a string to field order.
 222  *
 223  * @return field order on success, -1 on failure.
 224  */
 225 enum v4l2_field v4l2_subdev_string_to_field(const char *string,
 226                                             unsigned int length);
 227
 228 #endif