usbtwod.h

Go to the documentation of this file.

/* -*- mode: C; indent-tabs-mode: nil; c-basic-offset: 8; tab-width: 8; -*- */
/* vim: set shiftwidth=8 softtabstop=8 expandtab: */
/*
 ********************************************************************
 ** NIDAS: NCAR In-situ Data Acquistion Software
 **
 ** 2007, Copyright University Corporation for Atmospheric Research
 **
 ** This program is free software; you can redistribute it and/or modify
 ** it under the terms of the GNU General Public License as published by
 ** the Free Software Foundation; either version 2 of the License, or
 ** (at your option) any later version.
 **
 ** This program is distributed in the hope that it will be useful,
 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ** GNU General Public License for more details.
 **
 ** The LICENSE.txt file accompanying this software contains
 ** a copy of the GNU General Public License. If it is not found,
 ** write to the Free Software Foundation, Inc.,
 ** 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 **
 ********************************************************************
*/

#ifndef _nidas_usbtwod_h_
#define _nidas_usbtwod_h_

#include <nidas/linux/types.h>

#ifndef __KERNEL__
/* User programs need this for the _IO macros, but kernel
 * modules get their's elsewhere.
 */
#include <sys/ioctl.h>
#include <sys/types.h>
#include <errno.h>
#endif

#include <nidas/linux/util.h>

struct usb_twod_stats
{
        unsigned int numImages;
        unsigned int lostImages;
        unsigned int numSORs;
        unsigned int lostSORs;
        unsigned int lostTASs;
        unsigned int urbErrors;
        unsigned int urbTimeouts;
};

typedef struct _Tap2D_v1
{
        unsigned char ntap;
        unsigned char div10;
        unsigned char cntr;
        unsigned char dummy;
} Tap2Dv1;

typedef struct _Tap2D_v2
{
        unsigned short ntap;
        unsigned char div10;

        unsigned char cntr;
} Tap2D;

/*
 * Believe this struct is unnecessary
 */
typedef struct _Tap2D_v3
{
        unsigned short tas;
        unsigned short probeResolution;
} Tap2D_v3;

/* Pick a character as the magic number of your driver.
 * It isn't strictly necessary that it be distinct between
 * all modules on the system, but is a good idea. With
 * distinct magic numbers one can catch a user sending
 * an ioctl to the wrong device.
 */
#define USB2D_IOC_MAGIC 0x2d

#define USB2D_SET_TAS       _IOW(USB2D_IOC_MAGIC,0,Tap2D)
#define USB2D_SET_SOR_RATE  _IOW(USB2D_IOC_MAGIC,1,int)
#define USB2D_GET_STATUS    _IOR(USB2D_IOC_MAGIC,2,struct usb_twod_stats)

/*
 * Both image and shadow-OR samples are read from this device.
 * We place the following 4-byte type values at the beginning of
 * each data sample in big-endian form, so user code can
 * figure out which is which.
 */
#define TWOD_IMG_TYPE   0
#define TWOD_SOR_TYPE   1
#define TWOD_SORv3_TYPE 0x534f522c /* SOR, */
#define TWOD_IMGv2_TYPE 2
#define TWOD_IMGv3_TYPE 3

#ifdef __KERNEL__
#include <linux/module.h>
#include <linux/spinlock.h>
#include <linux/kref.h>

/* 64 bit probes will have minor numbers starting at 192,
 * 32 bit probes will have minor numbers starting at 196.
 * On the vulcan, running 2.6.11 kernel without a udev daemon,
 * you have to mknod the devices by hand:
 * mknod /dev/usbtwod_64_0 c 180 192
 * mknod /dev/usbtwod_64_1 c 180 193
 * mknod /dev/usbtwod_64_2 c 180 194
 * mknod /dev/usbtwod_64_3 c 180 195
 * mknod /dev/usbtwod_32_0 c 180 196
 * etc...
 * On systems with a udev daemon, these device files are created
 * automatically when the device is connected, using the
 * name member of the struct usb_class_driver, which
 * is passed to usb_register_dev() in the probe method.
 */
#define USB_TWOD_64_V3_MINOR_BASE  192
#define USB_TWOD_64_MINOR_BASE     192
#define USB_TWOD_32_MINOR_BASE     196

#define TWOD_IMG_BUFF_SIZE  4096
#define TWOD_SOR_BUFF_SIZE      128 /*PRS doc hs 70 as max possible size of housekeeping*/
#define TWOD_TAS_BUFF_SIZE  4

/* SAMPLE_QUEUE_SIZE must be a power of 2 (required by circ_buf).
 * In order for a circ_buf to tell the difference between empty
 * and full, a full circ_buf contains (size-1) elements.
 * In addition, SAMPLE_QUEUE_SIZE should be at least 
 * IMG_URBS_IN_FLIGHT + SOR_URBS_IN_FLIGHT + 1 
 */
/*
 * Throughput tests on both an Intel core laptop PC and an Arcom Vulcan
 * showed no difference in throughput with the following values
 * for the sample queue sizes and number of urbs in flight:
 * SAMPLE_QUEUE_SIZE IMG_URB_QUEUE_SIZE  IMG_URBS_IN_FLIGHT
 *  16      8           7
 *  8       4           3
 *  4       2           1
 * We'll use the middle values.
 * Having more than one urb in flight means a read()
 * can return more than one image sample.
 */
#define SAMPLE_QUEUE_SIZE   32

/* This queue is only used if throttleRate > 0 */
#define IMG_URB_QUEUE_SIZE  16   /* power of two */

#define IMG_URBS_IN_FLIGHT   (IMG_URB_QUEUE_SIZE-1)

#define SOR_URBS_IN_FLIGHT   4

#define TAS_URB_QUEUE_SIZE   4   /* power of two */

#define THROTTLE_JIFFIES (HZ / 10)

struct twod_urb_sample
{
        dsm_sample_time_t timetag;      /* timetag of sample */
        dsm_sample_length_t length;     /* number of bytes in data */
        unsigned int stype;     /* sample type, 0=image, 1=SOR */
        unsigned int data;     /* True Airspeed for image sample */
        int pre_urb_len;    /* size of sample without urb contents */
        struct urb *urb;
};
struct twod_house_urb_sample
{
        int serialNum;
        dsm_sample_time_t timetag;
        unsigned int stype; //sor
        unsigned int data; //dof or
        int temperature;
        double levelD1;
        double levelD32;
        double levelD64;
};

struct sample_circ_buf
{
        struct twod_urb_sample **buf;
        int head;
        int tail;
};

struct urb_circ_buf
{
        struct urb **buf;
        int head;
        int tail;
};


/* reading status keeper  */
struct read_state
{
        char *dataPtr;          /* pointer into data of what is left to copy to user */
        size_t bytesLeft;       /* How much is left to copy to user buffer of sample_ptr */
        struct twod_urb_sample *pendingSample;  /* sample partly copied to user space */
};

enum twod_probe_type { TWOD_64_V3, TWOD_64, TWOD_32 };

/* Structure to hold all of our device specific stuff */
struct usb_twod
{       
        struct usb_device *udev;        /* the usb device for this device */
        struct usb_interface *interface;        /* the interface for this device */
        struct kref kref;               /* reference counter for this structure */
        rwlock_t usb_iface_lock;        /* for detection of whether disconnect has been called */

        char   dev_name[64];           /* device name for log messages */

        __u8 img_in_endpointAddr;       /* the address of the image in endpoint */
        __u8 tas_out_endpointAddr;      /* the address of the tas out endpoint */
        __u8 sor_in_endpointAddr;       /* value is "SOR," the address of the shadow word in endpoint - for v3 sor (rather housekeeping packet) is now binary, this value is used in xml to sort */
        int is_open;                   /* don't allow multiple opens. */

    enum twod_probe_type ptype;

        struct urb *img_urbs[IMG_URBS_IN_FLIGHT];       /* All data read urbs */
        struct urb_circ_buf img_urb_q;

        struct urb *sor_urbs[SOR_URBS_IN_FLIGHT];       /* All sor read urbs */

        struct sample_circ_buf sampleq; /* samples that are ready for reading from user side */
        spinlock_t sampqlock;           /* control sample producer threads */

        struct urb_circ_buf tas_urb_q;  /* queue of TAS samples for writing */

        wait_queue_head_t read_wait;    /* Zzzzz ... */

        struct usb_twod_stats stats;    /* various I/O counter for info */

        struct read_state readstate;    /* leftovers from past read */

        int errorStatus;                /* current error value */

        struct timer_list urbThrottle;
        
        int throttleJiffies;            /* if throttling jiffie wait between
                                            timer events */

        int nurbPerTimer;               /* if throttling, how many urbs to submit on
                                            every timer event */

        int latencyJiffies;             /* maximum time user wants to wait
                                         * between reads */

    unsigned long lastWakeup;       /* time of last read queue wakeup */

        struct timer_list sendTASTimer; /* kernel timer for sending true airspeed */
        int sendTASJiffies;             /* when to send the next TAS */

        spinlock_t taslock;             /* control access to TAS value */

        Tap2D tasValue;                 /* TAS value to send to probe (from user ioctl) */

        int consecTimeouts;
};
#endif                          // ifdef __KERNEL__
#endif