[linux-block.git] / include / media / v4l2-async.h

/*
 * V4L2 asynchronous subdevice registration API
 *
 * Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 */

#ifndef V4L2_ASYNC_H
#define V4L2_ASYNC_H

#include <linux/list.h>
#include <linux/mutex.h>

struct device;
struct device_node;
struct v4l2_device;
struct v4l2_subdev;

/* A random max subdevice number, used to allocate an array on stack */
#define V4L2_MAX_SUBDEVS 128U

/**
 * enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
 *	in order to identify a match
 *
 * @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
 * 	v4l2_async_subdev.match ops
 * @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
 * @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
 * @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node
 *
 * This enum is used by the asyncrhronous sub-device logic to define the
 * algorithm that will be used to match an asynchronous device.
 */
enum v4l2_async_match_type {
	V4L2_ASYNC_MATCH_CUSTOM,
	V4L2_ASYNC_MATCH_DEVNAME,
	V4L2_ASYNC_MATCH_I2C,
	V4L2_ASYNC_MATCH_FWNODE,
};

/**
 * struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
 *
 * @match_type:	type of match that will be used
 * @match:	union of per-bus type matching data sets
 * @list:	used to link struct v4l2_async_subdev objects, waiting to be
 *		probed, to a notifier->waiting list
 *
 * When this struct is used as a member in a driver specific struct,
 * the driver specific struct shall contain the &struct
 * v4l2_async_subdev as its first member.
 */
struct v4l2_async_subdev {
	enum v4l2_async_match_type match_type;
	union {
		struct {
			struct fwnode_handle *fwnode;
		} fwnode;
		struct {
			const char *name;
		} device_name;
		struct {
			int adapter_id;
			unsigned short address;
		} i2c;
		struct {
			bool (*match)(struct device *,
				      struct v4l2_async_subdev *);
			void *priv;
		} custom;
	} match;

	/* v4l2-async core private: not to be used by drivers */
	struct list_head list;
};

/**
 * struct v4l2_async_notifier - v4l2_device notifier data
 *
 * @num_subdevs: number of subdevices used in the subdevs array
 * @max_subdevs: number of subdevices allocated in the subdevs array
 * @subdevs:	array of pointers to subdevice descriptors
 * @v4l2_dev:	pointer to struct v4l2_device
 * @waiting:	list of struct v4l2_async_subdev, waiting for their drivers
 * @done:	list of struct v4l2_subdev, already probed
 * @list:	member in a global list of notifiers
 * @bound:	a subdevice driver has successfully probed one of subdevices
 * @complete:	all subdevices have been probed successfully
 * @unbind:	a subdevice is leaving
 */
struct v4l2_async_notifier {
	unsigned int num_subdevs;
	unsigned int max_subdevs;
	struct v4l2_async_subdev **subdevs;
	struct v4l2_device *v4l2_dev;
	struct list_head waiting;
	struct list_head done;
	struct list_head list;
	int (*bound)(struct v4l2_async_notifier *notifier,
		     struct v4l2_subdev *subdev,
		     struct v4l2_async_subdev *asd);
	int (*complete)(struct v4l2_async_notifier *notifier);
	void (*unbind)(struct v4l2_async_notifier *notifier,
		       struct v4l2_subdev *subdev,
		       struct v4l2_async_subdev *asd);
};

/**
 * v4l2_async_notifier_register - registers a subdevice asynchronous notifier
 *
 * @v4l2_dev: pointer to &struct v4l2_device
 * @notifier: pointer to &struct v4l2_async_notifier
 */
int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
				 struct v4l2_async_notifier *notifier);

/**
 * v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
 *
 * @notifier: pointer to &struct v4l2_async_notifier
 */
void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);

/**
 * v4l2_async_notifier_cleanup - clean up notifier resources
 * @notifier: the notifier the resources of which are to be cleaned up
 *
 * Release memory resources related to a notifier, including the async
 * sub-devices allocated for the purposes of the notifier but not the notifier
 * itself. The user is responsible for calling this function to clean up the
 * notifier after calling @v4l2_async_notifier_parse_fwnode_endpoints.
 *
 * There is no harm from calling v4l2_async_notifier_cleanup in other
 * cases as long as its memory has been zeroed after it has been
 * allocated.
 */
void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);

/**
 * v4l2_async_register_subdev - registers a sub-device to the asynchronous
 * 	subdevice framework
 *
 * @sd: pointer to &struct v4l2_subdev
 */
int v4l2_async_register_subdev(struct v4l2_subdev *sd);

/**
 * v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
 * 	subdevice framework
 *
 * @sd: pointer to &struct v4l2_subdev
 */
void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
#endif
Commit	Line	Data
e9e31049 GL	1	/*
	2	* V4L2 asynchronous subdevice registration API
	3	*
	4	* Copyright (C) 2012-2013, Guennadi Liakhovetski <g.liakhovetski@gmx.de>
	5	*
	6	* This program is free software; you can redistribute it and/or modify
	7	* it under the terms of the GNU General Public License version 2 as
	8	* published by the Free Software Foundation.
	9	*/
	10
	11	#ifndef V4L2_ASYNC_H
	12	#define V4L2_ASYNC_H
	13
	14	#include <linux/list.h>
	15	#include <linux/mutex.h>
	16
	17	struct device;
e7359f8e	18	struct device_node;
e9e31049 GL	19	struct v4l2_device;
e9e31049 GL	20	struct v4l2_subdev;
e9e31049 GL	21
	22	/* A random max subdevice number, used to allocate an array on stack */
	23	#define V4L2_MAX_SUBDEVS 128U
	24
ab4f5a4a MCC	25	/**
	26	* enum v4l2_async_match_type - type of asynchronous subdevice logic to be used
	27	* in order to identify a match
	28	*
	29	* @V4L2_ASYNC_MATCH_CUSTOM: Match will use the logic provided by &struct
	30	* v4l2_async_subdev.match ops
	31	* @V4L2_ASYNC_MATCH_DEVNAME: Match will use the device name
	32	* @V4L2_ASYNC_MATCH_I2C: Match will check for I2C adapter ID and address
ecdf0cfe	33	* @V4L2_ASYNC_MATCH_FWNODE: Match will use firmware node
ab4f5a4a MCC	34	*
	35	* This enum is used by the asyncrhronous sub-device logic to define the
	36	* algorithm that will be used to match an asynchronous device.
	37	*/
cfca7644 SN	38	enum v4l2_async_match_type {
	39	V4L2_ASYNC_MATCH_CUSTOM,
	40	V4L2_ASYNC_MATCH_DEVNAME,
	41	V4L2_ASYNC_MATCH_I2C,
ecdf0cfe	42	V4L2_ASYNC_MATCH_FWNODE,
e9e31049 GL	43	};
	44
	45	/**
	46	* struct v4l2_async_subdev - sub-device descriptor, as known to a bridge
f8b27377 MCC	47	*
f8b27377 MCC	48	* @match_type: type of match that will be used
e9e31049 GL	49	* @match: union of per-bus type matching data sets
	50	* @list: used to link struct v4l2_async_subdev objects, waiting to be
	51	* probed, to a notifier->waiting list
9ca46531 SA	52	*
	53	* When this struct is used as a member in a driver specific struct,
	54	* the driver specific struct shall contain the &struct
	55	* v4l2_async_subdev as its first member.
e9e31049 GL	56	*/
e9e31049 GL	57	struct v4l2_async_subdev {
cfca7644	58	enum v4l2_async_match_type match_type;
e9e31049	59	union {
ecdf0cfe SA	60	struct {
	61	struct fwnode_handle *fwnode;
	62	} fwnode;
e9e31049 GL	63	struct {
e9e31049 GL	64	const char *name;
cfca7644	65	} device_name;
e9e31049 GL	66	struct {
	67	int adapter_id;
	68	unsigned short address;
	69	} i2c;
	70	struct {
	71	bool (match)(struct device ,
	72	struct v4l2_async_subdev *);
	73	void *priv;
	74	} custom;
	75	} match;
	76
	77	/* v4l2-async core private: not to be used by drivers */
	78	struct list_head list;
	79	};
	80
e9e31049	81	/**
f8b27377 MCC	82	* struct v4l2_async_notifier - v4l2_device notifier data
f8b27377 MCC	83	*
9ca46531 SA	84	* @num_subdevs: number of subdevices used in the subdevs array
9ca46531 SA	85	* @max_subdevs: number of subdevices allocated in the subdevs array
e8419d08	86	* @subdevs: array of pointers to subdevice descriptors
e9e31049 GL	87	* @v4l2_dev: pointer to struct v4l2_device
e9e31049 GL	88	* @waiting: list of struct v4l2_async_subdev, waiting for their drivers
b426b3a6	89	* @done: list of struct v4l2_subdev, already probed
e9e31049 GL	90	* @list: member in a global list of notifiers
	91	* @bound: a subdevice driver has successfully probed one of subdevices
	92	* @complete: all subdevices have been probed successfully
	93	* @unbind: a subdevice is leaving
	94	*/
	95	struct v4l2_async_notifier {
	96	unsigned int num_subdevs;
9ca46531	97	unsigned int max_subdevs;
e8419d08	98	struct v4l2_async_subdev **subdevs;
e9e31049 GL	99	struct v4l2_device *v4l2_dev;
	100	struct list_head waiting;
	101	struct list_head done;
	102	struct list_head list;
	103	int (bound)(struct v4l2_async_notifier notifier,
	104	struct v4l2_subdev *subdev,
	105	struct v4l2_async_subdev *asd);
	106	int (complete)(struct v4l2_async_notifier notifier);
	107	void (unbind)(struct v4l2_async_notifier notifier,
	108	struct v4l2_subdev *subdev,
	109	struct v4l2_async_subdev *asd);
	110	};
	111
ab4f5a4a MCC	112	/**
	113	* v4l2_async_notifier_register - registers a subdevice asynchronous notifier
	114	*
	115	* @v4l2_dev: pointer to &struct v4l2_device
	116	* @notifier: pointer to &struct v4l2_async_notifier
	117	*/
e9e31049 GL	118	int v4l2_async_notifier_register(struct v4l2_device *v4l2_dev,
e9e31049 GL	119	struct v4l2_async_notifier *notifier);
ab4f5a4a MCC	120
	121	/**
	122	* v4l2_async_notifier_unregister - unregisters a subdevice asynchronous notifier
	123	*
	124	* @notifier: pointer to &struct v4l2_async_notifier
	125	*/
e9e31049	126	void v4l2_async_notifier_unregister(struct v4l2_async_notifier *notifier);
ab4f5a4a	127
9ca46531 SA	128	/**
	129	* v4l2_async_notifier_cleanup - clean up notifier resources
	130	* @notifier: the notifier the resources of which are to be cleaned up
	131	*
	132	* Release memory resources related to a notifier, including the async
	133	* sub-devices allocated for the purposes of the notifier but not the notifier
	134	* itself. The user is responsible for calling this function to clean up the
	135	* notifier after calling @v4l2_async_notifier_parse_fwnode_endpoints.
	136	*
	137	* There is no harm from calling v4l2_async_notifier_cleanup in other
	138	* cases as long as its memory has been zeroed after it has been
	139	* allocated.
	140	*/
	141	void v4l2_async_notifier_cleanup(struct v4l2_async_notifier *notifier);
	142
ab4f5a4a MCC	143	/**
	144	* v4l2_async_register_subdev - registers a sub-device to the asynchronous
	145	* subdevice framework
	146	*
	147	* @sd: pointer to &struct v4l2_subdev
	148	*/
e9e31049	149	int v4l2_async_register_subdev(struct v4l2_subdev *sd);
ab4f5a4a MCC	150
	151	/**
	152	* v4l2_async_unregister_subdev - unregisters a sub-device to the asynchronous
	153	* subdevice framework
	154	*
	155	* @sd: pointer to &struct v4l2_subdev
	156	*/
e9e31049 GL	157	void v4l2_async_unregister_subdev(struct v4l2_subdev *sd);
e9e31049 GL	158	#endif