usb_protocol.h

一个简单示波器的源代码

//*****************************************************************************
//
// usb_protocol.h - Structures and definitions relating to the USB control
//                  protocol used by the Quickstart Oscilloscope application.
//
// Copyright (c) 2008 Luminary Micro, Inc.  All rights reserved.
// 
// Software License Agreement
// 
// Luminary Micro, Inc. (LMI) is supplying this software for use solely and
// exclusively on LMI's microcontroller products.
// 
// The software is owned by LMI and/or its suppliers, and is protected under
// applicable copyright laws.  All rights are reserved.  You may not combine
// this software with "viral" open-source software in order to form a larger
// program.  Any use in violation of the foregoing restrictions may subject
// the user to criminal sanctions under applicable laws, as well as to civil
// liability for the breach of the terms and conditions of this license.
// 
// THIS SOFTWARE IS PROVIDED "AS IS".  NO WARRANTIES, WHETHER EXPRESS, IMPLIED
// OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
// LMI SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR
// CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
// 
// This is part of revision 2692 of the Stellaris Peripheral Driver Library.
//
//*****************************************************************************

#ifndef _USB_PROTOCOL_H_
#define _USB_PROTOCOL_H_

//*****************************************************************************
// Oscilloscope USB Device Protocol Overview
// -----------------------------------------
//
// The oscilloscope application may be controlled remotely by an application
// running on a USB host machine. The oscilloscope offers two bulk endpoints,
// one IN endpoint used to send sample sets and state change information from
// the oscilloscope to the host and one OUT endpoint allowing the host to send
// control requests to the oscilloscope.
//
// All information sent between the device and the host is based upon the
// tScopePacket structure. This structure defines the protocol version in use,
// the command or status update being sent, two packet-specific parameters
// and optional command or status-specific data. Each packet sent is, therefore,
// a tScopePacket structure with optional data appended to the end of it.
//
// Before the device will attempt to send any data to the host, it listens for
// a SCOPE_PKT_HOST_HELLO packet from the host.  This packet indicates that
// the host application is running and informs the device of the version of
// the protocol it is using.  The device then responds with a
// SCOPE_PKT_HELLO_RESPONSE indicating the protocol version that should be
// used, either the protocol version requested by the host or a lower version
// if the device does not support the host's requested version.  This response
// also includes additional data informing the host of the current settings
// of the oscilloscope to allow the application on the host side to initialize
// its user interface appropriately.
//
// After the SCOPE_PKT_HOST_HELLO/SCOPE_PKT_HELLO_RESPONSE handshake, the
// host is free to send any other commands to the device. The device will
// send state updates to the host and also data for all capture sequences
// performed. Communication continues until the device detects that the host
// has disconnected or the host sends a SCOPE_PKT_HOST_GOODBYE. In either of
// these cases, communication is reestablished when another HELLO handshake
// occurs.
//
// Data Transmission from the Oscilloscope to the host
// ---------------------------------------------------
//
// All command and status packets related to device control are completed in
// a single USB packet. In transfering captured data, however, multiple
// packets are required since a single set of capture data is larger than the
// maximum USB packet size. Communication of this data is performed using
// three distinct packet types, SCOPE_PKT_DATA_START, SCOPE_PKT_DATA and
// SCOPE_PKT_DATA_END.
//
// Transmission of a new data set is initiated with a SCOPE_PKT_DATA_START
// packet whose payload provides information on the timing and format of the
// following sample data along with the total number of sample structures that
// are to be sent in following SCOPE_PKT_DATA packets.
//
// After SCOPE_PKT_DATA_START, the device sends multiple SCOPE_PKT_DATA
// packets whose payloads contain an integral number of structures containing
// either single- or dual-channel data depending upon information passed in
// SCOPE_PKT_DATA_START. The SCOPE_PKT_DATA packets also contain a continuity
// counter to allow the host to be sure that no packets have been lost. This
// counter increments by one for each packet in the data set.
//
// Once sufficient SCOPE_PKT_DATA packets have been sent to transfer all the
// sample data, a single SCOPE_PKT_DATA_END packet indicates the end of the
// transfer. The packet count in this packet is one greater than the last
// SCOPE_PKT_DATA packet count value.
//
// If any errors occur, the host may request retransmission of the entire
// data set using SCOPE_PKT_RETRANSMIT which causes the device to resend the
// latest captured data. Alternatively, if continuous capture is taking place,
// the host may simply ignore the damaged data set and wait for the next one.
//
// Host to Device Commands
// -----------------------
//
// This section details the use of the packet-specific parameters in the
// tScopePacket header structure for all command sent from the host to the
// device. In all cases, the ucVersion field must be the protocol version
// number (SCOPE_PROTOCOL_VERSION_1 currently) and ucHdrLength must be set
// to sizeof(tScopePacket) which will equal 12 assuming your compiler packing
// macros are correctly configured.
//
// ucPacketType                ucParam          ulParam        ulDataLength
// ------------                -------          -------        ------------
// SCOPE_PKT_HOST_HELLO        Unused           Unused               0
// SCOPE_PKT_HOST_GOODBYE      Unused           Unused               0
// SCOPE_PKT_SET_TIMEBASE      Unused           uS/Division          0
// SCOPE_PKT_SET_TRIGGER_TYPE  Channel Number   Trigger Type         0
// SCOPE_PKT_SET_TRIGGER_POS   Unused           Trigger Pos          0
// SCOPE_PKT_CAPTURE           Unused           Unused               0
// SCOPE_PKT_STOP              Unused           Unused               0
// SCOPE_PKT_START             Unused           Unused               0
// SCOPE_PKT_SET_TRIGGER_LEVEL Unused           Level in mV          0
// SCOPE_PKT_RETRANSMIT        Unused           Unused               0
// SCOPE_PKT_SET_CHANNEL2      Enable/Disable   Unused               0
// SCOPE_PKT_PING              Echo1            Echo2                0
// SCOPE_PKT_PING_RESPONSE     Echo1            Echo2                0
// SCOPE_PKT_DATA_CONTROL      Enable/Disable   Unused               0
// SCOPE_PKT_FIND              Channel Number   Unused               0
// SCOPE_PKT_SET_POSITION      Channel Number   Position in mV       0
// SCOPE_PKT_SET_SCALE         Channel Number   Scale in mV/div      0
//
// Device to Host Status
// ---------------------
//
// This section details the use of packet-specific parameters in the
// tScopePacket header structure for all status packets sent from the device
// to the host. As for host to device commands, the ucVersion field must be the
// protocol version number (SCOPE_PROTOCOL_VERSION_1 currently) and ucHdrLength
// must be set to sizeof(tScopePacket) which will equal 12 assuming your
// compiler packing macros are correctly configured.
//
// ucPacketType                ucParam          ulParam        ulDataLength
// ------------                -------          -------        ------------
// SCOPE_PKT_HELLO_RESPONSE    Protocol         Unused     size tScopeSettings
// SCOPE_PKT_TIMEBASE_UPDATED  Unused           uS/Division          0
// SCOPE_PKT_TRIGGER_TYPE      Channel Number   Trigger Type         0
// SCOPE_PKT_TRIGGER_LEVEL     Unused           Level in mV          0
// SCOPE_PKT_TRIGGER_POS       Unused           Trigger Pos          0
// SCOPE_PKT_CHANNEL2          Enable/Disable   Unused               0
// SCOPE_PKT_STARTED           Unused           Unused               0
// SCOPE_PKT_STOPPED           Unused           Unused               0
// SCOPE_PKT_DATA_START        0                Elements   size tScopeDataStart
// SCOPE_PKT_DATA              Packet Count     Elements       Payload size
// SCOPE_PKT_DATA_END          Packet Count     Unused               0
// SCOPE_PKT_PING              Echo1            Echo2                0
// SCOPE_PKT_PING_RESPONSE     Echo1            Echo2                0
// SCOPE_PKT_POSITION          Channel Number   Position in mV       0
// SCOPE_PKT_SCALE             Channel Number   Scale in mV/div      0
//
//*****************************************************************************

//*****************************************************************************
//
// All structures defined in this header require byte packing of fields. This
// is usually accomplished using the PACKED modifier macro but, for IAR
// Embedded Workbench, we need to issue a pragma so...
//
//*****************************************************************************
#ifdef ewarm
#pragma pack(1)
#endif

typedef struct
{
    unsigned char ucVersion;
    unsigned char ucHdrLength;
    unsigned char ucPacketType;
    unsigned char ucParam;
    unsigned long ulParam;
    unsigned long ulDataLength;
}
PACKED tScopePacket;

//*****************************************************************************
//
// The protocol version number associated with the definitions in this header
// file.
//
//*****************************************************************************
#define SCOPE_PROTOCOL_VERSION_1 0x01

//*****************************************************************************
//
// Packet types (tScopePacket.ucPacketType) for packets sent from the host
// to the device.
//
//*****************************************************************************

//
// Sent from the host to initiate communication. The ucVersion field of
// tScopePacket indicates the highest protocol version number the host
// supports. The host must ensure that it uses the protocol version which
// appears in the SCOPE_PKT_HELLO_RESPONSE sent from the device in response
// to this packet for all future transactions.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_HOST_HELLO 0x00

//
// Sent from the host to terminate communication.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_HOST_GOODBYE 0x01

//
// Sent from the host to set the trigger type to be used in the following
// capture requests.
//
// ucParam      - SCOPE_CHANNEL_1 or SCOPE_CHANNEL_2 to indicate the channel
//                on which triggering is to take place.
// ulParam      - SCOPE_TRIGGER_TYPE_LEVEL, SCOPE_TRIGGER_TYPE_RISING,
//                SCOPE_TRIGGER_TYPE_FALLING or SCOPE_TRIGGER_TYPE_ALWAYS.
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_TRIGGER_TYPE 0x02

// Sent from the host to request a change in the timebase. This affects both
// the display and also the sample capture rate.
//
// ucParam      - Unused
// ulParam      - The new timebase expressed in microseconds per division.
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_TIMEBASE 0x03

//
// Sent from the host to request a single capture cycle. This command is
// ignored if continuous capture is currently ongoing.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_CAPTURE 0x04

//
// Sent from the host to stop continuous capture of data.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_STOP 0x05

//
// Sent from the host to start continuous capture of data.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_START 0x06

//
// Sent from the host to set the trigger level.
//
// ucParam      - Unused
// ulParam      - The desired trigger level in millivolts.
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_TRIGGER_LEVEL 0x07

//
// Sent from the host to set the trigger position.
//
// ucParam      - Unused
// ulParam      - The desired trigger position in pixels (-60, 60).
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_TRIGGER_POS 0x08

//
// Sent from the host to request retransmission of the last data set captured.
// Note that this packet will initiate transmission of a data set even if
// automatic data capture has not previously been enabled via a
// SCOPE_PKT_DATA_CONTROL packet.
//
// ucParam      - Unused
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_RETRANSMIT 0x09

//
// Sent from the host to enable or disable capture of data on channel 2
//
// ucParam      - SCOPE_CHANNEL2_DISABLE or SCOPE_CHANNEL2_ENABLE
// ulParam      - Unused
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_CHANNEL2 0x0A

//
// Sent either from the host or device to enquire as to ensure that the
// communication link is still active. The parameters passed in the packet
// will be returned in the matching SCOPE_PKT_PING_RESPONSE packet.
//
// ucParam      - Sender's choice.
// ulParam      - Sender's choice
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_PING 0x0B

//
// Sent from the host to instruct the device to start or stop automatic
// transmission of captured waveform data. By default, the device will not
// transmit SCOPE_PKT_DATA_START/SCOPE_PKT_DATA/SCOPE_PKT_DATA_END unless
// this packet has been sent with a non-zero value in ucParam to enable
// data flow.
//
// ucParam      - Zero to disable automatic data transmission, non-zero to
//                enable it.
// ulParam      - Unused.
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_DATA_CONTROL 0x0C

//
// Sent from the host to instruct the device set the offset and scale
// for the given channel to ensure that the waveform is visible on the
// screen. This packet will result in the return of two packets,
// SCOPE_PKT_POSITION and SCOPE_PKT_SCALE indicating the calculated position
// and scale settings.
//
// ucParam      - SCOPE_CHANNEL_1 or SCOPE_CHANNEL_2 to indicate the channel
//                whose display position and scale is to be set.
// ulParam      - Unused.
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_FIND 0x0D

//
// Sent from the host to instruct the device to set the vertical position
// offset for a given channel. A SCOPE_PKT_POSITION packet will be returned by
// the device in response to this request.
//
// ucParam      - SCOPE_CHANNEL_1 or SCOPE_CHANNEL_2 to indicate the channel
//                whose display position is to be set.
// ulParam      - Position offset in mV (signed).
// ulDataLength - 0 (no additional payload).
//
#define SCOPE_PKT_SET_POSITION 0x0E

//
// Sent from the host to instruct the device to set the vertical scaling
// offset for a given channel. A SCOPE_PKT_SCALE packet will be returned by
// the device in response to this request.
//
// ucParam      - SCOPE_CHANNEL_1 or SCOPE_CHANNEL_2 to indicate the channel
//                whose vertical scale is to be set.