usb/pvrusb2/pvrusb2-hdw.h

0001 /* SPDX-License-Identifier: GPL-2.0-only */
0002 /*
0003  *
0004  *  Copyright (C) 2005 Mike Isely <isely@pobox.com>
0005  */
0006 #ifndef __PVRUSB2_HDW_H
0007 #define __PVRUSB2_HDW_H
0008
0009 #include <linux/usb.h>
0010 #include <linux/videodev2.h>
0011 #include <media/v4l2-dev.h>
0012 #include "pvrusb2-io.h"
0013 #include "pvrusb2-ctrl.h"
0014
0015
0016 /* Private internal control ids, look these up with
0017    pvr2_hdw_get_ctrl_by_id() - these are NOT visible in V4L */
0018 #define PVR2_CID_STDCUR 2
0019 #define PVR2_CID_STDAVAIL 3
0020 #define PVR2_CID_INPUT 4
0021 #define PVR2_CID_AUDIOMODE 5
0022 #define PVR2_CID_FREQUENCY 6
0023 #define PVR2_CID_HRES 7
0024 #define PVR2_CID_VRES 8
0025 #define PVR2_CID_CROPL 9
0026 #define PVR2_CID_CROPT 10
0027 #define PVR2_CID_CROPW 11
0028 #define PVR2_CID_CROPH 12
0029 #define PVR2_CID_CROPCAPPAN 13
0030 #define PVR2_CID_CROPCAPPAD 14
0031 #define PVR2_CID_CROPCAPBL 15
0032 #define PVR2_CID_CROPCAPBT 16
0033 #define PVR2_CID_CROPCAPBW 17
0034 #define PVR2_CID_CROPCAPBH 18
0035 #define PVR2_CID_STDDETECT 19
0036
0037 /* Legal values for the INPUT state variable */
0038 #define PVR2_CVAL_INPUT_TV 0
0039 #define PVR2_CVAL_INPUT_DTV 1
0040 #define PVR2_CVAL_INPUT_COMPOSITE 2
0041 #define PVR2_CVAL_INPUT_SVIDEO 3
0042 #define PVR2_CVAL_INPUT_RADIO 4
0043 #define PVR2_CVAL_INPUT_MAX PVR2_CVAL_INPUT_RADIO
0044
0045 enum pvr2_config {
0046     pvr2_config_empty,    /* No configuration */
0047     pvr2_config_mpeg,     /* Encoded / compressed video */
0048     pvr2_config_vbi,      /* Standard vbi info */
0049     pvr2_config_pcm,      /* Audio raw pcm stream */
0050     pvr2_config_rawvideo, /* Video raw frames */
0051 };
0052
0053 enum pvr2_v4l_type {
0054     pvr2_v4l_type_video,
0055     pvr2_v4l_type_vbi,
0056     pvr2_v4l_type_radio,
0057 };
0058
0059 /* Major states that we can be in:
0060  *
0061  *  DEAD - Device is in an unusable state and cannot be recovered.  This
0062  *  can happen if we completely lose the ability to communicate with it
0063  *  (but it might still on the bus).  In this state there's nothing we can
0064  *  do; it must be replugged in order to recover.
0065  *
0066  *  COLD - Device is in an unusable state, needs microcontroller firmware.
0067  *
0068  *  WARM - We can communicate with the device and the proper
0069  *  microcontroller firmware is running, but other device initialization is
0070  *  still needed (e.g. encoder firmware).
0071  *
0072  *  ERROR - A problem prevents capture operation (e.g. encoder firmware
0073  *  missing).
0074  *
0075  *  READY - Device is operational, but not streaming.
0076  *
0077  *  RUN - Device is streaming.
0078  *
0079  */
0080 #define PVR2_STATE_NONE 0
0081 #define PVR2_STATE_DEAD 1
0082 #define PVR2_STATE_COLD 2
0083 #define PVR2_STATE_WARM 3
0084 #define PVR2_STATE_ERROR 4
0085 #define PVR2_STATE_READY 5
0086 #define PVR2_STATE_RUN 6
0087
0088 /* Translate configuration enum to a string label */
0089 const char *pvr2_config_get_name(enum pvr2_config);
0090
0091 struct pvr2_hdw;
0092
0093 /* Create and return a structure for interacting with the underlying
0094    hardware */
0095 struct pvr2_hdw *pvr2_hdw_create(struct usb_interface *intf,
0096                  const struct usb_device_id *devid);
0097
0098 /* Perform second stage initialization, passing in a notification callback
0099    for when the master state changes. */
0100 int pvr2_hdw_initialize(struct pvr2_hdw *,
0101             void (*callback_func)(void *),
0102             void *callback_data);
0103
0104 /* Destroy hardware interaction structure */
0105 void pvr2_hdw_destroy(struct pvr2_hdw *);
0106
0107 /* Return true if in the ready (normal) state */
0108 int pvr2_hdw_dev_ok(struct pvr2_hdw *);
0109
0110 /* Return small integer number [1..N] for logical instance number of this
0111    device.  This is useful for indexing array-valued module parameters. */
0112 int pvr2_hdw_get_unit_number(struct pvr2_hdw *);
0113
0114 /* Get pointer to underlying USB device */
0115 struct usb_device *pvr2_hdw_get_dev(struct pvr2_hdw *);
0116
0117 /* Retrieve serial number of device */
0118 unsigned long pvr2_hdw_get_sn(struct pvr2_hdw *);
0119
0120 /* Retrieve bus location info of device */
0121 const char *pvr2_hdw_get_bus_info(struct pvr2_hdw *);
0122
0123 /* Retrieve per-instance string identifier for this specific device */
0124 const char *pvr2_hdw_get_device_identifier(struct pvr2_hdw *);
0125
0126 /* Called when hardware has been unplugged */
0127 void pvr2_hdw_disconnect(struct pvr2_hdw *);
0128
0129 /* Sets v4l2_dev of a video_device struct */
0130 void pvr2_hdw_set_v4l2_dev(struct pvr2_hdw *, struct video_device *);
0131
0132 /* Get the number of defined controls */
0133 unsigned int pvr2_hdw_get_ctrl_count(struct pvr2_hdw *);
0134
0135 /* Retrieve a control handle given its index (0..count-1) */
0136 struct pvr2_ctrl *pvr2_hdw_get_ctrl_by_index(struct pvr2_hdw *,unsigned int);
0137
0138 /* Retrieve a control handle given its internal ID (if any) */
0139 struct pvr2_ctrl *pvr2_hdw_get_ctrl_by_id(struct pvr2_hdw *,unsigned int);
0140
0141 /* Retrieve a control handle given its V4L ID (if any) */
0142 struct pvr2_ctrl *pvr2_hdw_get_ctrl_v4l(struct pvr2_hdw *,unsigned int ctl_id);
0143
0144 /* Retrieve a control handle given its immediate predecessor V4L ID (if any) */
0145 struct pvr2_ctrl *pvr2_hdw_get_ctrl_nextv4l(struct pvr2_hdw *,
0146                         unsigned int ctl_id);
0147
0148 /* Commit all control changes made up to this point */
0149 int pvr2_hdw_commit_ctl(struct pvr2_hdw *);
0150
0151 /* Return a bit mask of valid input selections for this device.  Mask bits
0152  * will be according to PVR_CVAL_INPUT_xxxx definitions. */
0153 unsigned int pvr2_hdw_get_input_available(struct pvr2_hdw *);
0154
0155 /* Return a bit mask of allowed input selections for this device.  Mask bits
0156  * will be according to PVR_CVAL_INPUT_xxxx definitions. */
0157 unsigned int pvr2_hdw_get_input_allowed(struct pvr2_hdw *);
0158
0159 /* Change the set of allowed input selections for this device.  Both
0160    change_mask and change_valu are mask bits according to
0161    PVR_CVAL_INPUT_xxxx definitions.  The change_mask parameter indicate
0162    which settings are being changed and the change_val parameter indicates
0163    whether corresponding settings are being set or cleared. */
0164 int pvr2_hdw_set_input_allowed(struct pvr2_hdw *,
0165                    unsigned int change_mask,
0166                    unsigned int change_val);
0167
0168 /* Return name for this driver instance */
0169 const char *pvr2_hdw_get_driver_name(struct pvr2_hdw *);
0170
0171 /* Mark tuner status stale so that it will be re-fetched */
0172 void pvr2_hdw_execute_tuner_poll(struct pvr2_hdw *);
0173
0174 /* Return information about the tuner */
0175 int pvr2_hdw_get_tuner_status(struct pvr2_hdw *,struct v4l2_tuner *);
0176
0177 /* Return information about cropping capabilities */
0178 int pvr2_hdw_get_cropcap(struct pvr2_hdw *, struct v4l2_cropcap *);
0179
0180 /* Query device and see if it thinks it is on a high-speed USB link */
0181 int pvr2_hdw_is_hsm(struct pvr2_hdw *);
0182
0183 /* Return a string token representative of the hardware type */
0184 const char *pvr2_hdw_get_type(struct pvr2_hdw *);
0185
0186 /* Return a single line description of the hardware type */
0187 const char *pvr2_hdw_get_desc(struct pvr2_hdw *);
0188
0189 /* Turn streaming on/off */
0190 int pvr2_hdw_set_streaming(struct pvr2_hdw *,int);
0191
0192 /* Find out if streaming is on */
0193 int pvr2_hdw_get_streaming(struct pvr2_hdw *);
0194
0195 /* Retrieve driver overall state */
0196 int pvr2_hdw_get_state(struct pvr2_hdw *);
0197
0198 /* Configure the type of stream to generate */
0199 int pvr2_hdw_set_stream_type(struct pvr2_hdw *, enum pvr2_config);
0200
0201 /* Get handle to video output stream */
0202 struct pvr2_stream *pvr2_hdw_get_video_stream(struct pvr2_hdw *);
0203
0204 /* Enable / disable retrieval of CPU firmware or prom contents.  This must
0205    be enabled before pvr2_hdw_cpufw_get() will function.  Note that doing
0206    this may prevent the device from running (and leaving this mode may
0207    imply a device reset). */
0208 void pvr2_hdw_cpufw_set_enabled(struct pvr2_hdw *,
0209                 int mode, /* 0=8KB FX2, 1=16KB FX2, 2=PROM */
0210                 int enable_flag);
0211
0212 /* Return true if we're in a mode for retrieval CPU firmware */
0213 int pvr2_hdw_cpufw_get_enabled(struct pvr2_hdw *);
0214
0215 /* Retrieve a piece of the CPU's firmware at the given offset.  Return
0216    value is the number of bytes retrieved or zero if we're past the end or
0217    an error otherwise (e.g. if firmware retrieval is not enabled). */
0218 int pvr2_hdw_cpufw_get(struct pvr2_hdw *,unsigned int offs,
0219                char *buf,unsigned int cnt);
0220
0221 /* Retrieve a previously stored v4l minor device number */
0222 int pvr2_hdw_v4l_get_minor_number(struct pvr2_hdw *,enum pvr2_v4l_type index);
0223
0224 /* Store a v4l minor device number */
0225 void pvr2_hdw_v4l_store_minor_number(struct pvr2_hdw *,
0226                      enum pvr2_v4l_type index,int);
0227
0228 /* The following entry points are all lower level things you normally don't
0229    want to worry about. */
0230
0231 /* Issue a command and get a response from the device.  LOTS of higher
0232    level stuff is built on this. */
0233 int pvr2_send_request(struct pvr2_hdw *,
0234               void *write_ptr,unsigned int write_len,
0235               void *read_ptr,unsigned int read_len);
0236
0237 /* Slightly higher level device communication functions. */
0238 int pvr2_write_register(struct pvr2_hdw *, u16, u32);
0239
0240 /* Call if for any reason we can't talk to the hardware anymore - this will
0241    cause the driver to stop flailing on the device. */
0242 void pvr2_hdw_render_useless(struct pvr2_hdw *);
0243
0244 /* Set / clear 8051's reset bit */
0245 void pvr2_hdw_cpureset_assert(struct pvr2_hdw *,int);
0246
0247 /* Execute a USB-commanded device reset */
0248 void pvr2_hdw_device_reset(struct pvr2_hdw *);
0249
0250 /* Reset worker's error trapping circuit breaker */
0251 int pvr2_hdw_untrip(struct pvr2_hdw *);
0252
0253 /* Execute hard reset command (after this point it's likely that the
0254    encoder will have to be reconfigured).  This also clears the "useless"
0255    state. */
0256 int pvr2_hdw_cmd_deep_reset(struct pvr2_hdw *);
0257
0258 /* Execute simple reset command */
0259 int pvr2_hdw_cmd_powerup(struct pvr2_hdw *);
0260
0261 /* Order decoder to reset */
0262 int pvr2_hdw_cmd_decoder_reset(struct pvr2_hdw *);
0263
0264 /* Direct manipulation of GPIO bits */
0265 int pvr2_hdw_gpio_get_dir(struct pvr2_hdw *hdw,u32 *);
0266 int pvr2_hdw_gpio_get_out(struct pvr2_hdw *hdw,u32 *);
0267 int pvr2_hdw_gpio_get_in(struct pvr2_hdw *hdw,u32 *);
0268 int pvr2_hdw_gpio_chg_dir(struct pvr2_hdw *hdw,u32 msk,u32 val);
0269 int pvr2_hdw_gpio_chg_out(struct pvr2_hdw *hdw,u32 msk,u32 val);
0270
0271 /* This data structure is specifically for the next function... */
0272 struct pvr2_hdw_debug_info {
0273     int big_lock_held;
0274     int ctl_lock_held;
0275     int flag_disconnected;
0276     int flag_init_ok;
0277     int flag_ok;
0278     int fw1_state;
0279     int flag_decoder_missed;
0280     int flag_tripped;
0281     int state_encoder_ok;
0282     int state_encoder_run;
0283     int state_decoder_run;
0284     int state_decoder_ready;
0285     int state_usbstream_run;
0286     int state_decoder_quiescent;
0287     int state_pipeline_config;
0288     int state_pipeline_req;
0289     int state_pipeline_pause;
0290     int state_pipeline_idle;
0291     int cmd_debug_state;
0292     int cmd_debug_write_len;
0293     int cmd_debug_read_len;
0294     int cmd_debug_write_pend;
0295     int cmd_debug_read_pend;
0296     int cmd_debug_timeout;
0297     int cmd_debug_rstatus;
0298     int cmd_debug_wstatus;
0299     unsigned char cmd_code;
0300 };
0301
0302 /* Non-intrusively retrieve internal state info - this is useful for
0303    diagnosing lockups.  Note that this operation is completed without any
0304    kind of locking and so it is not atomic and may yield inconsistent
0305    results.  This is *purely* a debugging aid. */
0306 void pvr2_hdw_get_debug_info_unlocked(const struct pvr2_hdw *hdw,
0307                       struct pvr2_hdw_debug_info *);
0308
0309 /* Intrusively retrieve internal state info - this is useful for
0310    diagnosing overall driver state.  This operation synchronizes against
0311    the overall driver mutex - so if there are locking problems this will
0312    likely hang!  This is *purely* a debugging aid. */
0313 void pvr2_hdw_get_debug_info_locked(struct pvr2_hdw *hdw,
0314                     struct pvr2_hdw_debug_info *);
0315
0316 /* Report out several lines of text that describes driver internal state.
0317    Results are written into the passed-in buffer. */
0318 unsigned int pvr2_hdw_state_report(struct pvr2_hdw *hdw,
0319                    char *buf_ptr,unsigned int buf_size);
0320
0321 /* Cause modules to log their state once */
0322 void pvr2_hdw_trigger_module_log(struct pvr2_hdw *hdw);
0323
0324 /* Cause encoder firmware to be uploaded into the device.  This is normally
0325    done autonomously, but the interface is exported here because it is also
0326    a debugging aid. */
0327 int pvr2_upload_firmware2(struct pvr2_hdw *hdw);
0328
0329 #endif /* __PVRUSB2_HDW_H */