usb_cdc_class.c File Reference

Pic CDC USB routines. More...

#include "config.h"
#include "pic_usb.h"
#include "pic_usb_buffer_mgt.h"
#include "pic_serial.h"
#include "usb_cdc_class.h"
#include "memory.h"
Include dependency graph for usb_cdc_class.c:

Go to the source code of this file.

Data Structures

struct  line_coding
union  long_union

Defines

#define not_SERIAL_STATE   0xa1
#define req_CLEAR_COMM_FEATURE   0x04
#define req_GET_COMM_FEATURE   0x03
#define req_GET_ENCAPSULATED_RESPONSE   0x01
#define req_GET_LINE_CODING   0x21
#define req_SEND_BREAK   0x23
#define req_SEND_ENCAPSULATED_COMMAND   0x00
#define req_SET_COMM_FEATURE   0x02
#define req_SET_CONTROL_LINE_STATE   0x22
#define req_SET_LINE_CODING   0x20

Functions

uns8 usb_cdc_getc (void)
 Retrieve a received character from the USB serial port.
void usb_cdc_handle_tx ()
 Transmit any buffered characters over ther USB virtual serial port.
void usb_cdc_print_int (uns16 i)
 Print a 16 bit number to the USB virtual serial port.
void usb_cdc_print_str (char *str)
 Print a string out to the USB virtual serial port.
void usb_cdc_putc (uns8 c)
 Sends a single character to the USB serial port.
uns8 usb_cdc_rx_avail ()
 Check to see if a character is available in the receive buffer.
void usb_cdc_set_dcd ()
void usb_cdc_set_dsr ()
void usb_cdc_setup ()
 Set up data structures ready for USB CDC use.
uns8 usb_cdc_tx_empty ()
 Check to see if the transmit buffer is empty.
void usb_ep_data_in_callback (uns8 end_point, uns16 byte_count)
 Callback routine triggered when data has been sent to the host.
void usb_ep_data_out_callback (uns8 end_point, uns8 *buffer, uns16 byte_count)
 Callback routine triggered when data has been sent to the device.
void usb_handle_class_ctrl_read_callback ()
 Callback routine for a class control read.
void usb_handle_class_ctrl_write_callback (uns8 *data, uns16 count)
 Callback routine for a class control write.
void usb_handle_class_request_callback (setup_data_packet sdp)
 Callback routine for a control transfer request that is placed on the class.
void usb_SOF_callback (uns16 frame)
 Callback routine triggered each time a start of frame (SOF) has been received.

Variables

uns8 cdc_rx_buffer [USB_CDC_RX_BUFFER_SIZE]
uns8 cdc_rx_end = 0
uns8 cdc_rx_start = 0
uns8 cdc_tx_buffer [USB_CDC_TX_BUFFER_SIZE]
uns8 cdc_tx_end = 0
uns8 cdc_tx_start = 0
uns8 class_data [8]
uns16 current_bit_rate
long_union dte_rate

Detailed Description

Communication Device Class (Serial Port) USB routines

Definition in file usb_cdc_class.c.


Define Documentation

#define not_SERIAL_STATE   0xa1

Definition at line 74 of file usb_cdc_class.c.

#define req_CLEAR_COMM_FEATURE   0x04

Definition at line 68 of file usb_cdc_class.c.

#define req_GET_COMM_FEATURE   0x03

Definition at line 67 of file usb_cdc_class.c.

#define req_GET_ENCAPSULATED_RESPONSE   0x01

Definition at line 65 of file usb_cdc_class.c.

#define req_GET_LINE_CODING   0x21
#define req_SEND_BREAK   0x23

Definition at line 72 of file usb_cdc_class.c.

#define req_SEND_ENCAPSULATED_COMMAND   0x00

Definition at line 64 of file usb_cdc_class.c.

#define req_SET_COMM_FEATURE   0x02

Definition at line 66 of file usb_cdc_class.c.

#define req_SET_CONTROL_LINE_STATE   0x22

Definition at line 71 of file usb_cdc_class.c.

Referenced by usb_handle_class_request_callback().

#define req_SET_LINE_CODING   0x20

Function Documentation

uns8 usb_cdc_getc (  ) 

Receive a character from the USB serial port. If a character has not been received, this routine will wait indefinately.

Returns:
Byte from the receive buffer.

Definition at line 371 of file usb_cdc_class.c.

References cdc_rx_buffer, cdc_rx_end, cdc_rx_start, end_crit_sec, start_crit_sec, and uns8.

void usb_cdc_handle_tx (  ) 

Generally only used internally, this routine will attempt to place any characters in the transmit queue into the USB buffers. It will fail gracefully if the USB buffer is already owned by the SIE.

Definition at line 392 of file usb_cdc_class.c.

References buffer_descriptor::addr, BC8, BC9, BSTALL, cdc_tx_buffer, cdc_tx_end, cdc_tx_start, buffer_descriptor::count, DTS, DTSEN, end_crit_sec, ep_in_bd_location, ep_in_buffer_location, ep_in_buffer_size, INCDIS, KEN, platform_leds_flash(), serial_print_int(), serial_print_str(), serial_putc(), start_crit_sec, buffer_descriptor::stat, uns16, uns8, and UOWN.

Referenced by usb_ep_data_in_callback(), and usb_SOF_callback().

Here is the call graph for this function:

Here is the caller graph for this function:

void usb_cdc_print_int ( uns16  i  ) 

Print a 16 bit unsigned number in decimal to the USB virtual serial port

Parameters:
i the 16 bit number to be printed

Definition at line 491 of file usb_cdc_class.c.

References uns8, and usb_cdc_putc().

Here is the call graph for this function:

void usb_cdc_print_str ( char *  str  ) 

Send a null terminated string out the virtual serial port

Parameters:
str the string to be sent

Definition at line 459 of file usb_cdc_class.c.

References uns8, and usb_cdc_putc().

Here is the call graph for this function:

void usb_cdc_putc ( uns8  c  ) 

Deliver a single character out the virtual serial port. This routine will add the character to the transmit buffer. The actual buffer will be physically sent on the Start Of Frame (SOF) interrupt (each 1ms) or on the end point interrupt - ie, when the last character or chunk of characters was sent.

Parameters:
c The 8 bit byte to be transmitted.

Definition at line 343 of file usb_cdc_class.c.

References cdc_tx_buffer, cdc_tx_end, cdc_tx_start, end_crit_sec, start_crit_sec, and uns8.

Referenced by usb_cdc_print_int(), and usb_cdc_print_str().

Here is the caller graph for this function:

uns8 usb_cdc_rx_avail (  ) 

If one or more bytes are available in the USB serial port receive buffer, this routine will return true. If there are no bytes available, it will return false.

Returns:
True if buffer is not empty, False if buffer is empty.

Definition at line 456 of file usb_cdc_class.c.

References cdc_rx_end, and cdc_rx_start.

void usb_cdc_set_dcd (  ) 

Definition at line 335 of file usb_cdc_class.c.

void usb_cdc_set_dsr (  ) 

Definition at line 338 of file usb_cdc_class.c.

void usb_cdc_setup (  ) 

Configures the default DTE rate, stop bits etc.

Definition at line 483 of file usb_cdc_class.c.

References long_union::as_long, and current_bit_rate.

uns8 usb_cdc_tx_empty (  ) 

Sometimes it is useful to see if the transmit buffer is empty, since then you can be sure your data is well on its way. In the case of USB, this means that the data has been at least placed into the outbound USB buffer; it's not possible to tell until after the fact if the data has actually been squirted out the USB port.

Returns:
True if transmit buffer is empty, False if buffer still has data in it.

Definition at line 457 of file usb_cdc_class.c.

References cdc_tx_end, and cdc_tx_start.

void usb_ep_data_in_callback ( uns8  end_point,
uns16  byte_count 
)

If you have called usb_send_data to transfer data to the host, this routine will be fired once this data has been transferred. You may send more data by using usb_send_data(). Since the current PicPack USB library supports only single buffering, transfer speed is limited by how quickly you can refill the buffer again. In the future, we may support double buffering (ping poing buffering) which will most likely improve transfer speeds (to be fair, transfer performance has not been a limiting factor in tests so far).

In order for this callback to be triggered, you must define USB_EP_DATA_CALLBACK in your config.h

Parameters:
end_point The endpoint on which the data was transferred
byte_count The number of bytes that were actually transferred

Definition at line 323 of file usb_cdc_class.c.

References serial_print_int(), serial_print_str(), and usb_cdc_handle_tx().

Referenced by usb_handle_transaction().

Here is the call graph for this function:

Here is the caller graph for this function:

void usb_ep_data_out_callback ( uns8  end_point,
uns8 *  buffer_location,
uns16  byte_count 
)

If data is sent to the device and the endpoint is not endpoint 0 (the control transfer endpoint) then this routine is called. Since the routine is passed the actual hardware buffer location, it is important to pull data out of the buffer as soon as possible in order to free up the buffer to receive more data. The buffer is re-primed only once this routine completes since PicPack only supports single-buffered mode. In the future, we may look at supporting double buffering (ping-pong buffering) in order to be able to receive more data even while this routine is being called.

In order for this callback to be triggered, you must define USB_EP_DATA_CALLBACK in your config.h

Parameters:
end_point The endpoint the data was sent do
buffer_lcoation The memory location of the USB buffer where the data was received into
byte_count The number of bytes received

Definition at line 283 of file usb_cdc_class.c.

References cdc_rx_buffer, cdc_rx_end, cdc_rx_start, platform_leds_flash(), serial_print_int(), serial_print_str(), and uns8.

Referenced by usb_handle_transaction().

Here is the call graph for this function:

Here is the caller graph for this function:

void usb_handle_class_ctrl_read_callback (  ) 

When a control transfer is taking place, this routine is called to indicate that a control read for the class has taken place. Since everything in USB land is all about what has just happened, this callback will occur after data has been transferred to the host. If you wish to send more data to the host, use usb_send_data(), or if your control read has sent all the data required, you will need to indicate that the state has changed by setting the control_mode variable to cm_CTRL_READ_AWAITING_STATUS. This will indicate to the stack that it should now wait for the status packet before completing the control transfer.

To allow this callback to trigger, ensure you define USB_CALLBACK_ON_CLASS_CTRL in your config.h

Definition at line 268 of file usb_cdc_class.c.

References setup_data_packet::bRequest, cm_CTRL_READ_AWAITING_STATUS, control_mode, req_GET_LINE_CODING, serial_print_int(), serial_print_str(), and usb_sdp.

Here is the call graph for this function:

void usb_handle_class_ctrl_write_callback ( uns8 *  data,
uns16  count 
)

When a control transfer is taking place, this routine is called to indicate that a control write for the class has taken place. Since everything in USB land is all about what has just happened, this callback will occur after data has been received by the device. If you expect more data from the host, it will arrive in due course since endpoint 0 will be primed for more data automatically. If you have received all the data from the host, you will need to set the control_mode state variable to cm_CTRL_WRITE_SENDING_STATUS and then actually send the status by calling usb_send_status_ack(). Once the status has actually been sent, the control_mode state will automatically change to cm_IDLE to indicate the transfer has completed.

To allow this callback to trigger, ensure you define USB_CALLBACK_ON_CLASS_CTRL in your config.h

Definition at line 168 of file usb_cdc_class.c.

References long_union::as_byte_array, long_union::as_long, setup_data_packet::bRequest, class_data, cm_CTRL_WRITE_SENDING_STATUS, control_mode, current_bit_rate, line_coding::data_bits, line_coding::dte_rate, line_coding::parity, platform_leds_flash(), req_SET_LINE_CODING, serial_print_int(), serial_print_int_hex(), serial_print_str(), serial_putc(), serial_setup(), serial_tx_empty(), serial_tx_isr(), line_coding::stop_bits, usb_sdp, and usb_send_status_ack.

Here is the call graph for this function:

void usb_handle_class_request_callback ( setup_data_packet  sdp  ) 

After receiving a setup packet, where the request is placed on the class, this routine is called. In usb_handle_class_request_callback, you can set up ready for the data stage of the control transfer. The direction of the data stage can be determined by examining test_bit(sdp.bRequest, DATA_STAGE_DIR) although generally it appears to be obvious from the request. The request is stored in sdp.bRequest.

Typically, if it is a control read transfer (that is, it is a request by the host for data), then you will need to move the control_mode state variable to cm_CTRL_READ_DATA_STAGE_CLASS and send data using usb_send_data(). If you only intend to send one packet, you can immediately move the control_mode state variable to cm_CTRL_READ_AWAITING_STATUS to indicate you are waiting for the status to arrive. You could wait for the usb_handle_class_ctrl_read callback and do it (move to cm_CTROL_READ_AWAITING_STATUS) but the PicPack USB stack can handle the control read event for you if you've already switched states.

If it is a control write transfer (that is, it is a request by the host to send data to the device), then you will need to move the control_mode state variable to cm_CTRL_WRITE_DATA_STAGE_CLASS. Then, the usb_handle_class_ctrl_write will be fired when data is received by the device in the data stage.

To allow this callback to trigger, ensure you define USB_CALLBACK_ON_CLASS_CTRL in your config.h

Definition at line 112 of file usb_cdc_class.c.

References long_union::as_byte_array, setup_data_packet::bRequest, cm_CTRL_READ_AWAITING_STATUS, cm_CTRL_READ_DATA_STAGE_CLASS, cm_CTRL_WRITE_DATA_STAGE_CLASS, cm_CTRL_WRITE_SENDING_STATUS, control_mode, line_coding::data_bits, line_coding::dte_rate, line_coding::parity, req_GET_LINE_CODING, req_SET_CONTROL_LINE_STATE, req_SET_LINE_CODING, serial_print_int(), serial_print_int_hex(), serial_print_str(), serial_putc(), line_coding::stop_bits, uns8, usb_send_data(), usb_send_status_ack, setup_data_packet::wLength, and setup_data_packet::wValue.

Here is the call graph for this function:

void usb_SOF_callback ( uns16  frame  ) 

Frames in USB occur each 1ms. A SOF packet is sent to each device at the start of each frame. This is a really neat way of getting a 1ms timer without any further work.

Parameters:
frame The frame number. Frames will wrap at 65535.

Definition at line 478 of file usb_cdc_class.c.

References usb_cdc_handle_tx().

Referenced by usb_handle_isr().

Here is the call graph for this function:

Here is the caller graph for this function:


Variable Documentation

uns8 cdc_rx_buffer[USB_CDC_RX_BUFFER_SIZE]

Receive fifo

Definition at line 102 of file usb_cdc_class.c.

Referenced by usb_cdc_getc(), and usb_ep_data_out_callback().

uns8 cdc_rx_end = 0

Receive fifo end point

Definition at line 106 of file usb_cdc_class.c.

Referenced by usb_cdc_getc(), usb_cdc_rx_avail(), and usb_ep_data_out_callback().

uns8 cdc_rx_start = 0

Receive fifo start point

Definition at line 104 of file usb_cdc_class.c.

Referenced by usb_cdc_getc(), usb_cdc_rx_avail(), and usb_ep_data_out_callback().

uns8 cdc_tx_buffer[USB_CDC_TX_BUFFER_SIZE]

Transmit fifo

Definition at line 95 of file usb_cdc_class.c.

Referenced by usb_cdc_handle_tx(), and usb_cdc_putc().

uns8 cdc_tx_end = 0

Transmit fifo end point

Definition at line 99 of file usb_cdc_class.c.

Referenced by usb_cdc_handle_tx(), usb_cdc_putc(), and usb_cdc_tx_empty().

uns8 cdc_tx_start = 0

Transmit fifo start point

Definition at line 97 of file usb_cdc_class.c.

Referenced by usb_cdc_handle_tx(), usb_cdc_putc(), and usb_cdc_tx_empty().

uns8 class_data[8]

Definition at line 109 of file usb_cdc_class.c.

Referenced by usb_handle_class_ctrl_write_callback().

Definition at line 91 of file usb_cdc_class.c.

Referenced by usb_cdc_setup(), and usb_handle_class_ctrl_write_callback().

Definition at line 92 of file usb_cdc_class.c.


Generated on Wed Dec 8 13:47:53 2010 for Pic Pack by  doxygen 1.6.1