packages/io/usb/serial/slave/v2_0/include/usbs_serial.h

   1 #ifndef CYGONCE_USBS_SERIAL_H
   2 #define CYGONCE_USBS_SERIAL_H
   3 //==========================================================================
   4 //
   5 //      include/usbs_serial.h
   6 //
   7 //      Description of the USB slave-side serial device support
   8 //
   9 //==========================================================================
  10 //####ECOSGPLCOPYRIGHTBEGIN####
  11 // -------------------------------------------
  12 // This file is part of eCos, the Embedded Configurable Operating System.
  13 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
  14 //
  15 // eCos is free software; you can redistribute it and/or modify it under
  16 // the terms of the GNU General Public License as published by the Free
  17 // Software Foundation; either version 2 or (at your option) any later version.
  18 //
  19 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  20 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  21 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22 // for more details.
  23 //
  24 // You should have received a copy of the GNU General Public License along
  25 // with eCos; if not, write to the Free Software Foundation, Inc.,
  26 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  27 //
  28 // As a special exception, if other files instantiate templates or use macros
  29 // or inline functions from this file, or you compile this file and link it
  30 // with other works to produce a work based on this file, this file does not
  31 // by itself cause the resulting work to be covered by the GNU General Public
  32 // License. However the source code for this file must still be made available
  33 // in accordance with section (3) of the GNU General Public License.
  34 //
  35 // This exception does not invalidate any other reasons why a work based on
  36 // this file might be covered by the GNU General Public License.
  37 //
  38 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
  39 // at http://sources.redhat.com/ecos/ecos-license/
  40 // -------------------------------------------
  41 //####ECOSGPLCOPYRIGHTEND####
  42 //==========================================================================
  43 //#####DESCRIPTIONBEGIN####
  44 //
  45 // Author(s):    Frank M. Pagliughi (fmp), SoRo Systems, Inc.
  46 // Contributors:
  47 // Date:         2008-06-02
  48 // Purpose:
  49 // Description:  USB slave-side serial support
  50 //
  51 //
  52 //####DESCRIPTIONEND####
  53 //==========================================================================
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 //
  60 // The primary purpose of the USB slave-side serial code is to provide a
  61 // simple USB connection to the host, especially for embedded systems that
  62 // are upgrading from RS-232 serial connections. The host would see the
  63 // device as if through a serial port, and thus the host software would
  64 // remain unchanged. It would also eliminate the need for a new device
  65 // driver on the host.
  66 //
  67 // On this side (the eCos USB slave side), the application sees the host
  68 // through a normal USB slave connection with two Bulk endpoints - one in
  69 // the IN direction and one in the OUT direction. This module provides the
  70 // necessary USB descriptors to enumerate the device for a single serial
  71 // port, but then the application is free to communicate with the host
  72 // using any desired API:
  73 //  - The standard eCos USB slave API
  74 //  - The low-level File I/O layer (if USB devtab entries configured)
  75 //  - The C stdio functions (again, if USB devtab entries configured)
  76 //  - The USB serial API defined here.
  77 //
  78 // The USB serial API is a thin layer over the standard eCos USB functions
  79 // to provide common synchronous and asynchronous transfers over the assigned
  80 // Bulk endpoints.
  81 //
  82
  83 #include <cyg/infra/cyg_type.h>
  84 #include <cyg/io/usb/usbs.h>
  85
  86 // ----------------------------------------------------------------------------
  87 // The ACM class requests
  88 //
  89
  90 #define USBS_SERIAL_SEND_ENCAPSULATED_COMMAND   0x00
  91 #define USBS_SERIAL_GET_ENCAPSULATED_RESPONSE   0x01
  92 #define USBS_SERIAL_SET_COMM_FEATURE            0x02
  93 #define USBS_SERIAL_GET_COMM_FEATURE            0x03
  94 #define USBS_SERIAL_CLEAR_COMM_FEATURE          0x04
  95
  96 #define USBS_SERIAL_SET_LINE_CODING             0x20
  97 #define USBS_SERIAL_GET_LINE_CODING             0x21
  98 #define USBS_SERIAL_SET_CONTROL_LINE_STATE      0x22
  99 #define USBS_SERIAL_SEND_BREAK                  0x23
 100
 101 // ----------------------------------------------------------------------------
 102 // Data structure to manage the pair of USB endpoints that comprise a single
 103 // serial port connection. Each "port" requires one Bulk IN endpoint and one
 104 // Bulk OUT endpoint.
 105
 106 typedef struct usbs_serial {
 107     // The communication endpoints. For the first (default) channel, these
 108     // are normally set by the configuration, but can be changed by the
 109     // application, if desired.
 110     usbs_tx_endpoint*   tx_ep;
 111     usbs_rx_endpoint*   rx_ep;
 112
 113     // The signal that a transmit operation is complete, and it's result.
 114     cyg_sem_t   tx_ready;
 115     int         tx_result;
 116
 117     // The signal that a receive operation is complete, and it's result.
 118     cyg_sem_t   rx_ready;
 119     int         rx_result;
 120
 121 } usbs_serial;
 122
 123 // The package contains one USB serial device.
 124 extern usbs_serial usbs_ser0;
 125
 126 // It's assumed that there's a single USB slave chip in the system, with a
 127 // single control endpoint 0. The actual variable is contained in the device
 128 // driver, but the USB serial code keeps a pointer to it for driver
 129 // independence. The application might find it useful for overriding low-level
 130 // code or callbacks.
 131 extern usbs_control_endpoint* usbs_serial_ep0;
 132
 133 // ----------------------------------------------------------------------------
 134 // A C interface to the serial USB code.
 135 // The application can use this interface, the standard (low-level) USB slave
 136 // API, the standard Unix-like I/O API, or C stdio API.
 137
 138 // Initialize support for a particular USB serial "port"
 139 // This associates a usbs_serial structure with specific endpoints and
 140 // initializes the structure for communications.
 141 void usbs_serial_init(usbs_serial*, usbs_tx_endpoint*, usbs_rx_endpoint*);
 142
 143 // Block the calling thread until the host configures the USB device.
 144 void usbs_serial_wait_until_configured(void);
 145
 146 // Determines if the USB subsystem is configured
 147 cyg_bool usbs_serial_is_configured(void);
 148
 149 // Start an asynchronous transmit of a single buffer.
 150 void usbs_serial_start_tx(usbs_serial*, const void* buf, int n);
 151
 152 // Block the calling thread until the transmit completes.
 153 // Returns the result code for the transfer
 154 int usbs_serial_wait_for_tx(usbs_serial*);
 155
 156 // Blocking, synchronous transmit of a single buffer.
 157 int usbs_serial_tx(usbs_serial*, const void* buf, int n);
 158
 159 // Start an asynchronous receive of a buffer.
 160 void usbs_serial_start_rx(usbs_serial*, void* buf, int n);
 161
 162 // Block the calling thread until the receive completes.
 163 // Returns the result code for the transfer
 164 int usbs_serial_wait_for_rx(usbs_serial*);
 165
 166 // Blocking, synchronous receive of a single buffer.
 167 int usbs_serial_rx(usbs_serial*, void* buf, int n);
 168
 169 // The default USB-serial state change handler paces the functions
 170 // usbs_serial_wait_until_configured() and usbs_serial_is_configured().
 171 // The application can override the state chain handler, but chain to
 172 // this function to keep the full USB-serial system working.
 173 void usbs_serial_state_change_handler(usbs_control_endpoint*, void*,
 174                                       usbs_state_change, int);
 175
 176 // Starts the USB subsystem
 177 void usbs_serial_start(void);
 178
 179 #ifdef __cplusplus
 180 } // extern "C"
 181 #endif
 182
 183 #endif // CYGONCE_USBS_SERIAL_H
 184