Intel® Quark™ Microcontroller Software Interface 1.4.0 Intel® Quark™ Microcontroller BSP

- Main Page
- Modules
- Data Structures
- Files

Data Structures | Typedefs | Enumerations | Functions
USB

USB peripheral driver for Quark Microcontrollers. More...

## Data Structures
struct | qm_usb_ep_config_t
| USB Endpoint Configuration. More...

## Typedefs
typedef void(* | qm_usb_status_callback_t )(void *data, int error, qm_usb_status_t status)
| Callback function signature for the device status. More...

## Enumerations
enum | qm_usb_status_t { QM_USB_RESET, QM_USB_CONNECTED, QM_USB_CONFIGURED, QM_USB_DISCONNECTED, QM_USB_SUSPEND, QM_USB_RESUME }
| USB Driver Status Codes. More...
enum | qm_usb_ep_status_t { QM_USB_EP_SETUP, QM_USB_EP_DATA_OUT, QM_USB_EP_DATA_IN }
| USB Endpoint Callback Status Codes. More...
enum | qm_usb_ep_type_t { QM_USB_EP_CONTROL = 0, QM_USB_EP_BULK = 2, QM_USB_EP_INTERRUPT = 3 }
| USB Endpoint type. More...

## Functions
int | qm_usb_attach (const qm_usb_t usb)
| Attach the USB device. More...
int | qm_usb_detach (const qm_usb_t usb)
| Detach the USB device. More...
int | qm_usb_reset (const qm_usb_t usb)
| Reset the USB device controller back to it's initial state. More...
int | qm_usb_set_address (const qm_usb_t usb, const uint8_t addr)
| Set USB device address. More...
int | qm_usb_set_status_callback (const qm_usb_t usb, const qm_usb_status_callback_t cb)
| Set USB device controller status callback. More...
int | qm_usb_ep_set_config (const qm_usb_t usb, const qm_usb_ep_config_t *const cfg)
| Configure endpoint. More...
int | qm_usb_ep_set_stall_state (const qm_usb_t usb, const qm_usb_ep_idx_t ep, const bool is_stalled)
| Set / Clear stall condition for the selected endpoint. More...
int | qm_usb_ep_is_stalled (const qm_usb_t usb, const qm_usb_ep_idx_t ep, bool *const stalled)
| Check stall condition for the selected endpoint. More...
int | qm_usb_ep_halt (const qm_usb_t usb, const qm_usb_ep_idx_t ep)
| Halt the selected endpoint. More...
int | qm_usb_ep_enable (const qm_usb_t usb, const qm_usb_ep_idx_t ep)
| Enable the selected endpoint. More...
int | qm_usb_ep_disable (const qm_usb_t usb, const qm_usb_ep_idx_t ep)
| Disable the selected endpoint. More...
int | qm_usb_ep_flush (const qm_usb_t usb, const qm_usb_ep_idx_t ep)
| Flush the selected IN endpoint TX FIFO. More...
int | qm_usb_ep_write (const qm_usb_t usb, const qm_usb_ep_idx_t ep, const uint8_t *const data, const uint32_t len, uint32_t *const ret_bytes)
| Write data to the specified IN endpoint. More...
int | qm_usb_ep_read (const qm_usb_t usb, const qm_usb_ep_idx_t ep, uint8_t *const data, const uint32_t max_len, uint32_t *const read_bytes)
| Read data from OUT endpoint. More...
int | qm_usb_ep_get_bytes_read (const qm_usb_t usb, const qm_usb_ep_idx_t ep, uint32_t *const read_bytes)
| Check how many bytes are available on OUT endpoint. More...

## Detailed Description

USB peripheral driver for Quark Microcontrollers.

## Typedef Documentation

typedef void(* qm_usb_status_callback_t)(void *data, int error, qm_usb_status_t status)

Callback function signature for the device status.

Parameters

  [in] | data | The callback user data.
  [in] | error | 0 on success. Negative errno for possible error codes.
  [in] | status | USB Controller Driver status.

Definition at line 82 of file qm_usb.h.

## Enumeration Type Documentation

enum qm_usb_ep_status_t

USB Endpoint Callback Status Codes.

Enumerator
QM_USB_EP_SETUP | SETUP received.
QM_USB_EP_DATA_OUT | Out transaction on this EP.
QM_USB_EP_DATA_IN | In transaction on this EP.

Definition at line 33 of file qm_usb.h.

enum qm_usb_ep_type_t

USB Endpoint type.

Enumerator
QM_USB_EP_CONTROL | Control endpoint.
QM_USB_EP_BULK | Bulk type endpoint.
QM_USB_EP_INTERRUPT | Interrupt type endpoint.

Definition at line 42 of file qm_usb.h.

enum qm_usb_status_t

USB Driver Status Codes.

Enumerator
QM_USB_RESET | USB reset.
QM_USB_CONNECTED | USB connection ready and enumeration done.
QM_USB_CONFIGURED | USB configuration completed.
QM_USB_DISCONNECTED | USB connection lost.
QM_USB_SUSPEND | USB connection suspended by the HOST.
QM_USB_RESUME | USB connection resumed by the HOST.

Definition at line 21 of file qm_usb.h.

## Function Documentation

int qm_usb_attach | ( | const qm_usb_t | usb | ) |

Attach the USB device.

Upon success, the USB PLL is enabled, and the USB device is now capable of transmitting and receiving on the USB bus and of generating interrupts.

Parameters

  [in] | usb | Which USB module to perform action.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 416 of file qm_usb.c.

References clk_sys_usb_enable().

int qm_usb_detach | ( | const qm_usb_t | usb | ) |

Detach the USB device.

Upon success, the USB hardware PLL is powered down and USB communication is disabled.

Parameters

  [in] | usb | Which USB module to perform action.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 458 of file qm_usb.c.

References clk_sys_usb_disable().

int qm_usb_ep_disable | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep
| ) |  |

Disable the selected endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 697 of file qm_usb.c.

int qm_usb_ep_enable | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep
| ) |  |

Enable the selected endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 664 of file qm_usb.c.

int qm_usb_ep_flush | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep
| ) |  |

Flush the selected IN endpoint TX FIFO.

RX FIFO is global and cannot be flushed per endpoint. Thus, this function only applies to endpoints of direction IN.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table. Must be of IN direction.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 727 of file qm_usb.c.

References clk_sys_udelay().

int qm_usb_ep_get_bytes_read | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep,
|  | uint32_t *const | read_bytes
| ) |  |

Check how many bytes are available on OUT endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table. Must be of OUT direction.
  [out] | read_bytes | Number of bytes read. Must not be null.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 857 of file qm_usb.c.

int qm_usb_ep_halt | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep
| ) |  |

Halt the selected endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 609 of file qm_usb.c.

References qm_usb_ep_set_stall_state().

int qm_usb_ep_is_stalled | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep,
|  | bool *const | stalled
| ) |  |

Check stall condition for the selected endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table.
  [out] | stalled | Endpoint stall state. Must not be NULL.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 640 of file qm_usb.c.

int qm_usb_ep_read | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep,
|  | uint8_t *const | data,
|  | const uint32_t | max_len,
|  | uint32_t *const | read_bytes
| ) |  |

Read data from OUT endpoint.

This function is called by the Endpoint handler function, after an OUT interrupt has been received for that EP.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table. Must be of OUT direction.
  [in] | data | Pointer to data to read to. Must not be null.
  [in] | max_len | Length of data requested to be read.
  [out] | read_bytes | Number of bytes read.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 791 of file qm_usb.c.

int qm_usb_ep_set_config | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_config_t *const | cfg
| ) |  |

Configure endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | cfg | Endpoint configuration.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 495 of file qm_usb.c.

References qm_usb_ep_config_t::max_packet_size, QM_USB_EP_BULK, QM_USB_EP_CONTROL, QM_USB_EP_INTERRUPT, and qm_usb_ep_config_t::type.

int qm_usb_ep_set_stall_state | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep,
|  | const bool | is_stalled
| ) |  |

Set / Clear stall condition for the selected endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table.
  [in] | is_stalled | Endpoint stall state to be set.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 578 of file qm_usb.c.

Referenced by qm_usb_ep_halt().

int qm_usb_ep_write | ( | const qm_usb_t | usb,
|  | const qm_usb_ep_idx_t | ep,
|  | const uint8_t *const | data,
|  | const uint32_t | len,
|  | uint32_t *const | ret_bytes
| ) |  |

Write data to the specified IN endpoint.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | ep | Endpoint index corresponding to the one listed in the device configuration table. Must be of IN direction.
  [in] | data | Pointer to data to write.
  [in] | len | Length of data requested to write. This may be zero for a zero length status packet.
  [out] | ret_bytes | Bytes scheduled for transmission. This value may be NULL if the application expects all bytes to be written.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 761 of file qm_usb.c.

int qm_usb_reset | ( | const qm_usb_t | usb | ) |

Reset the USB device controller back to it's initial state.

Performs the Core Soft Reset from the USB controller. This means that all internal state machines are reset to the IDLE state, all FIFOs are flushed and all ongoing transactions are terminated.

Note
  This function does NOT disable the USB clock PLL.

Parameters

  [in] | usb | Which USB module to perform action.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 476 of file qm_usb.c.

int qm_usb_set_address | ( | const qm_usb_t | usb,
|  | const uint8_t | addr
| ) |  |

Set USB device address.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | addr | USB Device Address.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 482 of file qm_usb.c.

int qm_usb_set_status_callback | ( | const qm_usb_t | usb,
|  | const qm_usb_status_callback_t | cb
| ) |  |

Set USB device controller status callback.

Parameters

  [in] | usb | Which USB module to perform action.
  [in] | cb | USB Device Status callback.

Returns
  Standard errno return type for QMSI.

Return values

  0 | on success.
  Negative | errno for possible error codes.

Definition at line 848 of file qm_usb.c.