1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * Greybus Camera protocol driver.
4  *
5  * Copyright 2015 Google Inc.
6  */
7 #ifndef __GB_CAMERA_H
8 #define __GB_CAMERA_H
9 
10 #include <linux/v4l2-mediabus.h>
11 
12 /* Input flags need to be set from the caller */
13 #define GB_CAMERA_IN_FLAG_TEST		(1 << 0)
14 /* Output flags returned */
15 #define GB_CAMERA_OUT_FLAG_ADJUSTED	(1 << 0)
16 
17 /**
18  * struct gb_camera_stream - Represents greybus camera stream.
19  * @width: Stream width in pixels.
20  * @height: Stream height in pixels.
21  * @pixel_code: Media bus pixel code.
22  * @vc: MIPI CSI virtual channel.
23  * @dt: MIPI CSI data types. Most formats use a single data type, in which case
24  *      the second element will be ignored.
25  * @max_size: Maximum size of a frame in bytes. The camera module guarantees
26  *            that all data between the Frame Start and Frame End packet for
27  *            the associated virtual channel and data type(s) will not exceed
28  *            this size.
29  */
30 struct gb_camera_stream {
31 	unsigned int width;
32 	unsigned int height;
33 	enum v4l2_mbus_pixelcode pixel_code;
34 	unsigned int vc;
35 	unsigned int dt[2];
36 	unsigned int max_size;
37 };
38 
39 /**
40  * struct gb_camera_csi_params - CSI configuration parameters
41  * @num_lanes: number of CSI data lanes
42  * @clk_freq: CSI clock frequency in Hz
43  */
44 struct gb_camera_csi_params {
45 	unsigned int num_lanes;
46 	unsigned int clk_freq;
47 };
48 
49 /**
50  * struct gb_camera_ops - Greybus camera operations, used by the Greybus camera
51  *                        driver to expose operations to the host camera driver.
52  * @capabilities: Retrieve camera capabilities and store them in the buffer
53  *                'buf' capabilities. The buffer maximum size is specified by
54  *                the caller in the 'size' parameter, and the effective
55  *                capabilities size is returned from the function. If the buffer
56  *                size is too small to hold the capabilities an error is
57  *                returned and the buffer is left untouched.
58  *
59  * @configure_streams: Negotiate configuration and prepare the module for video
60  *                     capture. The caller specifies the number of streams it
61  *                     requests in the 'nstreams' argument and the associated
62  *                     streams configurations in the 'streams' argument. The
63  *                     GB_CAMERA_IN_FLAG_TEST 'flag' can be set to test a
64  *                     configuration without applying it, otherwise the
65  *                     configuration is applied by the module. The module can
66  *                     decide to modify the requested configuration, including
67  *                     using a different number of streams. In that case the
68  *                     modified configuration won't be applied, the
69  *                     GB_CAMERA_OUT_FLAG_ADJUSTED 'flag' will be set upon
70  *                     return, and the modified configuration and number of
71  *                     streams stored in 'streams' and 'array'. The module
72  *                     returns its CSI-2 bus parameters in the 'csi_params'
73  *                     structure in all cases.
74  *
75  * @capture: Submit a capture request. The supplied 'request_id' must be unique
76  *           and higher than the IDs of all the previously submitted requests.
77  *           The 'streams' argument specifies which streams are affected by the
78  *           request in the form of a bitmask, with bits corresponding to the
79  *           configured streams indexes. If the request contains settings, the
80  *           'settings' argument points to the settings buffer and its size is
81  *           specified by the 'settings_size' argument. Otherwise the 'settings'
82  *           argument should be set to NULL and 'settings_size' to 0.
83  *
84  * @flush: Flush the capture requests queue. Return the ID of the last request
85  *         that will processed by the device before it stops transmitting video
86  *         frames. All queued capture requests with IDs higher than the returned
87  *         ID will be dropped without being processed.
88  */
89 struct gb_camera_ops {
90 	ssize_t (*capabilities)(void *priv, char *buf, size_t len);
91 	int (*configure_streams)(void *priv, unsigned int *nstreams,
92 			unsigned int *flags, struct gb_camera_stream *streams,
93 			struct gb_camera_csi_params *csi_params);
94 	int (*capture)(void *priv, u32 request_id,
95 			unsigned int streams, unsigned int num_frames,
96 			size_t settings_size, const void *settings);
97 	int (*flush)(void *priv, u32 *request_id);
98 };
99 
100 /**
101  * struct gb_camera_module - Represents greybus camera module.
102  * @priv: Module private data, passed to all camera operations.
103  * @ops: Greybus camera operation callbacks.
104  * @interface_id: Interface id of the module.
105  * @refcount: Reference counting object.
106  * @release: Module release function.
107  * @list: List entry in the camera modules list.
108  */
109 struct gb_camera_module {
110 	void *priv;
111 	const struct gb_camera_ops *ops;
112 
113 	unsigned int interface_id;
114 	struct kref refcount;
115 	void (*release)(struct kref *kref);
116 	struct list_head list; /* Global list */
117 };
118 
119 #define gb_camera_call(f, op, args...)      \
120 	(!(f) ? -ENODEV : (((f)->ops->op) ?  \
121 	(f)->ops->op((f)->priv, ##args) : -ENOIOCTLCMD))
122 
123 int gb_camera_register(struct gb_camera_module *module);
124 int gb_camera_unregister(struct gb_camera_module *module);
125 
126 #endif /* __GB_CAMERA_H */
127