# C51 USB Library

## Library Usage

### Package Description

### Package Summary

#### Constants

#### Global Variables

#### Macros

    USB clock management
    wSWAP

#### Functions

    configure_usb_clock
    usb_configure_endpoint
    usb_get_nb_byte
    usb_get_nb_byte_epw
    usb_halt_endpoint
    usb_read_packet
    usb_reset_endpoint
    usb_select_endpoint_interrupt
    usb_send_ep0_packet
    usb_send_packet

### Files List

- usb_drv.c

This file contains the USB driver routines.

- usb_drv.h

This file contains the USB low level driver definition

### Included Files

- config.h
- usb_drv.h

## Constant Macros

## Global Variables

## Function Macros

### USB clock management

    #define Usb_set_EXT48 (  )                 ( PLLCON |= MSK_EXT48 )
    #define Usb_clear_EXT48 (  )               ( PLLCON &= ~MSK_EXT48 )
    #define Pll_stop (  )                      ( PLLCON &= ~MSK_PLLEN )
    #define Pll_set_div ( n )                  ( PLLDIV = n )
    #define Pll_enable (  )                    ( PLLCON |= MSK_PLLEN )
    / * _____ D E C L A R A T I O N ______________________________________________ * /
    void    usb_configure_endpoint        ( Uchar  ,  Uchar ) ;
    Uchar   usb_get_nb_byte               ( void ) ;
    Uint16  usb_get_nb_byte_epw           ( void ) ;
    Uchar *   usb_send_ep0_packet           ( Uchar *  ,  Uchar ) ;
    Uchar *   usb_send_packet               ( Uchar  ,  Uchar *  ,  Uchar ) ;
    Uchar *   usb_read_packet               ( Uchar  ,  Uchar *  ,  Uchar ) ;
    void    usb_reset_endpoint            ( Uchar ) ;
    Uchar   usb_select_enpoint_interrupt  ( void ) ;
    void    usb_halt_endpoint             ( Uchar ) ;
    void    configure_usb_clock           ( void ) ;
    #endif  / *  _USB_DRV_H_  * /

These macros manage the USB clock.

### wSWAP

    #define wSWAP ( x )   (  (  (  ( x ) >>8 ) &0x00FF ) | (  (  ( x ) <<8 ) &0xFF00 )  )  ;
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: dwSWAP
     * ----------------------------------------------------------------------------
     *  PARAMS:
     *  x     :  ( Uint32 )  the 32 bit double word to swap
     *  return:  ( Uint32 )  the 32 bit double word x with the 4 bytes swaped
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  This macro swaps the Uchar order in double words.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define dwSWAP ( x )   (  (  (  ( x ) >>24 ) &0x000000FF ) | (  (  ( x ) >>8 ) &0x0000FF00 ) | (  (  ( x ) <<24 ) &0xFF000000 ) | (  (  ( x ) <<8 ) &0x00FF0000 )  )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: General endpoint management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the common features of the endpoints
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_select_ep ( e )                ( UEPNUM = e )
    #define Usb_configure_ep_type ( x )        ( UEPCONX = x )
    #define Usb_set_stall_request (  )         ( UEPSTAX |= MSK_STALLRQ )
    #define Usb_clear_stall_request (  )       ( UEPSTAX &= ~MSK_STALLRQ )
    #define Usb_clear_stalled (  )             ( UEPSTAX &= ~MSK_STALLED )
    #define Usb_stall_requested (  )           ( UEPSTAX & MSK_STALLRQ )
    #define Usb_stall_sent (  )                ( UEPSTAX & MSK_STALLED )
    #define Usb_read_byte (  )                 ( UEPDATX )
    #define Usb_write_byte ( x )               ( UEPDATX = x )
    #define Usb_endpoint_interrupt (  )        ( UEPINT != 0  )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: OUT endpoint management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the OUT endpoints.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_clear_rx (  )                  ( UEPSTAX &= ~MSK_RXOUT )
    #define Usb_clear_rx_bank0 (  )            ( UEPSTAX &= ~MSK_RXOUTB0 )
    #define Usb_clear_rx_bank1 (  )            ( UEPSTAX &= ~MSK_RXOUTB1 )
    #define Usb_rx_complete (  )               ( UEPSTAX & MSK_RXOUTB0B1 )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: IN endpoint management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the IN endpoints.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_set_tx_ready (  )              ( UEPSTAX |= MSK_TXRDY )
    #define Usb_clear_tx_ready (  )            ( UEPSTAX &= ~MSK_TXRDY )
    #define Usb_clear_tx_complete (  )         ( UEPSTAX &= ~MSK_TXCMPL )
    #define Usb_tx_complete (  )               ( UEPSTAX & MSK_TXCMPL )
    #define Usb_tx_ready (  )                  ( UEPSTAX & MSK_TXRDY )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: CONTROL endpoint management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the Control endpoints.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_clear_rx_setup (  )            ( UEPSTAX &= ~MSK_RXSETUP )
    #define Usb_setup_received (  )            ( UEPSTAX & MSK_RXSETUP )
    #define Usb_clear_DIR (  )                 ( UEPSTAX &= ~MSK_DIR )
    #define Usb_set_DIR (  )                   ( UEPSTAX |= MSK_DIR )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: General USB management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the USB controller.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_enable (  )                    ( USBCON |= MSK_USBE )
    #define Usb_disable (  )                   ( USBCON &= ~MSK_USBE )
    #define Usb_detach (  )                    ( USBCON |= MSK_DETACH )
    #define Usb_attach (  )                    ( USBCON &= ~MSK_DETACH )
    #define Usb_clear_reset (  )               ( USBINT &= ~MSK_EORINT )
    #define Usb_clear_resume (  )              ( USBINT &= ~MSK_WUPCPU )
    #define Usb_clear_sof (  )                 ( USBINT &= ~MSK_SOFINT )
    #define Usb_clear_suspend (  )             ( USBINT &= ~MSK_SPINT )
    #define Usb_suspend (  )                   ( USBINT & MSK_SPINT )
    #define Usb_resume (  )                    ( USBINT & MSK_WUPCPU )
    #define Usb_reset (  )                     ( USBINT & MSK_EORINT )
    #define Usb_sof (  )                       ( USBINT & MSK_SOFINT )
    #define Usb_configure_address ( x )        ( USBADDR =  ( 0x80 | x )  )
    #define Usb_set_CONFG (  )                 ( USBCON |= MSK_CONFG )
    #define Usb_clear_CONFG (  )               ( USBCON &= ~MSK_CONFG )
    #define Usb_set_FADDEN (  )                ( USBCON |= MSK_FADDEN )
    #define Usb_clear_FADDEN (  )              ( USBCON &= ~MSK_FADDEN )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: USB interrupt management
     * ----------------------------------------------------------------------------
     *  PARAMS:
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  These macros manage the USB controller.
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     * ----------------------------------------------------------------------------
     *  NOTE:
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define Usb_enable_int (  )                ( IEN1 |= MSK_EUSB )
    #define Usb_disable_int (  )               ( IEN1 &= ~MSK_EUSB )
    #define Usb_enable_reset_int (  )          ( USBIEN |= MSK_EEORINT )
    #define Usb_enable_resume_int (  )         ( USBIEN |= MSK_EWUPCPU )
    #define Usb_enable_sof_int (  )            ( USBIEN |= MSK_ESOFINT )
    #define Usb_enable_suspend_int (  )        ( USBIEN |= MSK_ESPINT )
    #define Usb_disable_reset_int (  )         ( USBIEN &= ~MSK_EEORINT )
    #define Usb_disable_resume_int (  )        ( USBIEN &= ~MSK_EWUPCPU )
    #define Usb_disable_sof_int (  )           ( USBIEN &= ~MSK_ESOFINT )
    #define Usb_disable_suspend_int (  )       ( USBIEN &= ~MSK_ESPINT )

This macro swaps the Uchar order in words.

    x     : (Uint16) the 16 bit word to swap
    return: (Uint16) the 16 bit word x with the 2 bytes swaped

## Functions

### configure_usb_clock

    void configure_usb_clock ( void )

This function configure the PLL to generate the 48MHz clock required by the USB controller, considering the FOSC defined in the "config.h" file.

    return:       none
    The possible value for FOSC are :
                 3000   ( 3MHz)
                 6000   ( 6MHz)
                 8000   ( 8MHz)
                12000   (12MHz)
                16000   (16MHz)
                18000   (18MHz)
                20000   (20MHz)
                24000   (24MHz)
                32000   (32MHz)
                40000   (40MHz)
                48000   (48MHz)
                 0000   (frequency auto-dectection)

#### Example

    #define FOSC   8000 // 8MHz
    configure_usb_clock();

### usb_configure_endpoint

    void usb_configure_endpoint  ( Uchar ep_num ,  Uchar ep_type )

This function configures an endpoint with the selected type.

    ep_num:   Number of the endpoint to configure
    ep_type:  Type to configure
              The possible types are:
                   CONTROL
                   BULK_IN
                   BULK_OUT
                   INTERRUPT_IN
                   INTERRUPT_OUT
                   ISOCHRONOUS_IN
                   ISOCHRONOUS_OUT
    return:   none

#### Example

    usb_configure_endpoint(0,CONTROL);

#### Note

The endpoint 0 shall always be configured in CONTROL type.

### usb_get_nb_byte

    Uchar usb_get_nb_byte  ( void )

This function returns the number of byte stored in the currently selected endpoint.

    return:   number of byte stored in the currently selected endpoint

#### Note

This function shall be launched only for OUT endpoints after each receipt and before any other operation. This function shall not be used if the declared FIFO size is more than 255 bytes. In this case, use the usb_get_nb_byte_epw function.

### usb_get_nb_byte_epw

    Uint16 usb_get_nb_byte_epw  ( void )

This function returns the number of byte stored in the endpoint 6.

    return:   number of byte stored in the endpoint .

#### Note

This function shall be launched only for OUT endpoints after each receipt and before any other operation. This function shall be used if the declared FIFO size is more than 255 bytes.

### usb_halt_endpoint

    void usb_halt_endpoint  ( Uchar ep_num )

This function sends a STALL handshake for the next Host request. A STALL handshake will be send for each next request untill a SETUP or a Clear Halt Feature occurs for this endpoint.

    ep_num:       number of the addressed endpoint
    return:       none

### usb_read_packet

    Uchar *  usb_read_packet  ( Uchar ep_num ,  Uchar *  rbuf ,  Uchar data_length )

This function moves the data stored in the selected endpoint fifo to the address specified by *rbuf.

    ep_num:       number of the addressed endpoint
    *rbuf:        address of the first data to write with the USB data
    data_length:  number of bytes to read
    return:       address of the next Ucharto send

#### Example

    while(!(Usb_rx_complete));                      // wait new packet received
    usb_read_packet(4,&first_data,usb_get_nb_byte); // read packet from ep 4
    Usb_clear_rx();                                 // acknowledge the transmit

#### Note

rbuf is incremented of 'data_length'.

### usb_reset_endpoint

    void usb_reset_endpoint  ( Uchar ep_num )

This function resets the endpoint fifo. This should be performed before the first use of an endpoint and after a Clear Halt Feature for the endpoint

    return:       none

### usb_select_endpoint_interrupt

    Uchar usb_select_enpoint_interrupt ( void )

This function select the endpoint where an event occurs and returns the number of this endpoint. If no event occurs on the endpoints, this function returns 0.

    return:   endpoint number

### usb_send_ep0_packet

    Uchar *  usb_send_ep0_packet  ( Uchar *  tbuf ,  Uchar data_length )

This function moves the data pointed by tbuf to the default Control endpoint fifo and sends it through the USB.

    *tbuf:        address of the first data to send
    data_length:  number of bytes to send
    return:       address of the next Ucharto send

#### Example

    usb_send_ep0_packet(&first_data,0x20);  // send packet
    while(!(Usb_tx_complete));              // wait packet ACK'ed by the Host
    Usb_clear_tx_complete();                     // acknowledge the transmit

#### Note

tbuf is incremented of 'data_length'.

### usb_send_packet

    Uchar *  usb_send_packet  ( Uchar ep_num ,  Uchar *  tbuf ,  Uchar data_length )

This function moves the data pointed by tbuf to the selected endpoint fifo and sends it through the USB.

    ep_num:       number of the addressed endpoint
    *tbuf:        address of the first data to send
    data_length:  number of bytes to send
    return:       address of the next Uchar to send

#### Example

    usb_send_packet(3,&first_data,0x20);    // send packet on the endpoint #3
    while(!(Usb_tx_complete));              // wait packet ACK'ed by the Host
    Usb_clear_tx_complete();                     // acknowledge the transmit

#### Note

tbuf is incremented of 'data_length'.