Control Transfer Functionality

Descriptor Requests

The module handles the following descriptor requests:

Device
Configuration
String

It does not support (replies with STALL to USB host controller):

Interface
DeviceQual
OtherSpeedConf
InterfacePower

All other descriptor requests (HID, ...) are made available to the application code through the hal_usb_cb_device_req_t callback.

The module does not support SetDescriptor requests

Feature Requests

The module handles the following feature requests:

DeviceRemoteWakeup
EndpointHalt

It does not support (replies with STALL to USB host controller) any other feature requests yet

Configuration Requests

The module do only support setting configuration 0 (sets the adressed state) and 1. Other configurations replies with STALL. Several configurations for a device is not implemented.

Alternative Interface Requests

Setting and getting alternative interfaces are not supported (replies with STALL to USB host controller)

Sync Frame Requests

Not supported

Class Specific Requests

All class specific requests are made available to the application code through the hal_usb_cb_device_req_t callback.

Endpoint Functionality

All available IN and OUT endpoints are avialable to the application through the hal_usb_send_packet, hal_usb_receive_packet functions and the callbacks registered for the endpoint. The callback functions are called when the host replies with an ACK for having received a packet or when the host has sent an OUT packet.

Isochronos endpoints are not supported in this version of USB HAL.

Data Structures
struct	hal_usb_device_req
struct	hal_usb_t
Defines
#define	USB_BM_STATE_CONFIGURED 0x01
#define	USB_BM_STATE_ALLOW_REMOTE_WAKEUP 0x02
#define	USB_BM_STATE_HOST_WU 0x04
Typedefs
typedef hal_usb_dev_req_resp_t(*	hal_usb_cb_device_req_t )(hal_usb_device_req device_req, uint8_t data_ptr, uint8_t size) large reentrant
typedef uint8_t(*	hal_usb_cb_endpoint_t )(uint8_t adr_ptr, uint8_t size) large reentrant
typedef void(*	hal_usb_cb_resume_t )() large reentrant
typedef void(*	hal_usb_cb_suspend_t )(uint8_t allow_remote_wu) large reentrant
typedef void(*	hal_usb_cb_reset_t )() large reentrant
Enumerations
enum	hal_usb_state_t { ATTACHED, POWERED, DEFAULT, ADDRESSED, CONFIGURED, SUSPENDED }
enum	hal_usb_dev_req_resp_t { STALL, NAK, ACK, NO_RESPONSE, DATA, EMPTY_RESPONSE }
Functions
void	hal_usb_init (_Bool usb_disconnect, hal_usb_cb_device_req_t device_req, hal_usb_cb_reset_t reset, hal_usb_cb_resume_t resume, hal_usb_cb_suspend_t suspend)
void	hal_usb_send_data (uint8_t ep_in_num, uint8_t *buffer, uint8_t bytes_to_send)
void	hal_usb_endpoint_config (uint8_t ep_num, uint8_t ep_size, hal_usb_cb_endpoint_t endpoint_isr)
void	hal_usb_endpoint_stall (uint8_t ep_num, _Bool stall)
hal_usb_state_t	hal_usb_get_state ()
uint8_t	hal_usb_get_address ()
void	hal_usb_wakeup ()
void	hal_usb_reset ()
void	hal_usb_bus_disconnect ()
void	hal_usb_bus_connect ()
void	hal_usb_sleep ()
Variables
hal_usb_t volatile	g_hal_usb

Define Documentation

#define USB_BM_STATE_CONFIGURED 0x01

Definition at line 90 of file hal_usb.h.

#define USB_BM_STATE_ALLOW_REMOTE_WAKEUP 0x02

Definition at line 91 of file hal_usb.h.

#define USB_BM_STATE_HOST_WU 0x04

Definition at line 92 of file hal_usb.h.

Typedef Documentation

typedef hal_usb_dev_req_resp_t(* hal_usb_cb_device_req_t)(hal_usb_device_req *device_req, uint8_t **data_ptr, uint8_t *size) large reentrant

Callback function that is called when a class request is received. The type of class request is determined by the interface the request is for. If interface 1 is a HID interface the request is a HID class request.

Parameters:

std_req	The complete request.
data_ptr	Pointer to pointer to data(descriptor struct) the function wants to send back to USB-host
size	Size of data the function wants to send back to USB-host

Definition at line 159 of file hal_usb.h.

typedef uint8_t(* hal_usb_cb_endpoint_t)(uint8_t *adr_ptr, uint8_t *size) large reentrant

Callback function that is called when an endpoint interrupt occurs

Parameters:

adr_ptr	IN endpoint: Pointer to address containing data to send. OUT endpoint: Pointer to address containg data received.
size	IN endpoint: Number of bytes to send. OUT endpoint: number of bytes received.

Return values:

Bit	7 Set: STALL request
Bit	6 Set: NACK request
Bit	5..0 : Bytes to send

Definition at line 168 of file hal_usb.h.

typedef void(* hal_usb_cb_resume_t)() large reentrant

Callback function that is called when a resume is signalled on the bus. A resume is signalled by the Data K state. For full-speed devices this is Differential "0". Differential "0": D-> Voh(main) and D+ < Vol(max).

Definition at line 174 of file hal_usb.h.

typedef void(* hal_usb_cb_suspend_t)(uint8_t allow_remote_wu) large reentrant

Callback function that is called when a suspend condition occurs.

Parameters:

can_resume Set to 1 if the device is allowed to wake up the host controller

See also:: hal_usb_state_t

Definition at line 181 of file hal_usb.h.

typedef void(* hal_usb_cb_reset_t)() large reentrant

Callback function that is called when a reset condition occurs.

Definition at line 186 of file hal_usb.h.

Enumeration Type Documentation

enum hal_usb_state_t

An enum describing the USB state

The states described in this enum are found in Chapter 9 of the USB 2.0 specification

Enumerator:

ATTACHED	Device is attached to the USB, but is not powered
POWERED	Device is attached to the USB and powered
DEFAULT	Device is attached to the USB and powered and has been reset, but has not been assigned a unique address
ADDRESSED	Device is attached to the USB, powered, has been reset, and a unique device address has been assigned. Device is not configured
CONFIGURED	Device is attached to the USB, powered, has been reset, has a unique address, is configured and is not suspended
SUSPENDED	Device is, at a minimum, attached to the USB and is powered and has not seen bus activity for 3ms. It may also have a unique address and be configured for use. However, because the device is suspended, the host may not use the device configuration

Definition at line 99 of file hal_usb.h.

              { 
    ATTACHED,   
    POWERED,    
    DEFAULT,    
    ADDRESSED,  
    CONFIGURED, 
    SUSPENDED   
} hal_usb_state_t;

enum hal_usb_dev_req_resp_t

An enum describing which reply to send to the control request

Enumerator:

STALL	Respond with STALL
NAK	Respond with NAK
ACK	Respond with ACK (if this is an OUT request)
NO_RESPONSE	Do not respond
DATA	Data is available
EMPTY_RESPONSE	Send an empty response

Definition at line 143 of file hal_usb.h.

             {
    STALL,         
    NAK,           
    ACK,           
    NO_RESPONSE,   
    DATA,          
    EMPTY_RESPONSE 
} hal_usb_dev_req_resp_t;

Function Documentation

void hal_usb_init	(	_Bool	usb_disconnect,
		hal_usb_cb_device_req_t	device_req,
		hal_usb_cb_reset_t	reset,
		hal_usb_cb_resume_t	resume,
		hal_usb_cb_suspend_t	suspend
	)

Function for setting up the USB controller and registering the callbacks

Parameters:

usb_disconnect	Set to true to perform physical disconnect and reconnect. Make sure to enable interrupts as soon as possible after the call to this function.
device_req	Pointer to function to call when a class specific request occur
reset	Pointer to function to call when USB controller detects a reset
resume	Pointer to function to call when USB controller detects a resume
suspend	Pointer to function to call when USB controller detects a suspend

Definition at line 57 of file hal_usb.c.

{
  // Setup descriptors
  g_hal_usb.descs.dev = &g_usb_dev_desc;
  g_hal_usb.descs.conf = &g_usb_conf_desc;
  g_hal_usb.descs.string = &g_usb_string_desc;

  // This is for setting language American English (String descriptor 0 is an array of supported languages)
  g_hal_usb.descs.string_zero[0] = 0x04;
  g_hal_usb.descs.string_zero[1] = 0x03;
  g_hal_usb.descs.string_zero[2] = 0x09;
  g_hal_usb.descs.string_zero[3] = 0x04;

  // Setup state information
  g_hal_usb.state = DEFAULT;
  g_hal_usb.bm_state = 0;
  stall_data_size0 = 0;

  // Setconfig configuration information
  g_hal_usb.current_config = 0;
  g_hal_usb.current_alt_interface = 0;

  // Setup callbacks
  g_hal_usb.device_req = device_req;
  g_hal_usb.reset = reset;
  g_hal_usb.resume = resume;
  g_hal_usb.suspend = suspend;

  // Disconnect from USB-bus if we are in this routine from a power on and not a soft reset
  if(usb_disconnect)
  {
    usbcs |= 0x08; // disconnect
    delay_ms(50);
    usbcs &= ~(0x08); // connect
  }

  // Setup interrupts
  USBWU = 1; // USBWU is mapped to IEN1.3
  USB = 1; // USBIRQ is mapped to IEN1.4

  usbien = 0x1d; // ibnie -5 4 - uresir 3 - suspir, 0 - sudavir

  in_ien = 0x01;
  in_irq = 0x1f;
  out_ien = 0x01;
  out_irq = 0x1f;

  // Setup the USB RAM with some OK default values. Note that isochronos is not set up yet.
  bout1addr = 16;
  bout2addr = 32;
  bout3addr = 48;
  bout4addr = 64;
  bout5addr = 80;

  binstaddr = 0xc0;
  bin1addr = 16;
  bin2addr = 32;
  bin3addr = 48;
  bin4addr = 64;
  bin5addr = 80;

  // Set all endpoints to not valid (except EP0IN and EP0OUT)
  inbulkval = 0x01;
  outbulkval = 0x01;
  inisoval = 0x00;
  outisoval = 0x00;
}

void hal_usb_send_data	(	uint8_t	ep_in_num,
		uint8_t *	buffer,
		uint8_t	bytes_to_send
	)

Function to send a packet to host (IN endpoint)

Parameters:

ep_in_num	IN endpointer number
buffer	Pointer to buffer containing data to send
bytes_to_send	Number of bytes to send.

Definition at line 230 of file hal_usb.c.

{
  uint8_t i;

  uint8_t xdata *buf_ptr;
  uint8_t xdata *bc_ptr;

  // Calculate the buffer pointer and byte count pointer
  buf_ptr = CALCULATE_BUF_IN_PTR(ep_num);
  bc_ptr = CALCULATE_BC_IN_PTR(ep_num);

  // Copy the data into the USB controller
  for( i = 0; i < count; i++ )
  {
    buf_ptr[i] = array[i];
  }

  // Set the number of bytes we want to send to USB-host. This also trigger sending of data to USB-host.
  *bc_ptr = count;
}

void hal_usb_endpoint_config	(	uint8_t	ep_num,
		uint8_t	ep_size,
		hal_usb_cb_endpoint_t	endpoint_isr
	)

Function to register callbacks for given endpoints To register a callback one have to have a function with an argument list equal to usb_endpoint_cb_t.

Parameters:

ep_num	Endpoint number. If MSB is set it indicates this is an IN endpoint.
ep_size	The maximum size of one packet for this endpoint
endpoint_isr	Pointer to function that is called when host issues a request on the given endpoint. Set to 0 to unregister function.

Definition at line 161 of file hal_usb.c.

{
  uint8_t xdata *bc_ptr;
  uint8_t temp = (ep_num & 0x7f) - 1;
  uint8_t stemp = 1 << (ep_num & 0x7f);

  // Dummy use of variable to get rid of warning
  ep_size = 0;

  if((ep_num & 0x80 ) == 0x80) // MSB set indicates IN endpoint
  {
    i_endpoint_in_isr[temp] = endpoint_isr;
    if(endpoint_isr != NULL)
    {
      // Add the callback, enable the interrupt and validate the endpoint
      in_ien |= stemp; 
      inbulkval |= stemp;
    }
    else
    {
      // Remove the callback, disable the interrupt and invalidate the endpoint
      in_ien &= ~stemp;
      inbulkval &= ~stemp;
    }
  }
  else // OUT endpoint
  {
    i_endpoint_out_isr[temp] = endpoint_isr;
    if(endpoint_isr != NULL)
    {
      // Add the callback, enable the interrupt and validate the endpoint
      out_ien |= stemp;
      outbulkval |= stemp;

      // Have to write a dummy value to the OUTxBC register to get interrupts
      bc_ptr = CALCULATE_BC_OUT_PTR(ep_num);
      *bc_ptr = 0xff;
    }
    else
    {
      // Remove the callback, disable the interrupt and invalidate the endpoint
      out_ien &= ~stemp;
      outbulkval &= ~stemp;
    }
  }
}

void hal_usb_endpoint_stall	(	uint8_t	ep_num,
		_Bool	stall
	)

Function to stall or unstall an endpoint

Parameters:

ep_num	Endpoint number. If MSB is set it indicates this is an IN endpoint.
stall	1 - stall the endpoint. 0 - unstall the endpoint.

Definition at line 125 of file hal_usb.c.

{
  uint8_t temp;
  uint8_t xdata *cs_ptr;

  temp = 2 * ((ep_num & 0x7f) - 1);

  // Calculate register address
  if((ep_num & 0x80 ) == 0x80) // IN endpoints
  {
    // Calculate control and status register for IN endpoint
    cs_ptr = (uint8_t xdata*)(&in1cs + temp);
  }
  else // OUT endpoints
  {
    // Calculate control and status register for OUT endpoint
    cs_ptr = (uint8_t xdata*)(&out1cs + temp);
  }

  if(stall == true)
  {
    // Set the stall bit
    *cs_ptr = 0x01;
  }
  else
  {
    // Clear the stall bit
    *cs_ptr = 0x00;
  }
}

hal_usb_state_t hal_usb_get_state ( )

Function returning the current state of the USB controller

See also:: usb_stat_t

Definition at line 225 of file hal_usb.c.

{
  return g_hal_usb.state;
}

uint8_t hal_usb_get_address ( )

Function returning the assigned address for the device

Definition at line 156 of file hal_usb.c.

{
  return fnaddr;
}

void hal_usb_wakeup ( )

Function to initiate a remote wakeup of the USB host

Definition at line 208 of file hal_usb.c.

{
  // We can only issue a wakeup if the host has allowed us to do so
  if((g_hal_usb.bm_state & USB_BM_STATE_ALLOW_REMOTE_WAKEUP) == USB_BM_STATE_ALLOW_REMOTE_WAKEUP)
  {
    USBCON = 0x40;  // Wakeup the USB controller via remote pin
    delay_ms(1);    // Wait until the USB clock starts
    USBCON = 0x00;
  }
}

void hal_usb_reset ( )

Function to initiate a hardware reset of the USB-controller

Definition at line 219 of file hal_usb.c.

{
  SWRST = 1;  // Perform a hardware reset of the USB controller
}

void hal_usb_bus_disconnect ( )

Function disconnecting the USB-controller from the USB bus

Definition at line 251 of file hal_usb.c.

{
  usbcs |= 0x08; // disconnect
}

void hal_usb_bus_connect ( )

Function connecting the USB-controller to the USB bus

Definition at line 256 of file hal_usb.c.

{
  usbcs &= ~(0x08); // connect
}

void hal_usb_sleep ( )

Function stopping the clock to the usb controller or by other means powers it down

Definition at line 261 of file hal_usb.c.

{
  USBSLP = 1;
}

Variable Documentation

hal_usb_t volatile g_hal_usb

Definition at line 54 of file hal_usb.c.

Universal Serial Bus (hal_usb) [nRF24LU1+ HAL]

Control Transfer Functionality

Descriptor Requests

Feature Requests

Configuration Requests

Alternative Interface Requests

Sync Frame Requests

Class Specific Requests

Endpoint Functionality

Data Structures

Defines

Typedefs

Enumerations

Functions

Variables

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation

Universal Serial Bus (hal_usb)
[nRF24LU1+ HAL]