Subversion Repositories gecko3

/* GECKO3COM

 *

 * Copyright (C) 2008 by

 *   ___    ____  _   _

 *  (  _`\ (  __)( ) ( )

 *  | (_) )| (_  | |_| |   Berne University of Applied Sciences

 *  |  _ <'|  _) |  _  |   School of Engineering and

 *  | (_) )| |   | | | |   Information Technology

 *  (____/'(_)   (_) (_)

 *

 *

 * 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 3 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.

 * You should have received a copy of the GNU General Public License

 * along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

/*********************************************************************/

/** \file     usb_tmc.h

 *********************************************************************

 * \brief     header file for the USB Test and Measurement Class (TMC)

 *            functions.

 *

 *            According to USBTMC Specification Revision 1.0 and

 *            USBTMC-USB488 Subclass Specification Revision 1.0.

 *

 * \author    Christoph Zimmermann bfh.ch, Eldo José dos Santos

 * \date      2009-02-04

 *

*/

#ifndef _USBTMC_H_

#define _USBTMC_H_

/** length of the buffer to hold the response messages to be sent to the host */

#define TMC_RESPONSE_QUEUE_LENGTH 256  

/*****************************************************************************/

/* definitions, data structures and related stuff

 * according to USBTMC standard */

#define USB_TMC_HEADER_SIZE 12  /**< length of a USBTMC header */

/* USBTMC MsgID. Values, Ref.: Table 2 */

#define DEV_DEP_MSG_OUT             1   /**< device dependent command message */

#define REQUEST_DEV_DEP_MSG_IN      2   /**< command message that requests the 

                                           device to send a USBTMC response */

#define DEV_DEP_MSG_IN              2   /**< response message to the 

                                           REQUEST_DEV_DEP_MSG_IN */

#define VENDOR_SPECIFIC_OUT         126 /**< vendor specific command message */

#define REQUEST_VENDOR_SPECIFIC_IN  127 /**< command message that requests the

                                           device to send a vendor specific

                                           USBTMC response */

#define VENDOR_SPECIFIC_IN          127 /**< response message to the 

                                           REQUEST_VENDOR_SPECIFIC_IN */

/* format of bmRequestType byte */

#define bmRT_TMC_OUT   0x21             

#define bmRT_TMC_IN    0xA1

/* USBTMC commands (bRequest values, Ref.: Table 15) */

#define INITIATE_ABORT_BULK_OUT      1

#define CHECK_ABORT_BULK_OUT_STATUS  2

#define INITIATE_ABORT_BULK_IN       3

#define CHECK_ABORT_BULK_IN_STATUS   4

#define INITIATE_CLEAR               5

#define CHECK_CLEAR_STATUS           6

#define GET_CAPABILITIES             7

#define INDICATOR_PULSE              64

/* USBTMC USB488 Subclass commands (bRequest values, Ref.: Table 9) */

#define READ_STATUS_BYTE             128

#define REN_CONTROL                  160

#define GO_TO_LOCAL                  161

#define LOCAL_LOCKOUT                162

/* bmTransfer attributes */

#define bmTA_EOM       0x01  /**< bmTransfer Attribute: End of Message */

#define bmTA_TERMCHAR  0x02  /**< bmTransfer Attribute: Terminate transfer with Terminate Character */

/** \brief status values according to USBTMC specificaton, Ref.: Table 16 */

typedef enum {

        TMC_STATUS_SUCCESS                   = 0x01,

        TMC_STATUS_PENDING                   = 0x02,

        /* USB488 defined USBTMC status values */

        TMC_STATUS_INTERRUPT_IN_BUSY         = 0x20,

        TMC_STATUS_FAILED                    = 0x80,

        TMC_STATUS_TRANSFER_NOT_IN_PROGRESS  = 0x81,

        TMC_STATUS_SPLIT_NOT_IN_PROGRESS     = 0x82,

        TMC_STATUS_SPLIT_IN_PROGRESS         = 0x83,

} TMC_Status;

/* defines for the device capablilities, Ref.: Table 37 and Table 8 USB488 */

#define HAS_INDICATOR_PULSE 0x04

#define TALK_ONLY       0x02

#define LISTEN_ONLY     0x01

#define TERMCHAR_BULKIN 0x01

#define IS_488_2        0x04

#define ACCEPTS_LOCAL_LOCKOUT 0x02

#define TRIGGER         0x01

#define SCPI_COMPILIANT 0x08

#define SR1_CAPABLE     0x04

#define RL1_CAPABLE     0x02

#define DT1_CAPABLE     0x01

/** \brief Structure to handle get_capabilities command.

 *

 *  contains all required parameters for a correct device specification */

typedef struct {

  uint8_t USBTMC_status;

  uint8_t reserved0;

  uint8_t bcdUSBTMC_lsb;

  uint8_t bcdUSBTMC_msb;

  uint8_t TMCInterface;

  uint8_t TMCDevice;

  uint8_t reserved1[6];

  /* place here USB488 subclass capabilities */

  uint8_t bcdUSB488_lsb;

  uint8_t bcdUSB488_msb;

  uint8_t USB488Interface;

  uint8_t USB488Device;

  uint8_t reserved2[8];

} USB_TMC_Capabilities;

/* Structure to handle Bulk-OUT Header for a DEV_DEP_MSG

 *

 * Ref.: Table 3 or Bulk-IN Header for a DEV_DEP_MSG, Ref.: Table 9 */

typedef struct

{

        uint32_t TransferSize;

        int8_t   bmTransferAttributes;

        int8_t   Reserved[3];

} DEV_DEP_MSG_OUT_Header, /**< Bulk-OUT Header for a DEV_DEP_MSG,

                            Ref.: Table 3 */

  DEV_DEP_MSG_IN_Header;  /**< Bulk-IN Header for a DEV_DEP_MSG,

                             Ref.: Table 9 */

/** \brief Structure to handle USBTMC device dependent message IN requests.

 *

 *  Ref.: Table 4 */

typedef struct

{

        uint32_t TransferSize;

        int8_t   bmTransferAttributes;

        int8_t   TermChar;

        int8_t   Reserved[2];

} REQUEST_DEV_DEP_MSG_IN_Header; /* Ref.: Table 4 */

/* \brief structure to handle vendor specific IN/OUT or REQUESTS according

 *  to USBTMC */

typedef struct

{

        uint32_t TransferSize;

        int8_t   Reserved[4];

} VENDOR_SPECIFIC_OUT_Header, /**< structure to handle vendor specific

                               *IN/OUT or REQUESTS according to Ref.: Table 5 */

  REQUEST_VENDOR_SPECIFIC_IN_Header, /**< structure to handle vendor

                                      * specific IN/OUT or REQUESTS according

                                      * Ref.: Table 6 */

  VENDOR_SPECIFIC_IN_Header; /**< structure to handle vendor specific

                              * IN/OUT or REQUESTS according Ref.: Table 10 */

/** \brief general Header structure for USBTMC bulk messages. The MsgID value

 *  determines the type of the msg_specific part of these structure */

typedef struct _tHeader

{

        int8_t MsgID; /**< The MsgID value determines the type of the

                       * msg_specific part of these structure */

        int8_t bTag;

        int8_t bTagInverse;

        int8_t Reserved;

        int8_t msg_specific[8];

} BulkOUT_Header, /**< \brief According to USBTMC Ref.: Table 1 */

  BulkIN_Header,  /**< \brief According to USBTMC Ref.: Table 8 */

  tHeader; /**< \brief general Header structure for USBTMC bulk messages. */

/*****************************************************************************/

/* IEEE488 related stuff */

#define bmPOWER_ON                0x80

#define bmUSER_REQUEST            0x40

#define bmCOMMAND_ERROR           0x20

#define bmEXECUTION_ERROR         0x10

#define bmDEVICEDEPENDENT_ERROR   0x08

#define bmQUERY_ERROR             0x04

#define bmREQUEST_CONTROL         0x02

#define bmOPERATION_COMPLETE      0x01

/** \brief struct that contains all registers needed for the IEEE488.2

 *  compiliant status reporting */

typedef struct {

        uint8_t EventStatusRegister;

        uint8_t EventStatusEnable;

        uint8_t StatusByteRegister;

        uint8_t ServiceRequestEnable;

        uint8_t OPC_Received;

} IEEE488_status_registers;

/*****************************************************************************/

/* internal definitions and typedef's needed for this implementation */

#define NEWTRANSFER 1

/** \brief Internal state of tmc system.

 *

 *  used by this implementation, no reference in standard */

typedef enum {

        TMC_STATE_IDLE = 0x01,

        TMC_STATE_OUT_TRANSFER = 0x02,

        TMC_STATE_IN_TRANSFER = 0x03,

        TMC_STATE_ABORTING_OUT = 0x04,

        TMC_STATE_ABORTING_IN = 0x05,

        TMC_STATE_HALT = 0x06,

} TMC_State;

/** \brief struct to hold all usb tmc transfer relevant information */

typedef struct {

  uint8_t bTag; /**< contains the bTag value of the currently active transfer */

  uint32_t transfer_size;

  uint8_t new_transfer; /**< flag to signal the start of a new transfer,

                           else 0 */

  uint32_t nbytes_rxd; /**< contains the number of bytes received in active

                          tmc OUT transfer */

  uint32_t nbytes_txd; /**< contains the number of bytes transmitted in active

                          tmc IN transfer */

} TMC_Transfer_Info;

/** \brief response queue to hold the data for requests */

typedef struct {

  unsigned char buf[TMC_RESPONSE_QUEUE_LENGTH]; /**< message buffer */

  uint16_t length;  /**< length of message. is 0 when no message is available */

} TMC_Response_Queue;

/* Global variables */

extern volatile static TMC_Status usb_tmc_status;       /**< Global variable

contains the status of the last tmc operation. normally USB_TMC_SUCCESS */

extern volatile TMC_State usb_tmc_state;         /**< Global variable contains

the state of the tmc system. Example USB_TMC_IDLE or USB_TMC_IN_TRANSFER */

extern volatile idata TMC_Transfer_Info usb_tmc_transfer; /**< Global struct

to hold all usb tmc transfer relevant information */

extern volatile idata IEEE488_status_registers ieee488_status;   /**< Struct

that contains all status and enable registers for the IEEE488 status reporting

capabilities */

/** Makro to check if this setup package is a USBTMC request */

#define usb_tmc_request() ((wIndexL == USB_TMC_INTERFACE && \

                            (bRequestType & bmRT_RECIP_INTERFACE) == bmRT_RECIP_INTERFACE) \

                           ||                                           \

                           (wIndexL == USB_TMC_EP_OUT && \

                            (bRequestType & bmRT_RECIP_ENDPOINT) == bmRT_RECIP_ENDPOINT) \

                           ||                                           \

                           (wIndexL == (bmRT_DIR_IN | USB_TMC_EP_IN) && \

                            (bRequestType & bmRT_RECIP_ENDPOINT) == bmRT_RECIP_ENDPOINT) \

                          )

/** \brief general function to handle the TMC requests.

 *

 *  Parses the TMC header to provide needed information to the

 *  following message parser.

 *  \return returns non-zero if it handled the command successfully.

 */

uint8_t usb_handle_tmc_packet (void);

/** \brief clears all global variables to known states. sets the POWER_ON bit */

void init_usb_tmc();

/** set the mav bit (Message available or "Queue not empty") in the IEEE488

    status structure */

#define IEEE488_set_mav() (ieee488_status.StatusByteRegister |= 0x10)

/** clear the mav bit (Message available or "Queue not empty") in the IEEE488

    status structure */

#define IEEE488_clear_mav() (ieee488_status.StatusByteRegister &= 0xEF)

/** \brief evalutates the status IEEE488 status byte. represents the current

 *         device state

 *

 * executes the process to evaluate the current state of the status byte

 * according to the IEEE488.2 standard status reporting capabilities.

 * Reference: IEC60488-2:2004 figure 4-1

 *

 * \param[in] *status pointer to a IEEE488_status_registers struct.

 *            Status byte in the struct is updated

 * \return return value is the current value of the status byte

 */

uint8_t IEEE488_status_query(idata IEEE488_status_registers *status);

#endif /* _USBTMC_H_ */