From 9b546182a4707fb2afe891a3eaa5ae804aa90ec8 Mon Sep 17 00:00:00 2001 From: Todor Tomov Date: Tue, 25 Jan 2011 17:46:47 +0200 Subject: Add doxygen comments Add doxygen format comments to header files. Signed-off-by: Laurent Pinchart Signed-off-by: Todor Tomov --- media.c | 18 ------------ media.h | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++ subdev.h | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 182 insertions(+), 18 deletions(-) diff --git a/media.c b/media.c index 5508775..456b882 100644 --- a/media.c +++ b/media.c @@ -34,9 +34,6 @@ #include "media.h" #include "tools.h" -/* - * media_entity_remote_pad - - */ struct media_pad *media_entity_remote_source(struct media_pad *pad) { unsigned int i; @@ -57,9 +54,6 @@ struct media_pad *media_entity_remote_source(struct media_pad *pad) return NULL; } -/* - * media_get_entity_by_name - - */ struct media_entity *media_get_entity_by_name(struct media_device *media, const char *name, size_t length) { @@ -75,9 +69,6 @@ struct media_entity *media_get_entity_by_name(struct media_device *media, return NULL; } -/* - * media_get_entity_by_id - - */ struct media_entity *media_get_entity_by_id(struct media_device *media, __u32 id) { @@ -93,9 +84,6 @@ struct media_entity *media_get_entity_by_id(struct media_device *media, return NULL; } -/* - * media_setup_link - - */ int media_setup_link(struct media_device *media, struct media_pad *source, struct media_pad *sink, @@ -330,9 +318,6 @@ static int media_enum_entities(struct media_device *media) return 0; } -/* - * media_open - - */ struct media_device *media_open(const char *name, int verbose) { struct media_device *media; @@ -381,9 +366,6 @@ struct media_device *media_open(const char *name, int verbose) return media; } -/* - * media_close - - */ void media_close(struct media_device *media) { unsigned int i; diff --git a/media.h b/media.h index bf5dcb7..80cf976 100644 --- a/media.h +++ b/media.h @@ -56,23 +56,105 @@ struct media_device { __u32 padding[6]; }; +/** + * @brief Open a media device. + * @param name - name (including path) of the device node. + * @param verbose - whether to print verbose information on the standard output. + * + * Open the media device referenced by @a name and enumerate entities, pads and + * links. + * + * @return A pointer to a newly allocated media_device structure instance on + * success and NULL on failure. The returned pointer must be freed with + * media_close when the device isn't needed anymore. + */ struct media_device *media_open(const char *name, int verbose); + +/** + * @brief Close a media device. + * @param media - device instance. + * + * Close the @a media device instance and free allocated resources. Access to the + * device instance is forbidden after this function returns. + */ void media_close(struct media_device *media); +/** + * @brief Locate the pad at the other end of a link. + * @param pad - sink pad at one end of the link. + * + * Locate the source pad connected to @a pad through an enabled link. As only one + * link connected to a sink pad can be enabled at a time, the connected source + * pad is guaranteed to be unique. + * + * @return A pointer to the connected source pad, or NULL if all links connected + * to @a pad are disabled. Return NULL also if @a pad is not a sink pad. + */ struct media_pad *media_entity_remote_source(struct media_pad *pad); +/** + * @brief Get the type of an entity. + * @param entity - the entity. + * + * @return The type of @a entity. + */ static inline unsigned int media_entity_type(struct media_entity *entity) { return entity->info.type & MEDIA_ENTITY_TYPE_MASK; } +/** + * @brief Find an entity by its name. + * @param media - media device. + * @param name - entity name. + * @param length - size of @a name. + * + * Search for an entity with a name equal to @a name. + * + * @return A pointer to the entity if found, or NULL otherwise. + */ struct media_entity *media_get_entity_by_name(struct media_device *media, const char *name, size_t length); + +/** + * @brief Find an entity by its ID. + * @param media - media device. + * @param id - entity ID. + * + * Search for an entity with an ID equal to @a id. + * + * @return A pointer to the entity if found, or NULL otherwise. + */ struct media_entity *media_get_entity_by_id(struct media_device *media, __u32 id); + +/** + * @brief Configure a link. + * @param media - media device. + * @param source - source pad at the link origin. + * @param sink - sink pad at the link target. + * @param flags - configuration flags. + * + * Locate the link between @a source and @a sink, and configure it by applying + * the new @a flags. + * + * Only the MEDIA_LINK_FLAG_ENABLED flag is writable. + * + * @return 0 on success, or a negative error code on failure. + */ int media_setup_link(struct media_device *media, struct media_pad *source, struct media_pad *sink, __u32 flags); + +/** + * @brief Reset all links to the disabled state. + * @param media - media device. + * + * Disable all links in the media device. This function is usually used after + * opening a media device to reset all links to a known state. + * + * @return 0 on success, or a negative error code on failure. + */ int media_reset_links(struct media_device *media); #endif diff --git a/subdev.h b/subdev.h index 976d066..9451b12 100644 --- a/subdev.h +++ b/subdev.h @@ -24,20 +24,120 @@ struct media_entity; +/** + * @brief Open a sub-device. + * @param entity - sub-device media entity. + * + * Open the V4L2 subdev device node associated with @a entity. The file + * descriptor is stored in the media_entity structure. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_open(struct media_entity *entity); +/** + * @brief Close a sub-device. + * @param entity - sub-device media entity. + * + * Close the V4L2 subdev device node associated with the @a entity and opened by + * a previous call to v4l2_subdev_open() (either explicit or implicit). + */ void v4l2_subdev_close(struct media_entity *entity); +/** + * @brief Retrieve the format on a pad. + * @param entity - subdev-device media entity. + * @param format - format to be filled. + * @param pad - pad number. + * @param which - identifier of the format to get. + * + * Retrieve the current format on the @a entity @a pad and store it in the + * @a format structure. + * + * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try format stored + * in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the current + * active format. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_get_format(struct media_entity *entity, struct v4l2_mbus_framefmt *format, unsigned int pad, enum v4l2_subdev_format_whence which); + +/** + * @brief Set the format on a pad. + * @param entity - subdev-device media entity. + * @param format - format. + * @param pad - pad number. + * @param which - identifier of the format to set. + * + * Set the format on the @a entity @a pad to @a format. The driver is allowed to + * modify the requested format, in which case @a format is updated with the + * modifications. + * + * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try format stored in the + * file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the device with an + * active format. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_set_format(struct media_entity *entity, struct v4l2_mbus_framefmt *format, unsigned int pad, enum v4l2_subdev_format_whence which); + +/** + * @brief Retrieve the crop rectangle on a pad. + * @param entity - subdev-device media entity. + * @param rect - crop rectangle to be filled. + * @param pad - pad number. + * @param which - identifier of the format to get. + * + * Retrieve the current crop rectangleon the @a entity @a pad and store it in + * the @a rect structure. + * + * @a which is set to V4L2_SUBDEV_FORMAT_TRY to retrieve the try crop rectangle + * stored in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to retrieve the + * current active crop rectangle. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_get_crop(struct media_entity *entity, struct v4l2_rect *rect, unsigned int pad, enum v4l2_subdev_format_whence which); + +/** + * @brief Set the crop rectangle on a pad. + * @param entity - subdev-device media entity. + * @param rect - crop rectangle. + * @param pad - pad number. + * @param which - identifier of the format to set. + * + * Set the crop rectangle on the @a entity @a pad to @a rect. The driver is + * allowed to modify the requested rectangle, in which case @a rect is updated + * with the modifications. + * + * @a which is set to V4L2_SUBDEV_FORMAT_TRY to set the try crop rectangle + * stored in the file handle, of V4L2_SUBDEV_FORMAT_ACTIVE to configure the + * device with an active crop rectangle. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_set_crop(struct media_entity *entity, struct v4l2_rect *rect, unsigned int pad, enum v4l2_subdev_format_whence which); + +/** + * @brief Set the frame interval on a sub-device. + * @param entity - subdev-device media entity. + * @param interval - frame interval. + * + * Set the frame interval on subdev @a entity to @a interval. The driver is + * allowed to modify the requested frame interval, in which case @a interval is + * updated with the modifications. + * + * Frame interval setting is usually supported only on devices at the beginning + * of video pipelines, such as sensors. + * + * @return 0 on success, or a negative error code on failure. + */ int v4l2_subdev_set_frame_interval(struct media_entity *entity, struct v4l2_fract *interval); -- cgit v1.2.3