1 | /* SPDX-License-Identifier: GPL-2.0-only */ |
2 | /* |
3 | * |
4 | * Copyright (C) 2005 Mike Isely <isely@pobox.com> |
5 | */ |
6 | #ifndef __PVRUSB2_HDW_H |
7 | #define __PVRUSB2_HDW_H |
8 | |
9 | #include <linux/usb.h> |
10 | #include <linux/videodev2.h> |
11 | #include <media/v4l2-dev.h> |
12 | #include "pvrusb2-io.h" |
13 | #include "pvrusb2-ctrl.h" |
14 | |
15 | |
16 | /* Private internal control ids, look these up with |
17 | pvr2_hdw_get_ctrl_by_id() - these are NOT visible in V4L */ |
18 | #define PVR2_CID_STDCUR 2 |
19 | #define PVR2_CID_STDAVAIL 3 |
20 | #define PVR2_CID_INPUT 4 |
21 | #define PVR2_CID_AUDIOMODE 5 |
22 | #define PVR2_CID_FREQUENCY 6 |
23 | #define PVR2_CID_HRES 7 |
24 | #define PVR2_CID_VRES 8 |
25 | #define PVR2_CID_CROPL 9 |
26 | #define PVR2_CID_CROPT 10 |
27 | #define PVR2_CID_CROPW 11 |
28 | #define PVR2_CID_CROPH 12 |
29 | #define PVR2_CID_CROPCAPPAN 13 |
30 | #define PVR2_CID_CROPCAPPAD 14 |
31 | #define PVR2_CID_CROPCAPBL 15 |
32 | #define PVR2_CID_CROPCAPBT 16 |
33 | #define PVR2_CID_CROPCAPBW 17 |
34 | #define PVR2_CID_CROPCAPBH 18 |
35 | #define PVR2_CID_STDDETECT 19 |
36 | |
37 | /* Legal values for the INPUT state variable */ |
38 | #define PVR2_CVAL_INPUT_TV 0 |
39 | #define PVR2_CVAL_INPUT_DTV 1 |
40 | #define PVR2_CVAL_INPUT_COMPOSITE 2 |
41 | #define PVR2_CVAL_INPUT_SVIDEO 3 |
42 | #define PVR2_CVAL_INPUT_RADIO 4 |
43 | #define PVR2_CVAL_INPUT_MAX PVR2_CVAL_INPUT_RADIO |
44 | |
45 | enum pvr2_config { |
46 | pvr2_config_empty, /* No configuration */ |
47 | pvr2_config_mpeg, /* Encoded / compressed video */ |
48 | pvr2_config_vbi, /* Standard vbi info */ |
49 | pvr2_config_pcm, /* Audio raw pcm stream */ |
50 | pvr2_config_rawvideo, /* Video raw frames */ |
51 | }; |
52 | |
53 | enum pvr2_v4l_type { |
54 | pvr2_v4l_type_video, |
55 | pvr2_v4l_type_vbi, |
56 | pvr2_v4l_type_radio, |
57 | }; |
58 | |
59 | /* Major states that we can be in: |
60 | * |
61 | * DEAD - Device is in an unusable state and cannot be recovered. This |
62 | * can happen if we completely lose the ability to communicate with it |
63 | * (but it might still on the bus). In this state there's nothing we can |
64 | * do; it must be replugged in order to recover. |
65 | * |
66 | * COLD - Device is in an unusable state, needs microcontroller firmware. |
67 | * |
68 | * WARM - We can communicate with the device and the proper |
69 | * microcontroller firmware is running, but other device initialization is |
70 | * still needed (e.g. encoder firmware). |
71 | * |
72 | * ERROR - A problem prevents capture operation (e.g. encoder firmware |
73 | * missing). |
74 | * |
75 | * READY - Device is operational, but not streaming. |
76 | * |
77 | * RUN - Device is streaming. |
78 | * |
79 | */ |
80 | #define PVR2_STATE_NONE 0 |
81 | #define PVR2_STATE_DEAD 1 |
82 | #define PVR2_STATE_COLD 2 |
83 | #define PVR2_STATE_WARM 3 |
84 | #define PVR2_STATE_ERROR 4 |
85 | #define PVR2_STATE_READY 5 |
86 | #define PVR2_STATE_RUN 6 |
87 | |
88 | /* Translate configuration enum to a string label */ |
89 | const char *pvr2_config_get_name(enum pvr2_config); |
90 | |
91 | struct pvr2_hdw; |
92 | |
93 | /* Create and return a structure for interacting with the underlying |
94 | hardware */ |
95 | struct pvr2_hdw *pvr2_hdw_create(struct usb_interface *intf, |
96 | const struct usb_device_id *devid); |
97 | |
98 | /* Perform second stage initialization, passing in a notification callback |
99 | for when the master state changes. */ |
100 | int pvr2_hdw_initialize(struct pvr2_hdw *, |
101 | void (*callback_func)(void *), |
102 | void *callback_data); |
103 | |
104 | /* Destroy hardware interaction structure */ |
105 | void pvr2_hdw_destroy(struct pvr2_hdw *); |
106 | |
107 | /* Return true if in the ready (normal) state */ |
108 | int pvr2_hdw_dev_ok(struct pvr2_hdw *); |
109 | |
110 | /* Return small integer number [1..N] for logical instance number of this |
111 | device. This is useful for indexing array-valued module parameters. */ |
112 | int pvr2_hdw_get_unit_number(struct pvr2_hdw *); |
113 | |
114 | /* Get pointer to underlying USB device */ |
115 | struct usb_device *pvr2_hdw_get_dev(struct pvr2_hdw *); |
116 | |
117 | /* Retrieve serial number of device */ |
118 | unsigned long pvr2_hdw_get_sn(struct pvr2_hdw *); |
119 | |
120 | /* Retrieve bus location info of device */ |
121 | const char *pvr2_hdw_get_bus_info(struct pvr2_hdw *); |
122 | |
123 | /* Retrieve per-instance string identifier for this specific device */ |
124 | const char *pvr2_hdw_get_device_identifier(struct pvr2_hdw *); |
125 | |
126 | /* Called when hardware has been unplugged */ |
127 | void pvr2_hdw_disconnect(struct pvr2_hdw *); |
128 | |
129 | /* Sets v4l2_dev of a video_device struct */ |
130 | void pvr2_hdw_set_v4l2_dev(struct pvr2_hdw *, struct video_device *); |
131 | |
132 | /* Get the number of defined controls */ |
133 | unsigned int pvr2_hdw_get_ctrl_count(struct pvr2_hdw *); |
134 | |
135 | /* Retrieve a control handle given its index (0..count-1) */ |
136 | struct pvr2_ctrl *pvr2_hdw_get_ctrl_by_index(struct pvr2_hdw *,unsigned int); |
137 | |
138 | /* Retrieve a control handle given its internal ID (if any) */ |
139 | struct pvr2_ctrl *pvr2_hdw_get_ctrl_by_id(struct pvr2_hdw *,unsigned int); |
140 | |
141 | /* Retrieve a control handle given its V4L ID (if any) */ |
142 | struct pvr2_ctrl *pvr2_hdw_get_ctrl_v4l(struct pvr2_hdw *,unsigned int ctl_id); |
143 | |
144 | /* Retrieve a control handle given its immediate predecessor V4L ID (if any) */ |
145 | struct pvr2_ctrl *pvr2_hdw_get_ctrl_nextv4l(struct pvr2_hdw *, |
146 | unsigned int ctl_id); |
147 | |
148 | /* Commit all control changes made up to this point */ |
149 | int pvr2_hdw_commit_ctl(struct pvr2_hdw *); |
150 | |
151 | /* Return a bit mask of valid input selections for this device. Mask bits |
152 | * will be according to PVR_CVAL_INPUT_xxxx definitions. */ |
153 | unsigned int pvr2_hdw_get_input_available(struct pvr2_hdw *); |
154 | |
155 | /* Return a bit mask of allowed input selections for this device. Mask bits |
156 | * will be according to PVR_CVAL_INPUT_xxxx definitions. */ |
157 | unsigned int pvr2_hdw_get_input_allowed(struct pvr2_hdw *); |
158 | |
159 | /* Change the set of allowed input selections for this device. Both |
160 | change_mask and change_valu are mask bits according to |
161 | PVR_CVAL_INPUT_xxxx definitions. The change_mask parameter indicate |
162 | which settings are being changed and the change_val parameter indicates |
163 | whether corresponding settings are being set or cleared. */ |
164 | int pvr2_hdw_set_input_allowed(struct pvr2_hdw *, |
165 | unsigned int change_mask, |
166 | unsigned int change_val); |
167 | |
168 | /* Return name for this driver instance */ |
169 | const char *pvr2_hdw_get_driver_name(struct pvr2_hdw *); |
170 | |
171 | /* Mark tuner status stale so that it will be re-fetched */ |
172 | void pvr2_hdw_execute_tuner_poll(struct pvr2_hdw *); |
173 | |
174 | /* Return information about the tuner */ |
175 | int pvr2_hdw_get_tuner_status(struct pvr2_hdw *,struct v4l2_tuner *); |
176 | |
177 | /* Return information about cropping capabilities */ |
178 | int pvr2_hdw_get_cropcap(struct pvr2_hdw *, struct v4l2_cropcap *); |
179 | |
180 | /* Query device and see if it thinks it is on a high-speed USB link */ |
181 | int pvr2_hdw_is_hsm(struct pvr2_hdw *); |
182 | |
183 | /* Return a string token representative of the hardware type */ |
184 | const char *pvr2_hdw_get_type(struct pvr2_hdw *); |
185 | |
186 | /* Return a single line description of the hardware type */ |
187 | const char *pvr2_hdw_get_desc(struct pvr2_hdw *); |
188 | |
189 | /* Turn streaming on/off */ |
190 | int pvr2_hdw_set_streaming(struct pvr2_hdw *,int); |
191 | |
192 | /* Find out if streaming is on */ |
193 | int pvr2_hdw_get_streaming(struct pvr2_hdw *); |
194 | |
195 | /* Retrieve driver overall state */ |
196 | int pvr2_hdw_get_state(struct pvr2_hdw *); |
197 | |
198 | /* Configure the type of stream to generate */ |
199 | int pvr2_hdw_set_stream_type(struct pvr2_hdw *, enum pvr2_config); |
200 | |
201 | /* Get handle to video output stream */ |
202 | struct pvr2_stream *pvr2_hdw_get_video_stream(struct pvr2_hdw *); |
203 | |
204 | /* Enable / disable retrieval of CPU firmware or prom contents. This must |
205 | be enabled before pvr2_hdw_cpufw_get() will function. Note that doing |
206 | this may prevent the device from running (and leaving this mode may |
207 | imply a device reset). */ |
208 | void pvr2_hdw_cpufw_set_enabled(struct pvr2_hdw *, |
209 | int mode, /* 0=8KB FX2, 1=16KB FX2, 2=PROM */ |
210 | int enable_flag); |
211 | |
212 | /* Return true if we're in a mode for retrieval CPU firmware */ |
213 | int pvr2_hdw_cpufw_get_enabled(struct pvr2_hdw *); |
214 | |
215 | /* Retrieve a piece of the CPU's firmware at the given offset. Return |
216 | value is the number of bytes retrieved or zero if we're past the end or |
217 | an error otherwise (e.g. if firmware retrieval is not enabled). */ |
218 | int pvr2_hdw_cpufw_get(struct pvr2_hdw *,unsigned int offs, |
219 | char *buf,unsigned int cnt); |
220 | |
221 | /* Retrieve a previously stored v4l minor device number */ |
222 | int pvr2_hdw_v4l_get_minor_number(struct pvr2_hdw *,enum pvr2_v4l_type index); |
223 | |
224 | /* Store a v4l minor device number */ |
225 | void pvr2_hdw_v4l_store_minor_number(struct pvr2_hdw *, |
226 | enum pvr2_v4l_type index,int); |
227 | |
228 | /* The following entry points are all lower level things you normally don't |
229 | want to worry about. */ |
230 | |
231 | /* Issue a command and get a response from the device. LOTS of higher |
232 | level stuff is built on this. */ |
233 | int pvr2_send_request(struct pvr2_hdw *, |
234 | void *write_ptr,unsigned int write_len, |
235 | void *read_ptr,unsigned int read_len); |
236 | |
237 | /* Slightly higher level device communication functions. */ |
238 | int pvr2_write_register(struct pvr2_hdw *, u16, u32); |
239 | |
240 | /* Call if for any reason we can't talk to the hardware anymore - this will |
241 | cause the driver to stop flailing on the device. */ |
242 | void pvr2_hdw_render_useless(struct pvr2_hdw *); |
243 | |
244 | /* Set / clear 8051's reset bit */ |
245 | void pvr2_hdw_cpureset_assert(struct pvr2_hdw *,int); |
246 | |
247 | /* Execute a USB-commanded device reset */ |
248 | void pvr2_hdw_device_reset(struct pvr2_hdw *); |
249 | |
250 | /* Reset worker's error trapping circuit breaker */ |
251 | int pvr2_hdw_untrip(struct pvr2_hdw *); |
252 | |
253 | /* Execute hard reset command (after this point it's likely that the |
254 | encoder will have to be reconfigured). This also clears the "useless" |
255 | state. */ |
256 | int pvr2_hdw_cmd_deep_reset(struct pvr2_hdw *); |
257 | |
258 | /* Execute simple reset command */ |
259 | int pvr2_hdw_cmd_powerup(struct pvr2_hdw *); |
260 | |
261 | /* Order decoder to reset */ |
262 | int pvr2_hdw_cmd_decoder_reset(struct pvr2_hdw *); |
263 | |
264 | /* Direct manipulation of GPIO bits */ |
265 | int pvr2_hdw_gpio_get_dir(struct pvr2_hdw *hdw,u32 *); |
266 | int pvr2_hdw_gpio_get_out(struct pvr2_hdw *hdw,u32 *); |
267 | int pvr2_hdw_gpio_get_in(struct pvr2_hdw *hdw,u32 *); |
268 | int pvr2_hdw_gpio_chg_dir(struct pvr2_hdw *hdw,u32 msk,u32 val); |
269 | int pvr2_hdw_gpio_chg_out(struct pvr2_hdw *hdw,u32 msk,u32 val); |
270 | |
271 | /* This data structure is specifically for the next function... */ |
272 | struct pvr2_hdw_debug_info { |
273 | int big_lock_held; |
274 | int ctl_lock_held; |
275 | int flag_disconnected; |
276 | int flag_init_ok; |
277 | int flag_ok; |
278 | int fw1_state; |
279 | int flag_decoder_missed; |
280 | int flag_tripped; |
281 | int state_encoder_ok; |
282 | int state_encoder_run; |
283 | int state_decoder_run; |
284 | int state_decoder_ready; |
285 | int state_usbstream_run; |
286 | int state_decoder_quiescent; |
287 | int state_pipeline_config; |
288 | int state_pipeline_req; |
289 | int state_pipeline_pause; |
290 | int state_pipeline_idle; |
291 | int cmd_debug_state; |
292 | int cmd_debug_write_len; |
293 | int cmd_debug_read_len; |
294 | int cmd_debug_write_pend; |
295 | int cmd_debug_read_pend; |
296 | int cmd_debug_timeout; |
297 | int cmd_debug_rstatus; |
298 | int cmd_debug_wstatus; |
299 | unsigned char cmd_code; |
300 | }; |
301 | |
302 | /* Non-intrusively retrieve internal state info - this is useful for |
303 | diagnosing lockups. Note that this operation is completed without any |
304 | kind of locking and so it is not atomic and may yield inconsistent |
305 | results. This is *purely* a debugging aid. */ |
306 | void pvr2_hdw_get_debug_info_unlocked(const struct pvr2_hdw *hdw, |
307 | struct pvr2_hdw_debug_info *); |
308 | |
309 | /* Intrusively retrieve internal state info - this is useful for |
310 | diagnosing overall driver state. This operation synchronizes against |
311 | the overall driver mutex - so if there are locking problems this will |
312 | likely hang! This is *purely* a debugging aid. */ |
313 | void pvr2_hdw_get_debug_info_locked(struct pvr2_hdw *hdw, |
314 | struct pvr2_hdw_debug_info *); |
315 | |
316 | /* Report out several lines of text that describes driver internal state. |
317 | Results are written into the passed-in buffer. */ |
318 | unsigned int pvr2_hdw_state_report(struct pvr2_hdw *hdw, |
319 | char *buf_ptr,unsigned int buf_size); |
320 | |
321 | /* Cause modules to log their state once */ |
322 | void pvr2_hdw_trigger_module_log(struct pvr2_hdw *hdw); |
323 | |
324 | /* Cause encoder firmware to be uploaded into the device. This is normally |
325 | done autonomously, but the interface is exported here because it is also |
326 | a debugging aid. */ |
327 | int pvr2_upload_firmware2(struct pvr2_hdw *hdw); |
328 | |
329 | #endif /* __PVRUSB2_HDW_H */ |
330 | |