usb/pwc/pwc.h

0001 /* SPDX-License-Identifier: GPL-2.0-or-later */
0002 /* (C) 1999-2003 Nemosoft Unv.
0003    (C) 2004-2006 Luc Saillard (luc@saillard.org)
0004
0005    NOTE: this version of pwc is an unofficial (modified) release of pwc & pcwx
0006    driver and thus may have bugs that are not present in the original version.
0007    Please send bug reports and support requests to <luc@saillard.org>.
0008    The decompression routines have been implemented by reverse-engineering the
0009    Nemosoft binary pwcx module. Caveat emptor.
0010
0011 */
0012
0013 #ifndef PWC_H
0014 #define PWC_H
0015
0016 #include <linux/module.h>
0017 #include <linux/usb.h>
0018 #include <linux/spinlock.h>
0019 #include <linux/wait.h>
0020 #include <linux/mutex.h>
0021 #include <linux/mm.h>
0022 #include <linux/slab.h>
0023 #include <asm/errno.h>
0024 #include <linux/videodev2.h>
0025 #include <media/v4l2-common.h>
0026 #include <media/v4l2-device.h>
0027 #include <media/v4l2-ioctl.h>
0028 #include <media/v4l2-ctrls.h>
0029 #include <media/v4l2-fh.h>
0030 #include <media/v4l2-event.h>
0031 #include <media/videobuf2-v4l2.h>
0032 #include <media/videobuf2-vmalloc.h>
0033 #ifdef CONFIG_USB_PWC_INPUT_EVDEV
0034 #include <linux/input.h>
0035 #endif
0036 #include "pwc-dec1.h"
0037 #include "pwc-dec23.h"
0038
0039 /* Version block */
0040 #define PWC_VERSION "10.0.15"
0041 #define PWC_NAME    "pwc"
0042 #define PFX     PWC_NAME ": "
0043
0044
0045 /* Trace certain actions in the driver */
0046 #define PWC_DEBUG_LEVEL_MODULE  BIT(0)
0047 #define PWC_DEBUG_LEVEL_PROBE   BIT(1)
0048 #define PWC_DEBUG_LEVEL_OPEN    BIT(2)
0049 #define PWC_DEBUG_LEVEL_READ    BIT(3)
0050 #define PWC_DEBUG_LEVEL_MEMORY  BIT(4)
0051 #define PWC_DEBUG_LEVEL_FLOW    BIT(5)
0052 #define PWC_DEBUG_LEVEL_SIZE    BIT(6)
0053 #define PWC_DEBUG_LEVEL_IOCTL   BIT(7)
0054 #define PWC_DEBUG_LEVEL_TRACE   BIT(8)
0055
0056 #define PWC_DEBUG_MODULE(fmt, args...) PWC_DEBUG(MODULE, fmt, ##args)
0057 #define PWC_DEBUG_PROBE(fmt, args...) PWC_DEBUG(PROBE, fmt, ##args)
0058 #define PWC_DEBUG_OPEN(fmt, args...) PWC_DEBUG(OPEN, fmt, ##args)
0059 #define PWC_DEBUG_READ(fmt, args...) PWC_DEBUG(READ, fmt, ##args)
0060 #define PWC_DEBUG_MEMORY(fmt, args...) PWC_DEBUG(MEMORY, fmt, ##args)
0061 #define PWC_DEBUG_FLOW(fmt, args...) PWC_DEBUG(FLOW, fmt, ##args)
0062 #define PWC_DEBUG_SIZE(fmt, args...) PWC_DEBUG(SIZE, fmt, ##args)
0063 #define PWC_DEBUG_IOCTL(fmt, args...) PWC_DEBUG(IOCTL, fmt, ##args)
0064 #define PWC_DEBUG_TRACE(fmt, args...) PWC_DEBUG(TRACE, fmt, ##args)
0065
0066
0067 #ifdef CONFIG_USB_PWC_DEBUG
0068
0069 #define PWC_DEBUG_LEVEL (PWC_DEBUG_LEVEL_MODULE)
0070
0071 #define PWC_DEBUG(level, fmt, args...) do {\
0072     if ((PWC_DEBUG_LEVEL_ ##level) & pwc_trace) \
0073         printk(KERN_DEBUG PFX fmt, ##args); \
0074     } while (0)
0075
0076 #define PWC_ERROR(fmt, args...) printk(KERN_ERR PFX fmt, ##args)
0077 #define PWC_WARNING(fmt, args...) printk(KERN_WARNING PFX fmt, ##args)
0078 #define PWC_INFO(fmt, args...) printk(KERN_INFO PFX fmt, ##args)
0079 #define PWC_TRACE(fmt, args...) PWC_DEBUG(TRACE, fmt, ##args)
0080
0081 #else /* if ! CONFIG_USB_PWC_DEBUG */
0082
0083 #define PWC_ERROR(fmt, args...) printk(KERN_ERR PFX fmt, ##args)
0084 #define PWC_WARNING(fmt, args...) printk(KERN_WARNING PFX fmt, ##args)
0085 #define PWC_INFO(fmt, args...) printk(KERN_INFO PFX fmt, ##args)
0086 #define PWC_TRACE(fmt, args...) do { } while(0)
0087 #define PWC_DEBUG(level, fmt, args...) do { } while(0)
0088
0089 #define pwc_trace 0
0090
0091 #endif
0092
0093 /* Defines for ToUCam cameras */
0094 #define TOUCAM_HEADER_SIZE      8
0095 #define TOUCAM_TRAILER_SIZE     4
0096
0097 #define FEATURE_MOTOR_PANTILT       0x0001
0098 #define FEATURE_CODEC1          0x0002
0099 #define FEATURE_CODEC2          0x0004
0100
0101 #define MAX_WIDTH       640
0102 #define MAX_HEIGHT      480
0103
0104 /* Ignore errors in the first N frames, to allow for startup delays */
0105 #define FRAME_LOWMARK 5
0106
0107 /* Size and number of buffers for the ISO pipe. */
0108 #define MAX_ISO_BUFS        3
0109 #define ISO_FRAMES_PER_DESC 10
0110 #define ISO_MAX_FRAME_SIZE  960
0111 #define ISO_BUFFER_SIZE     (ISO_FRAMES_PER_DESC * ISO_MAX_FRAME_SIZE)
0112
0113 /* Maximum size after decompression is 640x480 YUV data, 1.5 * 640 * 480 */
0114 #define PWC_FRAME_SIZE      (460800 + TOUCAM_HEADER_SIZE + TOUCAM_TRAILER_SIZE)
0115
0116 /* Absolute minimum and maximum number of buffers available for mmap() */
0117 #define MIN_FRAMES      2
0118 #define MAX_FRAMES      16
0119
0120 /* Some macros to quickly find the type of a webcam */
0121 #define DEVICE_USE_CODEC1(x) ((x)<675)
0122 #define DEVICE_USE_CODEC2(x) ((x)>=675 && (x)<700)
0123 #define DEVICE_USE_CODEC3(x) ((x)>=700)
0124 #define DEVICE_USE_CODEC23(x) ((x)>=675)
0125
0126 /* Request types: video */
0127 #define SET_LUM_CTL         0x01
0128 #define GET_LUM_CTL         0x02
0129 #define SET_CHROM_CTL           0x03
0130 #define GET_CHROM_CTL           0x04
0131 #define SET_STATUS_CTL          0x05
0132 #define GET_STATUS_CTL          0x06
0133 #define SET_EP_STREAM_CTL       0x07
0134 #define GET_EP_STREAM_CTL       0x08
0135 #define GET_XX_CTL          0x09
0136 #define SET_XX_CTL          0x0A
0137 #define GET_XY_CTL          0x0B
0138 #define SET_XY_CTL          0x0C
0139 #define SET_MPT_CTL         0x0D
0140 #define GET_MPT_CTL         0x0E
0141
0142 /* Selectors for the Luminance controls [GS]ET_LUM_CTL */
0143 #define AGC_MODE_FORMATTER          0x2000
0144 #define PRESET_AGC_FORMATTER            0x2100
0145 #define SHUTTER_MODE_FORMATTER          0x2200
0146 #define PRESET_SHUTTER_FORMATTER        0x2300
0147 #define PRESET_CONTOUR_FORMATTER        0x2400
0148 #define AUTO_CONTOUR_FORMATTER          0x2500
0149 #define BACK_LIGHT_COMPENSATION_FORMATTER   0x2600
0150 #define CONTRAST_FORMATTER          0x2700
0151 #define DYNAMIC_NOISE_CONTROL_FORMATTER     0x2800
0152 #define FLICKERLESS_MODE_FORMATTER      0x2900
0153 #define AE_CONTROL_SPEED            0x2A00
0154 #define BRIGHTNESS_FORMATTER            0x2B00
0155 #define GAMMA_FORMATTER             0x2C00
0156
0157 /* Selectors for the Chrominance controls [GS]ET_CHROM_CTL */
0158 #define WB_MODE_FORMATTER           0x1000
0159 #define AWB_CONTROL_SPEED_FORMATTER     0x1100
0160 #define AWB_CONTROL_DELAY_FORMATTER     0x1200
0161 #define PRESET_MANUAL_RED_GAIN_FORMATTER    0x1300
0162 #define PRESET_MANUAL_BLUE_GAIN_FORMATTER   0x1400
0163 #define COLOUR_MODE_FORMATTER           0x1500
0164 #define SATURATION_MODE_FORMATTER1      0x1600
0165 #define SATURATION_MODE_FORMATTER2      0x1700
0166
0167 /* Selectors for the Status controls [GS]ET_STATUS_CTL */
0168 #define SAVE_USER_DEFAULTS_FORMATTER        0x0200
0169 #define RESTORE_USER_DEFAULTS_FORMATTER     0x0300
0170 #define RESTORE_FACTORY_DEFAULTS_FORMATTER  0x0400
0171 #define READ_AGC_FORMATTER          0x0500
0172 #define READ_SHUTTER_FORMATTER          0x0600
0173 #define READ_RED_GAIN_FORMATTER         0x0700
0174 #define READ_BLUE_GAIN_FORMATTER        0x0800
0175
0176 /* Formatters for the motorized pan & tilt [GS]ET_MPT_CTL */
0177 #define PT_RELATIVE_CONTROL_FORMATTER       0x01
0178 #define PT_RESET_CONTROL_FORMATTER      0x02
0179 #define PT_STATUS_FORMATTER         0x03
0180
0181 /* Enumeration of image sizes */
0182 #define PSZ_SQCIF   0x00
0183 #define PSZ_QSIF    0x01
0184 #define PSZ_QCIF    0x02
0185 #define PSZ_SIF     0x03
0186 #define PSZ_CIF     0x04
0187 #define PSZ_VGA     0x05
0188 #define PSZ_MAX     6
0189
0190 struct pwc_raw_frame {
0191     __le16 type;        /* type of the webcam */
0192     __le16 vbandlength; /* Size of 4 lines compressed (used by the
0193                    decompressor) */
0194     __u8   cmd[4];      /* the four byte of the command (in case of
0195                    nala, only the first 3 bytes is filled) */
0196     __u8   rawframe[];  /* frame_size = H / 4 * vbandlength */
0197 } __packed;
0198
0199 /* intermediate buffers with raw data from the USB cam */
0200 struct pwc_frame_buf
0201 {
0202     /* common v4l buffer stuff -- must be first */
0203     struct vb2_v4l2_buffer vb;
0204     struct list_head list;
0205     void *data;
0206     int filled;     /* number of bytes filled */
0207 };
0208
0209 struct pwc_device
0210 {
0211     struct video_device vdev;
0212     struct v4l2_device v4l2_dev;
0213
0214     /* videobuf2 queue and queued buffers list */
0215     struct vb2_queue vb_queue;
0216     struct list_head queued_bufs;
0217     spinlock_t queued_bufs_lock; /* Protects queued_bufs */
0218
0219     /* If taking both locks vb_queue_lock must always be locked first! */
0220     struct mutex v4l2_lock;      /* Protects everything else */
0221     struct mutex vb_queue_lock;  /* Protects vb_queue and capt_file */
0222
0223     /* Pointer to our usb_device, will be NULL after unplug */
0224     struct usb_device *udev; /* Both mutexes most be hold when setting! */
0225
0226     /* type of cam (645, 646, 675, 680, 690, 720, 730, 740, 750) */
0227     int type;
0228     int release;        /* release number */
0229     int features;       /* feature bits */
0230
0231     /*** Video data ***/
0232     int vendpoint;      /* video isoc endpoint */
0233     int vcinterface;    /* video control interface */
0234     int valternate;     /* alternate interface needed */
0235     int vframes;        /* frames-per-second */
0236     int pixfmt;     /* pixelformat: V4L2_PIX_FMT_YUV420 or _PWCX */
0237     int vframe_count;   /* received frames */
0238     int vmax_packet_size;   /* USB maxpacket size */
0239     int vlast_packet_size;  /* for frame synchronisation */
0240     int visoc_errors;   /* number of contiguous ISOC errors */
0241     int vbandlength;    /* compressed band length; 0 is uncompressed */
0242     char vsync;     /* used by isoc handler */
0243     char vmirror;       /* for ToUCaM series */
0244     char power_save;    /* Do powersaving for this cam */
0245
0246     unsigned char cmd_buf[13];
0247     unsigned char *ctrl_buf;
0248
0249     struct urb *urbs[MAX_ISO_BUFS];
0250
0251     /*
0252      * Frame currently being filled, this only gets touched by the
0253      * isoc urb complete handler, and by stream start / stop since
0254      * start / stop touch it before / after starting / killing the urbs
0255      * no locking is needed around this
0256      */
0257     struct pwc_frame_buf *fill_buf;
0258
0259     int frame_header_size, frame_trailer_size;
0260     int frame_size;
0261     int frame_total_size;   /* including header & trailer */
0262     int drop_frames;
0263
0264     union { /* private data for decompression engine */
0265         struct pwc_dec1_private dec1;
0266         struct pwc_dec23_private dec23;
0267     };
0268
0269     /*
0270      * We have an 'image' and a 'view', where 'image' is the fixed-size img
0271      * as delivered by the camera, and 'view' is the size requested by the
0272      * program. The camera image is centered in this viewport, laced with
0273      * a gray or black border. view_min <= image <= view <= view_max;
0274      */
0275     int image_mask;             /* supported sizes */
0276     int width, height;          /* current resolution */
0277
0278 #ifdef CONFIG_USB_PWC_INPUT_EVDEV
0279     struct input_dev *button_dev;   /* webcam snapshot button input */
0280     char button_phys[64];
0281 #endif
0282
0283     /* controls */
0284     struct v4l2_ctrl_handler    ctrl_handler;
0285     u16             saturation_fmt;
0286     struct v4l2_ctrl        *brightness;
0287     struct v4l2_ctrl        *contrast;
0288     struct v4l2_ctrl        *saturation;
0289     struct v4l2_ctrl        *gamma;
0290     struct {
0291         /* awb / red-blue balance cluster */
0292         struct v4l2_ctrl    *auto_white_balance;
0293         struct v4l2_ctrl    *red_balance;
0294         struct v4l2_ctrl    *blue_balance;
0295         /* usb ctrl transfers are slow, so we cache things */
0296         int         color_bal_valid;
0297         unsigned long       last_color_bal_update; /* In jiffies */
0298         s32         last_red_balance;
0299         s32         last_blue_balance;
0300     };
0301     struct {
0302         /* autogain / gain cluster */
0303         struct v4l2_ctrl    *autogain;
0304         struct v4l2_ctrl    *gain;
0305         int         gain_valid;
0306         unsigned long       last_gain_update; /* In jiffies */
0307         s32         last_gain;
0308     };
0309     struct {
0310         /* exposure_auto / exposure cluster */
0311         struct v4l2_ctrl    *exposure_auto;
0312         struct v4l2_ctrl    *exposure;
0313         int         exposure_valid;
0314         unsigned long       last_exposure_update; /* In jiffies */
0315         s32         last_exposure;
0316     };
0317     struct v4l2_ctrl        *colorfx;
0318     struct {
0319         /* autocontour/contour cluster */
0320         struct v4l2_ctrl    *autocontour;
0321         struct v4l2_ctrl    *contour;
0322     };
0323     struct v4l2_ctrl        *backlight;
0324     struct v4l2_ctrl        *flicker;
0325     struct v4l2_ctrl        *noise_reduction;
0326     struct v4l2_ctrl        *save_user;
0327     struct v4l2_ctrl        *restore_user;
0328     struct v4l2_ctrl        *restore_factory;
0329     struct v4l2_ctrl        *awb_speed;
0330     struct v4l2_ctrl        *awb_delay;
0331     struct {
0332         /* motor control cluster */
0333         struct v4l2_ctrl    *motor_pan;
0334         struct v4l2_ctrl    *motor_tilt;
0335         struct v4l2_ctrl    *motor_pan_reset;
0336         struct v4l2_ctrl    *motor_tilt_reset;
0337     };
0338     /* CODEC3 models have both gain and exposure controlled by autogain */
0339     struct v4l2_ctrl        *autogain_expo_cluster[3];
0340 };
0341
0342 /* Global variables */
0343 #ifdef CONFIG_USB_PWC_DEBUG
0344 extern int pwc_trace;
0345 #endif
0346
0347 /** Functions in pwc-misc.c */
0348 /* sizes in pixels */
0349 extern const int pwc_image_sizes[PSZ_MAX][2];
0350
0351 int pwc_get_size(struct pwc_device *pdev, int width, int height);
0352 void pwc_construct(struct pwc_device *pdev);
0353
0354 /** Functions in pwc-ctrl.c */
0355 /* Request a certain video mode. Returns < 0 if not possible */
0356 extern int pwc_set_video_mode(struct pwc_device *pdev, int width, int height,
0357     int pixfmt, int frames, int *compression, int send_to_cam);
0358 extern unsigned int pwc_get_fps(struct pwc_device *pdev, unsigned int index, unsigned int size);
0359 extern int pwc_set_leds(struct pwc_device *pdev, int on_value, int off_value);
0360 extern int pwc_get_cmos_sensor(struct pwc_device *pdev, int *sensor);
0361 extern int send_control_msg(struct pwc_device *pdev,
0362                 u8 request, u16 value, void *buf, int buflen);
0363
0364 /* Control get / set helpers */
0365 int pwc_get_u8_ctrl(struct pwc_device *pdev, u8 request, u16 value, int *data);
0366 int pwc_set_u8_ctrl(struct pwc_device *pdev, u8 request, u16 value, u8 data);
0367 int pwc_get_s8_ctrl(struct pwc_device *pdev, u8 request, u16 value, int *data);
0368 #define pwc_set_s8_ctrl pwc_set_u8_ctrl
0369 int pwc_get_u16_ctrl(struct pwc_device *pdev, u8 request, u16 value, int *dat);
0370 int pwc_set_u16_ctrl(struct pwc_device *pdev, u8 request, u16 value, u16 data);
0371 int pwc_button_ctrl(struct pwc_device *pdev, u16 value);
0372 int pwc_init_controls(struct pwc_device *pdev);
0373
0374 /* Power down or up the camera; not supported by all models */
0375 extern void pwc_camera_power(struct pwc_device *pdev, int power);
0376
0377 extern const struct v4l2_ioctl_ops pwc_ioctl_ops;
0378
0379 /** pwc-uncompress.c */
0380 /* Expand frame to image, possibly including decompression. Uses read_frame and fill_image */
0381 int pwc_decompress(struct pwc_device *pdev, struct pwc_frame_buf *fbuf);
0382
0383 #endif