app/src/main/jni/libuvc/include/libuvc/libuvc_internal.h

   1 /** @file libuvc_internal.h
   2   * @brief Implementation-specific UVC constants and structures.
   3   * @cond include_hidden
   4   */
   5 #ifndef LIBUVC_INTERNAL_H
   6 #define LIBUVC_INTERNAL_H
   7
   8 #include <assert.h>
   9 #include <stdlib.h>
  10 #include <stdio.h>
  11 #include <string.h>
  12 #include <pthread.h>
  13 #include <signal.h>
  14 #include "utilbase.h"
  15 #include "utlist.h"
  16 #ifdef __ANDROID__
  17 #include <android/log.h>
  18 #endif
  19
  20 //#define UVC_DEBUGGING
  21
  22 #define MIN(a, b) ((a) < (b) ? (a) : (b))
  23 #define MAX(a, b) ((a) > (b) ? (a) : (b))
  24
  25 /** Converts an unaligned 8-byte little-endian integer into an int64 */
  26 #define QW_TO_LONG(p) \
  27  ((p)[0] | ((p)[1] << 8) | ((p)[2] << 16) | ((p)[3] << 24) \
  28   | ((uint64_t)(p)[4] << 32) | ((uint64_t)(p)[5] << 40) \
  29   | ((uint64_t)(p)[6] << 48) | ((uint64_t)(p)[7] << 56))
  30 /** Converts an unaligned four-byte little-endian integer into an int32 */
  31 #define DW_TO_INT(p) ((p)[0] | ((p)[1] << 8) | ((p)[2] << 16) | ((p)[3] << 24))
  32 /** Converts an unaligned four-byte little-endian integer into an signed int32 */
  33 /** Converts an unaligned two-byte little-endian integer into an int16 */
  34 #define SW_TO_SHORT(p) ((p)[0] | ((p)[1] << 8))
  35 /** Converts an unaligned two-byte little-endian integer into an int16 as a signed value */
  36 /** Converts an int16 into an unaligned two-byte little-endian integer */
  37 #define SHORT_TO_SW(s, p) \
  38   (p)[0] = (s); \
  39   (p)[1] = (s) >> 8;
  40 /** Converts an int32 into an unaligned four-byte little-endian integer */
  41 #define INT_TO_DW(i, p) \
  42   (p)[0] = (i); \
  43   (p)[1] = (i) >> 8; \
  44   (p)[2] = (i) >> 16; \
  45   (p)[3] = (i) >> 24;
  46 /** Converts an int64 into an unaligned 8-byte little-endian integer */
  47 #define LONG_TO_QW(i, p) \
  48   (p)[0] = (i); \
  49   (p)[1] = (i) >> 8; \
  50   (p)[2] = (i) >> 16; \
  51   (p)[3] = (i) >> 24; \
  52   (p)[4] = (i) >> 32; \
  53   (p)[5] = (i) >> 40; \
  54   (p)[6] = (i) >> 48; \
  55   (p)[7] = (i) >> 56;
  56
  57
  58 /** Selects the nth item in a doubly linked list. n=-1 selects the last item. */
  59 #define DL_NTH(head, out, n) \
  60   do { \
  61     int dl_nth_i = 0; \
  62     LDECLTYPE(head) dl_nth_p = (head); \
  63     if ((n) < 0) { \
  64       while (dl_nth_p && dl_nth_i > (n)) { \
  65         dl_nth_p = dl_nth_p->prev; \
  66         dl_nth_i--; \
  67       } \
  68     } else { \
  69       while (dl_nth_p && dl_nth_i < (n)) { \
  70         dl_nth_p = dl_nth_p->next; \
  71         dl_nth_i++; \
  72       } \
  73     } \
  74     (out) = dl_nth_p; \
  75   } while (0);
  76
  77 #ifdef UVC_DEBUGGING
  78 #include <libgen.h>
  79 #ifdef __ANDROID__      // add for android saki@sereneginat
  80         #define UVC_DEBUG(...) __android_log_print(ANDROID_LOG_ERROR, "UVC", __VA_ARGS__)
  81         #define UVC_ENTER() __android_log_print(ANDROID_LOG_ERROR, "UVC", "[%s:%d] begin %s", basename(__FILE__), __LINE__, __FUNCTION__)
  82         #define UVC_EXIT(code) __android_log_print(ANDROID_LOG_ERROR, "UVC", "[%s:%d] end %s (%d)", basename(__FILE__), __LINE__, __FUNCTION__, code)
  83         #define UVC_EXIT_VOID() __android_log_print(ANDROID_LOG_ERROR, "UVC", "[%s:%d] end %s", basename(__FILE__), __LINE__, __FUNCTION__)
  84 #else
  85         #define UVC_DEBUG(format, ...) fprintf(stderr, "[%s:%d/%s] " format "\n", basename(__FILE__), __LINE__, __FUNCTION__, ##__VA_ARGS__)
  86         #define UVC_ENTER() fprintf(stderr, "[%s:%d] begin %s\n", basename(__FILE__), __LINE__, __FUNCTION__)
  87         #define UVC_EXIT(code) fprintf(stderr, "[%s:%d] end %s (%d)\n", basename(__FILE__), __LINE__, __FUNCTION__, code)
  88         #define UVC_EXIT_VOID() fprintf(stderr, "[%s:%d] end %s\n", basename(__FILE__), __LINE__, __FUNCTION__)
  89 #endif
  90 #else
  91         #define UVC_DEBUG(...)
  92         #define UVC_ENTER()
  93         #define UVC_EXIT(code)
  94         #define UVC_EXIT_VOID()
  95 #endif
  96
  97 /* http://stackoverflow.com/questions/19452971/array-size-macro-that-rejects-pointers */
  98 #define IS_INDEXABLE(arg) (sizeof(arg[0]))
  99 #define IS_ARRAY(arg) (IS_INDEXABLE(arg) && (((void *) &arg) == ((void *) arg)))
 100 #define ARRAYSIZE(arr) (sizeof(arr) / (IS_ARRAY(arr) ? sizeof(arr[0]) : 0))
 101
 102 /** Video interface subclass code (A.2) */
 103 enum uvc_int_subclass_code {
 104   UVC_SC_UNDEFINED = 0x00,
 105   UVC_SC_VIDEOCONTROL = 0x01,
 106   UVC_SC_VIDEOSTREAMING = 0x02,
 107   UVC_SC_VIDEO_INTERFACE_COLLECTION = 0x03
 108 };
 109
 110 /** Video interface protocol code (A.3) */
 111 enum uvc_int_proto_code {
 112   UVC_PC_PROTOCOL_UNDEFINED = 0x00
 113 };
 114
 115 /** VideoControl interface descriptor subtype (A.5) */
 116 enum uvc_vc_desc_subtype {
 117   UVC_VC_DESCRIPTOR_UNDEFINED = 0x00,
 118   UVC_VC_HEADER = 0x01,
 119   UVC_VC_INPUT_TERMINAL = 0x02,
 120   UVC_VC_OUTPUT_TERMINAL = 0x03,
 121   UVC_VC_SELECTOR_UNIT = 0x04,
 122   UVC_VC_PROCESSING_UNIT = 0x05,
 123   UVC_VC_EXTENSION_UNIT = 0x06
 124 };
 125
 126 /** UVC endpoint descriptor subtype (A.7) */
 127 enum uvc_ep_desc_subtype {
 128   UVC_EP_UNDEFINED = 0x00,
 129   UVC_EP_GENERAL = 0x01,
 130   UVC_EP_ENDPOINT = 0x02,
 131   UVC_EP_INTERRUPT = 0x03
 132 };
 133
 134 /** VideoControl interface control selector (A.9.1) */
 135 enum uvc_vc_ctrl_selector {
 136   UVC_VC_CONTROL_UNDEFINED = 0x00,
 137   UVC_VC_VIDEO_POWER_MODE_CONTROL = 0x01,
 138   UVC_VC_REQUEST_ERROR_CODE_CONTROL = 0x02
 139 };
 140
 141 /** Terminal control selector (A.9.2) */
 142 enum uvc_term_ctrl_selector {
 143   UVC_TE_CONTROL_UNDEFINED = 0x00
 144 };
 145
 146 /** Selector unit control selector (A.9.3) */
 147 enum uvc_su_ctrl_selector {
 148   UVC_SU_CONTROL_UNDEFINED = 0x00,
 149   UVC_SU_INPUT_SELECT_CONTROL = 0x01
 150 };
 151
 152 /** Extension unit control selector (A.9.6) */
 153 enum uvc_xu_ctrl_selector {
 154   UVC_XU_CONTROL_UNDEFINED = 0x00
 155 };
 156
 157 /** VideoStreaming interface control selector (A.9.7) */
 158 enum uvc_vs_ctrl_selector {
 159   UVC_VS_CONTROL_UNDEFINED = 0x00,
 160   UVC_VS_PROBE_CONTROL = 0x01,
 161   UVC_VS_COMMIT_CONTROL = 0x02,
 162   UVC_VS_STILL_PROBE_CONTROL = 0x03,
 163   UVC_VS_STILL_COMMIT_CONTROL = 0x04,
 164   UVC_VS_STILL_IMAGE_TRIGGER_CONTROL = 0x05,
 165   UVC_VS_STREAM_ERROR_CODE_CONTROL = 0x06,
 166   UVC_VS_GENERATE_KEY_FRAME_CONTROL = 0x07,
 167   UVC_VS_UPDATE_FRAME_SEGMENT_CONTROL = 0x08,
 168   UVC_VS_SYNC_DELAY_CONTROL = 0x09
 169 };
 170
 171 /** Status packet type (2.4.2.2) */
 172 enum uvc_status_type {
 173   UVC_STATUS_TYPE_CONTROL = 1,
 174   UVC_STATUS_TYPE_STREAMING = 2
 175 };
 176
 177 /** Payload header flags (2.4.3.3) */
 178 #define UVC_STREAM_EOH (1 << 7)
 179 #define UVC_STREAM_ERR (1 << 6)
 180 #define UVC_STREAM_STI (1 << 5)
 181 #define UVC_STREAM_RES (1 << 4)
 182 #define UVC_STREAM_SCR (1 << 3)
 183 #define UVC_STREAM_PTS (1 << 2)
 184 #define UVC_STREAM_EOF (1 << 1)
 185 #define UVC_STREAM_FID (1 << 0)
 186
 187 /** Control capabilities (4.1.2) */
 188 #define UVC_CONTROL_CAP_GET (1 << 0)
 189 #define UVC_CONTROL_CAP_SET (1 << 1)
 190 #define UVC_CONTROL_CAP_DISABLED (1 << 2)
 191 #define UVC_CONTROL_CAP_AUTOUPDATE (1 << 3)
 192 #define UVC_CONTROL_CAP_ASYNCHRONOUS (1 << 4)
 193
 194 struct uvc_streaming_interface;
 195 struct uvc_device_info;
 196
 197 /** VideoStream interface */
 198 typedef struct uvc_streaming_interface {
 199   struct uvc_device_info *parent;
 200   struct uvc_streaming_interface *prev, *next;
 201   /** Interface number */
 202   uint8_t bInterfaceNumber;
 203   /** Video formats that this interface provides */
 204   struct uvc_format_desc *format_descs;
 205   /** USB endpoint to use when communicating with this interface */
 206   uint8_t bEndpointAddress;
 207   uint8_t bTerminalLink;
 208   uint8_t bmInfo;       // XXX
 209   uint8_t bStillCaptureMethod;  // XXX
 210   uint8_t bTriggerSupport;      // XXX
 211   uint8_t bTriggerUsage;        // XXX
 212   uint64_t *bmaControls;        // XXX
 213 } uvc_streaming_interface_t;
 214
 215 /** VideoControl interface */
 216 typedef struct uvc_control_interface {
 217   struct uvc_device_info *parent;
 218   struct uvc_input_terminal *input_term_descs;
 219   struct uvc_output_terminal *output_term_descs;
 220   struct uvc_processing_unit *processing_unit_descs;
 221   struct uvc_extension_unit *extension_unit_descs;
 222   uint16_t bcdUVC;
 223   uint8_t bEndpointAddress;
 224   /** Interface number */
 225   uint8_t bInterfaceNumber;
 226 } uvc_control_interface_t;
 227
 228 struct uvc_stream_ctrl;
 229
 230 struct uvc_device {
 231   struct uvc_context *ctx;
 232   int ref;
 233   libusb_device *usb_dev;
 234 };
 235
 236 typedef struct uvc_device_info {
 237   /** Configuration descriptor for USB device */
 238   struct libusb_config_descriptor *config;
 239   /** VideoControl interface provided by device */
 240   uvc_control_interface_t ctrl_if;
 241   /** VideoStreaming interfaces on the device */
 242   uvc_streaming_interface_t *stream_ifs;
 243 } uvc_device_info_t;
 244
 245 /*
 246   set a high number of transfer buffers. This uses a lot of ram, but
 247   avoids problems with scheduling delays on slow boards causing missed
 248   transfers. A better approach may be to make the transfer thread FIFO
 249   scheduled (if we have root).
 250   We could/should change this to allow reduce it to, say, 5 by default
 251   and then allow the user to change the number of buffers as required.
 252  */
 253 #define LIBUVC_NUM_TRANSFER_BUFS 10
 254
 255 #define LIBUVC_XFER_BUF_SIZE    ( 16 * 1024 * 1024 )
 256
 257 struct uvc_stream_handle {
 258   struct uvc_device_handle *devh;
 259   struct uvc_stream_handle *prev, *next;
 260   struct uvc_streaming_interface *stream_if;
 261
 262   /** if true, stream is running (streaming video to host) */
 263   uint8_t running;
 264   /** Current control block */
 265   struct uvc_stream_ctrl cur_ctrl;
 266
 267   /* listeners may only access hold*, and only when holding a
 268    * lock on cb_mutex (probably signaled with cb_cond) */
 269   uint8_t bfh_err, hold_bfh_err;        // XXX added to keep UVC_STREAM_ERR
 270   uint8_t fid;
 271   uint32_t seq, hold_seq;
 272   uint32_t pts, hold_pts;
 273   uint32_t last_scr, hold_last_scr;
 274   size_t got_bytes, hold_bytes;
 275   size_t size_buf;      // XXX add for boundary check
 276   uint8_t *outbuf, *holdbuf;
 277   pthread_mutex_t cb_mutex;
 278   pthread_cond_t cb_cond;
 279   pthread_t cb_thread;
 280   uint32_t last_polled_seq;
 281   uvc_frame_callback_t *user_cb;
 282   void *user_ptr;
 283   struct libusb_transfer *transfers[LIBUVC_NUM_TRANSFER_BUFS];
 284   uint8_t *transfer_bufs[LIBUVC_NUM_TRANSFER_BUFS];
 285   struct uvc_frame frame;
 286   enum uvc_frame_format frame_format;
 287 };
 288
 289 /** Handle on an open UVC device
 290  *
 291  * @todo move most of this into a uvc_device struct?
 292  */
 293 struct uvc_device_handle {
 294   struct uvc_device *dev;
 295   struct uvc_device_handle *prev, *next;
 296   /** Underlying USB device handle */
 297   libusb_device_handle *usb_devh;
 298   struct uvc_device_info *info;
 299   struct libusb_transfer *status_xfer;
 300   pthread_mutex_t status_mutex; // XXX saki
 301   uint8_t status_buf[32];
 302   /** Function to call when we receive status updates from the camera */
 303   uvc_status_callback_t *status_cb;
 304   void *status_user_ptr;
 305   /** Function to call when we receive button events from the camera */
 306   uvc_button_callback_t *button_cb;
 307   void *button_user_ptr;
 308
 309   uvc_stream_handle_t *streams;
 310   /** Whether the camera is an iSight that sends one header per frame */
 311   uint8_t is_isight;
 312   uint8_t reset_on_release_if;  // XXX whether interface alt setting needs to reset to 0.
 313 };
 314
 315 /** Context within which we communicate with devices */
 316 struct uvc_context {
 317   /** Underlying context for USB communication */
 318   struct libusb_context *usb_ctx;
 319   /** True if libuvc initialized the underlying USB context */
 320   uint8_t own_usb_ctx;
 321   /** List of open devices in this context */
 322   uvc_device_handle_t *open_devices;
 323   pthread_t handler_thread;
 324   uint8_t kill_handler_thread;
 325 };
 326
 327 uvc_error_t uvc_query_stream_ctrl(
 328     uvc_device_handle_t *devh,
 329     uvc_stream_ctrl_t *ctrl,
 330     uint8_t probe,
 331     enum uvc_req_code req);
 332
 333 void uvc_start_handler_thread(uvc_context_t *ctx);
 334 uvc_error_t uvc_claim_if(uvc_device_handle_t *devh, int idx);
 335 uvc_error_t uvc_release_if(uvc_device_handle_t *devh, int idx);
 336
 337 #endif // !def(LIBUVC_INTERNAL_H)
 338 /** @endcond */
 339