Subversion Repositories openrisc

#ifndef CYGONCE_USBS_SERIAL_H

#define CYGONCE_USBS_SERIAL_H

//==========================================================================

//

//      include/usbs_serial.h

//

//      Description of the USB slave-side serial device support

//

//==========================================================================

// ####ECOSGPLCOPYRIGHTBEGIN####                                            

// -------------------------------------------                              

// This file is part of eCos, the Embedded Configurable Operating System.   

// Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.

//

// eCos 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 or (at your option) any later      

// version.                                                                 

//

// eCos 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 eCos; if not, write to the Free Software Foundation, Inc.,    

// 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.            

//

// As a special exception, if other files instantiate templates or use      

// macros or inline functions from this file, or you compile this file      

// and link it with other works to produce a work based on this file,       

// this file does not by itself cause the resulting work to be covered by   

// the GNU General Public License. However the source code for this file    

// must still be made available in accordance with section (3) of the GNU   

// General Public License v2.                                               

//

// This exception does not invalidate any other reasons why a work based    

// on this file might be covered by the GNU General Public License.         

// -------------------------------------------                              

// ####ECOSGPLCOPYRIGHTEND####                                              

//==========================================================================

//#####DESCRIPTIONBEGIN####

//

// Author(s):    Frank M. Pagliughi (fmp), SoRo Systems, Inc.

// Contributors: 

// Date:         2008-06-02

// Purpose:

// Description:  USB slave-side serial support

//

//

//####DESCRIPTIONEND####

//==========================================================================

#ifdef __cplusplus

extern "C" {

#endif

//

// The primary purpose of the USB slave-side serial code is to provide a 

// simple USB connection to the host, especially for embedded systems that

// are upgrading from RS-232 serial connections. The host would see the 

// device as if through a serial port, and thus the host software would

// remain unchanged. It would also eliminate the need for a new device

// driver on the host.

// 

// On this side (the eCos USB slave side), the application sees the host

// through a normal USB slave connection with two Bulk endpoints - one in 

// the IN direction and one in the OUT direction. This module provides the

// necessary USB descriptors to enumerate the device for a single serial

// port, but then the application is free to communicate with the host

// using any desired API:

//  - The standard eCos USB slave API

//  - The low-level File I/O layer (if USB devtab entries configured)

//  - The C stdio functions (again, if USB devtab entries configured)

//  - The USB serial API defined here.

// 

// The USB serial API is a thin layer over the standard eCos USB functions

// to provide common synchronous and asynchronous transfers over the assigned

// Bulk endpoints.

//

#include <cyg/infra/cyg_type.h>

#include <cyg/io/usb/usbs.h>

// ----------------------------------------------------------------------------

// The ACM class requests

// 

#define USBS_SERIAL_SEND_ENCAPSULATED_COMMAND   0x00

#define USBS_SERIAL_GET_ENCAPSULATED_RESPONSE   0x01

#define USBS_SERIAL_SET_COMM_FEATURE            0x02

#define USBS_SERIAL_GET_COMM_FEATURE            0x03

#define USBS_SERIAL_CLEAR_COMM_FEATURE          0x04

#define USBS_SERIAL_SET_LINE_CODING             0x20

#define USBS_SERIAL_GET_LINE_CODING             0x21

#define USBS_SERIAL_SET_CONTROL_LINE_STATE      0x22

#define USBS_SERIAL_SEND_BREAK                  0x23

// ----------------------------------------------------------------------------

// Data structure to manage the pair of USB endpoints that comprise a single

// serial port connection. Each "port" requires one Bulk IN endpoint and one

// Bulk OUT endpoint.

typedef struct usbs_serial {

    // The communication endpoints. For the first (default) channel, these

    // are normally set by the configuration, but can be changed by the

    // application, if desired.

    usbs_tx_endpoint*   tx_ep;

    usbs_rx_endpoint*   rx_ep;

    // The signal that a transmit operation is complete, and it's result.

    cyg_sem_t   tx_ready;

    int         tx_result;

    // The signal that a receive operation is complete, and it's result.

    cyg_sem_t   rx_ready;

    int         rx_result;

} usbs_serial;

// The package contains one USB serial device.

extern usbs_serial usbs_ser0;

// It's assumed that there's a single USB slave chip in the system, with a

// single control endpoint 0. The actual variable is contained in the device

// driver, but the USB serial code keeps a pointer to it for driver 

// independence. The application might find it useful for overriding low-level

// code or callbacks.

extern usbs_control_endpoint* usbs_serial_ep0;

// ----------------------------------------------------------------------------

// A C interface to the serial USB code.

// The application can use this interface, the standard (low-level) USB slave

// API, the standard Unix-like I/O API, or C stdio API.

// Initialize support for a particular USB serial "port"

// This associates a usbs_serial structure with specific endpoints and 

// initializes the structure for communications.

void usbs_serial_init(usbs_serial*, usbs_tx_endpoint*, usbs_rx_endpoint*);

// Block the calling thread until the host configures the USB device.

void usbs_serial_wait_until_configured(void);

// Determines if the USB subsystem is configured

cyg_bool usbs_serial_is_configured(void);

// Start an asynchronous transmit of a single buffer.

void usbs_serial_start_tx(usbs_serial*, const void* buf, int n);

// Block the calling thread until the transmit completes.

// Returns the result code for the transfer

int usbs_serial_wait_for_tx(usbs_serial*);

// Blocking, synchronous transmit of a single buffer.

int usbs_serial_tx(usbs_serial*, const void* buf, int n);

// Start an asynchronous receive of a buffer.

void usbs_serial_start_rx(usbs_serial*, void* buf, int n);

// Block the calling thread until the receive completes.

// Returns the result code for the transfer

int usbs_serial_wait_for_rx(usbs_serial*);

// Blocking, synchronous receive of a single buffer.

int usbs_serial_rx(usbs_serial*, void* buf, int n);

// The default USB-serial state change handler paces the functions

// usbs_serial_wait_until_configured() and usbs_serial_is_configured().

// The application can override the state chain handler, but chain to 

// this function to keep the full USB-serial system working.

void usbs_serial_state_change_handler(usbs_control_endpoint*, void*,

                                      usbs_state_change, int);

// Starts the USB subsystem

void usbs_serial_start(void);

#ifdef __cplusplus

} // extern "C"

#endif

#endif // CYGONCE_USBS_SERIAL_H