USB Component  Version 6.13.6
MDK Middleware for USB Device and Host Communication
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages

User API reference of the Communication Device Class (NCM). More...

Functions

int32_t USBD_CDC_NCM_NTB_IN_Initialize (uint8_t instance)
 Clear the active NTB (prepared for sending) More...
 
int32_t USBD_CDC_NCM_NTB_IN_CreateNDP (uint8_t instance, uint8_t num_datagrams)
 Create a new NDP in the NTB (datagrams can be added to it) More...
 
int32_t USBD_CDC_NCM_NTB_IN_WriteDatagram (uint8_t instance, const uint8_t *buf, uint32_t len)
 Add a datagram into the active NDP of the NTB to be sent. More...
 
int32_t USBD_CDC_NCM_NTB_IN_Send (uint8_t instance)
 Send the active NTB. More...
 
int32_t USBD_CDC_NCM_NTB_IN_IsSent (uint8_t instance)
 Check if NTB was sent and new NTB can be prepared. More...
 
int32_t USBD_CDC_NCM_NTB_OUT_IsReceived (uint8_t instance)
 Check if NTB was received and is available for processing. More...
 
int32_t USBD_CDC_NCM_NTB_OUT_Release (uint8_t instance)
 Flush the received NTB and release memory for reception of a new NTB. More...
 
int32_t USBD_CDC_NCM_NTB_OUT_ProcessNDP (uint8_t instance)
 Process the next NDP in the received NTB. More...
 
uint32_t USBD_CDC_NCM_NTB_OUT_GetDatagramSize (uint8_t instance)
 Get size of a datagram from the active NDP of the received NTB. More...
 
int32_t USBD_CDC_NCM_NTB_OUT_ReadDatagram (uint8_t instance, uint8_t *buf, uint32_t max_len)
 Read a datagram from the active NDP of the received NTB. More...
 
int32_t USBD_CDC_NCM_NTB_IN_RawSend (uint8_t instance, const uint8_t *buf, uint32_t len)
 Send already prepared NTB (for this option value of define in configuration USBD_CDCn_NCM_RAW_ENABLE has to be 1) More...
 
uint32_t USBD_CDC_NCM_NTB_OUT_RawGetSize (uint8_t instance)
 Get size of the received NTB. More...
 
int32_t USBD_CDC_NCM_NTB_OUT_RawReceive (uint8_t instance, uint8_t *buf, uint32_t max_len)
 Receive an NDP (for this option value of define in configuration USBD_CDCn_NCM_RAW_ENABLE has to be 1) More...
 
int32_t USBD_CDC_NCM_Notify_NetworkConnection (uint8_t instance, uint16_t status)
 Report whether or not the physical layer (modem, Ethernet PHY, etc.) link is up to the USB Host. More...
 
int32_t USBD_CDC_NCM_Notify_ConnectionSpeedChange (uint8_t instance, uint32_t us_bitrate, uint32_t ds_bitrate)
 Report a change in upstream or downstream speed of the networking connection to the USB Host. More...
 
void USBD_CDCn_NCM_Initialize (void)
 Callback function called during USBD_Initialize to initialize the USB CDC class instance (NCM) More...
 
void USBD_CDCn_NCM_Uninitialize (void)
 Callback function called during USBD_Uninitialize to de-initialize the USB CDC class instance (NCM) More...
 
void USBD_CDCn_NCM_Reset (void)
 Callback function called upon USB Bus Reset signaling. More...
 
void USBD_CDCn_NCM_Start (void)
 Callback function called when USB Host changes data interface from alternate 0 to alternate 1 (activates data interface) More...
 
void USBD_CDCn_NCM_Stop (void)
 Callback function called when USB Host changes data interface from alternate 1 to alternate 0 (de-activates data interface) More...
 
bool USBD_CDCn_NCM_SetEthernetMulticastFilters (const uint8_t *addr_list, uint16_t num_of_filters)
 Callback function called upon USB Host request to set the Ethernet device multicast filters. More...
 
bool USBD_CDCn_NCM_SetEthernetPowerManagementPatternFilter (uint16_t filter_number, const uint8_t *pattern_filter, uint16_t pattern_filter_size)
 Callback function called upon USB Host request to set up the specified Ethernet power management pattern filter. More...
 
bool USBD_CDCn_NCM_GetEthernetPowerManagementPatternFilter (uint16_t filter_number, uint16_t *pattern_active)
 Callback function called upon USB Host request to retrieve the status of the specified Ethernet power management pattern filter. More...
 
bool USBD_CDCn_NCM_SetEthernetPacketFilter (uint16_t packet_filter_bitmap)
 Callback function called upon USB Host request to configure device Ethernet packet filter settings. More...
 
bool USBD_CDCn_NCM_GetEthernetStatistic (uint16_t feature_selector, uint32_t *data)
 Callback function called upon USB Host request to retrieve a statistic based on the feature selector. More...
 
bool USBD_CDCn_NCM_GetNtbParameters (CDC_NCM_NTB_PARAM *ntb_params)
 Callback function called upon USB Host request to retrieve the parameters that describe NTBs for each direction. More...
 
bool USBD_CDCn_NCM_GetNetAddress (uint8_t *net_addr)
 Callback function called upon USB Host request to return the USB Device's current EUI-48 station address. More...
 
bool USBD_CDCn_NCM_SetNetAddress (const uint8_t *net_addr)
 Callback function called upon USB Host request to set the USB Device's current EUI-48 station address. More...
 
bool USBD_CDCn_NCM_GetNtbFormat (uint16_t *ntb_format)
 Callback function called upon USB Host request to return the NTB data format currently being used. More...
 
bool USBD_CDCn_NCM_SetNtbFormat (uint16_t ntb_format)
 Callback function called upon USB Host request to select the format of NTB to be used for NTBs transmitted to the USB Host. More...
 
bool USBD_CDCn_NCM_GetNtbInputSize (uint32_t *ntb_input_size)
 Callback function called upon USB Host request to return NTB input size currently being used. More...
 
bool USBD_CDCn_NCM_SetNtbInputSize (uint32_t ntb_input_size)
 Callback function called upon USB Host request to select the maximum size of NTB that is permitted to be sent to the USB Host. More...
 
bool USBD_CDCn_NCM_GetMaxDatagramSize (uint16_t *max_datagram_size)
 Callback function called upon USB Host request to return the currently effective maximum datagram size. More...
 
bool USBD_CDCn_NCM_SetMaxDatagramSize (uint16_t max_datagram_size)
 Callback function called upon USB Host request to select the maximum datagram size that can be sent in an NTB. More...
 
bool USBD_CDCn_NCM_GetCrcMode (uint16_t *crc_mode)
 Callback function called upon USB Host request to return the currently selected CRC mode. More...
 
bool USBD_CDCn_NCM_SetCrcMode (uint16_t crc_mode)
 Callback function called upon USB Host request to control CRC mode. More...
 
void USBD_CDCn_NCM_NTB_IN_Sent (void)
 Callback function called when NTB was successfully sent. More...
 
void USBD_CDCn_NCM_NTB_OUT_Received (void)
 Callback function called when NTB was successfully received. More...
 

Description

User API reference of the Communication Device Class (NCM).

Function Documentation

int32_t USBD_CDC_NCM_Notify_ConnectionSpeedChange ( uint8_t  instance,
uint32_t  us_bitrate,
uint32_t  ds_bitrate 
)

Report a change in upstream or downstream speed of the networking connection to the USB Host.

Parameters
[in]instanceInstance of CDC class.
[in]us_bitrateUpstream bitrate.
[in]ds_bitrateDownstream bitrate.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_Notify_ConnectionSpeedChange report to the USB Host any change in the upstream or downstream speed of the networking connection.

The argument instance specifies the instance of the CDC class.

The argument us_bitrate specifies the upstream bitrate.

The argument ds_bitrate specifies the downstream bitrate.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_Notify_NetworkConnection ( uint8_t  instance,
uint16_t  status 
)

Report whether or not the physical layer (modem, Ethernet PHY, etc.) link is up to the USB Host.

Parameters
[in]instanceInstance of CDC class.
[in]statusConnection status :
  • value 0 : Disconnected
  • value 1 : Connected
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_Notify_NetworkConnection reports to the USB Host whether the physical layer (modem, Ethernet PHY, etc.) link is up.

The argument instance specifies the instance of the CDC class.

The argument status specifies the connection status.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_CreateNDP ( uint8_t  instance,
uint8_t  num_datagrams 
)

Create a new NDP in the NTB (datagrams can be added to it)

Parameters
[in]instanceInstance of CDC class.
[in]num_datagramsMaximum number of datagrams that NDP will contain.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_CreateNDP creates a new NDP in the NTB so that datagrams can be added to it.

The argument instance specifies the instance of the CDC class.

The argument num_datagrams specifies the maximum number of datagrams that the NDP will contain.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_Initialize ( uint8_t  instance)

Clear the active NTB (prepared for sending)

Parameters
[in]instanceInstance of CDC class.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_Initialize clears the active NTB and initializes it for adding of NDPs and datagrams.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_IsSent ( uint8_t  instance)

Check if NTB was sent and new NTB can be prepared.

Parameters
[in]instanceInstance of CDC class.
Returns
NTB sent status or error code :
  • value 1 : NTB was sent
  • value 0 : NTB sending is in progress
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_IsSent checks whether the NTB was sent and a new one can be prepared.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_RawSend ( uint8_t  instance,
const uint8_t *  buf,
uint32_t  len 
)

Send already prepared NTB (for this option value of define in configuration USBD_CDCn_NCM_RAW_ENABLE has to be 1)

Parameters
[in]instanceInstance of CDC class.
[in]bufBuffer containing NTB.
[in]lenSize of NTB.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_RawSend sends an already prepared NTB. For this option, the value of the #define USBD_CDCn_NCM_RAW_ENABLE in the configuration has to be '1'.

The argument instance specifies the instance of the CDC class.

The argument buf specifies the buffer containing the NTB.

The argument len specifies the size of the NTB.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_Send ( uint8_t  instance)

Send the active NTB.

Parameters
[in]instanceInstance of CDC class.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_Send transmits the active NTB.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_IN_WriteDatagram ( uint8_t  instance,
const uint8_t *  buf,
uint32_t  len 
)

Add a datagram into the active NDP of the NTB to be sent.

Parameters
[in]instanceInstance of CDC class.
[in]bufBuffer containing data bytes to write.
[in]lenNumber of bytes to write.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_IN_WriteDatagram adds a datagram into the active NDP of the NTB to be sent.

The argument instance specifies the instance of the CDC class.

The argument buf is a buffer containing the data to be written.

The argument len specifies the number of bytes to be written.

Code Example
Refer to the CDC (NCM) User Code Template

uint32_t USBD_CDC_NCM_NTB_OUT_GetDatagramSize ( uint8_t  instance)

Get size of a datagram from the active NDP of the received NTB.

Parameters
[in]instanceInstance of CDC class.
Returns
Number of bytes available in the datagram.

The function USBD_CDC_NCM_NTB_OUT_GetDatagramSize returns the size of a datagram from the active NDP of the received NTB.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_OUT_IsReceived ( uint8_t  instance)

Check if NTB was received and is available for processing.

Parameters
[in]instanceInstance of CDC class.
Returns
NTB available or error code :
  • value 1 : received NTB is available
  • value 0 : no received NTB is available
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_OUT_IsReceived checks whether the NTB was received and can be processed.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_OUT_ProcessNDP ( uint8_t  instance)

Process the next NDP in the received NTB.

Parameters
[in]instanceInstance of CDC class.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_OUT_ProcessNDP processes the next NDP in the received NTB.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

uint32_t USBD_CDC_NCM_NTB_OUT_RawGetSize ( uint8_t  instance)

Get size of the received NTB.

Parameters
[in]instanceInstance of CDC class.
Returns
Number of bytes available in the NTB.

The function USBD_CDC_NCM_NTB_OUT_RawGetSize returns the number of bytes available in the NTB.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_OUT_RawReceive ( uint8_t  instance,
uint8_t *  buf,
uint32_t  max_len 
)

Receive an NDP (for this option value of define in configuration USBD_CDCn_NCM_RAW_ENABLE has to be 1)

Parameters
[in]instanceInstance of CDC class.
[out]bufBuffer that receives NTB.
[in]max_lenMaximum number of bytes that buffer can accept.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_OUT_RawReceive receives an NDP For this option, the value of the #define USBD_CDCn_NCM_RAW_ENABLE in the configuration has to be '1'.

The argument instance specifies the instance of the CDC class.

The argument buf specifies the buffer that receives the NTB.

The argument max_len specifies the maximum number of bytes that are accepted by the buffer (must be multiple of Bulk Out endpoint maximum packet size).

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_OUT_ReadDatagram ( uint8_t  instance,
uint8_t *  buf,
uint32_t  max_len 
)

Read a datagram from the active NDP of the received NTB.

Parameters
[in]instanceInstance of CDC class.
[out]bufBuffer that receives read data.
[in]max_lenMaximum number of bytes to read.
Returns
number of bytes read from the datagram or error code :
  • value >= 0 : number of bytes read from the datagram
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_OUT_ReadDatagram reads a datagram from the active NDP of the received NTB.

The argument instance specifies the instance of the CDC class.

The argument buf specifies the buffer that receives the data that is read.

The argument max_len specifies the maximum number of bytes to be read.

Code Example
Refer to the CDC (NCM) User Code Template

int32_t USBD_CDC_NCM_NTB_OUT_Release ( uint8_t  instance)

Flush the received NTB and release memory for reception of a new NTB.

Parameters
[in]instanceInstance of CDC class.
Returns
function execution status :
  • value 0 : success
  • value < 0 : error code

The function USBD_CDC_NCM_NTB_OUT_Release flushes the received NTB and releases the memory for the reception of a new NTB.

The argument instance specifies the instance of the CDC class.

Code Example
Refer to the CDC (NCM) User Code Template

bool USBD_CDCn_NCM_GetCrcMode ( uint16_t *  crc_mode)

Callback function called upon USB Host request to return the currently selected CRC mode.

Parameters
[out]crc_modePointer to current CRC mode.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetCrcMode is called when the USB Host requests to return the currently selected CRC mode.

The argument crc_mode is a pointer to the current CRC mode.

Code Example

bool USBD_CDCn_NCM_GetCrcMode (uint16_t *crc_mode) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x10) != 0)
crc_mode = NCM_State.crc_mode;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_GetEthernetPowerManagementPatternFilter ( uint16_t  filter_number,
uint16_t *  pattern_active 
)

Callback function called upon USB Host request to retrieve the status of the specified Ethernet power management pattern filter.

Parameters
[in]filter_numberFilter number.
[out]pattern_activePointer to pattern active boolean.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetEthernetPowerManagementPatternFilter is called when the USB Host retrieves the status of the USB Device's Ethernet power management pattern filter.

The argument filter_number specifies the filter number.

The argument pattern_active is a pointer to the pattern active boolean.

Code Example

bool USBD_CDCn_NCM_GetEthernetPowerManagementPatternFilter (uint16_t filter_number, uint16_t *pattern_active) {
#if (USBD_CDCn_NCM_B_NUMBER_POWER_FILTERS != 0)
pattern_active = (NCM_State.power_filter_active[filter_number / 8] & (1U << (filter_number % 8))) ? 1 : 0;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_GetEthernetStatistic ( uint16_t  feature_selector,
uint32_t *  data 
)

Callback function called upon USB Host request to retrieve a statistic based on the feature selector.

Parameters
[in]feature_selectorFeature Selector.
[out]dataPointer to Statistics Value.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetEthernetStatistic is called when the USB Host tries to retrieve an Ethernet statistic based on the feature selector.

The argument feature_selector specifies the feature selector.

The argument data is a pointer to the statistic's value.

Code Example

bool USBD_CDCn_NCM_GetEthernetStatistic (uint16_t feature_selector, uint32_t *data) {
#if (USBD_CDCn_NCM_BM_ETHERNET_STATISTICS != 0)
if (feature_selector == 0x00U) { return true; }
if (feature_selector > 0x1DU) { return false; }
data = NCM_State.eth_statistics[feature_selector - 1];
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_GetMaxDatagramSize ( uint16_t *  max_datagram_size)

Callback function called upon USB Host request to return the currently effective maximum datagram size.

Parameters
[out]max_datagram_sizePointer to current maximum datagram size.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetMaxDatagramSize is called when the USB Host requests to return the currently effective maximum datagram size used by the USB Device.

The argument max_datagram_size is a pointer to current maximum datagram size.

Code Example

bool USBD_CDCn_NCM_GetMaxDatagramSize (uint16_t *max_datagram_size) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x08) != 0)
max_datagram_size = NCM_State.max_datagram_size;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_GetNetAddress ( uint8_t *  net_addr)

Callback function called upon USB Host request to return the USB Device's current EUI-48 station address.

Parameters
[out]net_addrPointer to EUI-48 current address, in network byte order.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetNetAddress is called when the USB Host requests to return the USB Device's current EUI-48 station address.

The argument net_addr is a pointer to the current EUI-48 network address.

Code Example

bool USBD_CDCn_NCM_GetNetAddress (uint8_t *net_addr) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x02) != 0)
memcpy(net_addr, &NCM_State.net_address, 6);
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_GetNtbFormat ( uint16_t *  ntb_format)

Callback function called upon USB Host request to return the NTB data format currently being used.

Parameters
[out]ntb_formatPointer to NTB format code.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetNtbFormat is called when the USB Host requests to return the NCM Transfer Block (NTBs) data format that is currently being used by the USB Device.

The argument ntb_format is a pointer to the NTB format code.

Code Example

bool USBD_CDCn_NCM_GetNtbFormat (uint16_t *ntb_format) {
ntb_format = NCM_State.ntb_format;
return true;
}
bool USBD_CDCn_NCM_GetNtbInputSize ( uint32_t *  ntb_input_size)

Callback function called upon USB Host request to return NTB input size currently being used.

Parameters
[out]ntb_input_sizePointer to NTB input size.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetNtbInputSize is called when the USB Host requests to return the NCM Transfer Block (NTBs) input size that is currently being used by the USB Device.

The argument ntb_input_size is a pointer to the NTB input size.

Code Example

bool USBD_CDCn_NCM_GetNtbInputSize (uint32_t *ntb_input_size) {
ntb_input_size = NCM_State.ntb_input_size;
return true;
}
bool USBD_CDCn_NCM_GetNtbParameters ( CDC_NCM_NTB_PARAM *  ntb_params)

Callback function called upon USB Host request to retrieve the parameters that describe NTBs for each direction.

Parameters
[out]ntb_paramsPointer to NTB Parameter Structure.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_GetNtbParameters is called when the USB Host requests to return the parameters that describe the NCM Transfer Blocks (NTBs) for each direction.

The argument ntb_params is a pointer to the NTB parameter structure.

Code Example

bool USBD_CDCn_NCM_GetNtbParameters (CDC_NCM_NTB_PARAM *ntb_params) {
ntb_params->wLength = sizeof(CDC_NCM_NTB_PARAM);
ntb_params->bmNtbFormatsSupported = USBD_CDCn_NCM_BM_NTB_FORMATS_SUPPORTED;
ntb_params->dwNtbInMaxSize = USBD_CDCn_NCM_DW_NTB_IN_MAX_SIZE;
ntb_params->wNdpInDivisor = USBD_CDCn_NCM_W_NDP_IN_DIVISOR;
ntb_params->wNdpInPayloadRemainder = USBD_CDCn_NCM_W_NDP_IN_PAYLOAD_REMINDER;
ntb_params->wNdpInAlignment = USBD_CDCn_NCM_W_NDP_IN_ALIGNMENT;
ntb_params->Reserved0 = 0U;
ntb_params->dwNtbOutMaxSize = USBD_CDCn_NCM_DW_NTB_OUT_MAX_SIZE;
ntb_params->wNdpOutDivisor = USBD_CDCn_NCM_W_NDP_OUT_DIVISOR;
ntb_params->wNdpOutPayloadRemainder = USBD_CDCn_NCM_W_NDP_OUT_PAYLOAD_REMINDER;
ntb_params->wNdpOutAlignment = USBD_CDCn_NCM_W_NDP_OUT_ALIGNMENT;
ntb_params->Reserved1 = 0U;
return true;
}
void USBD_CDCn_NCM_Initialize ( void  )

Callback function called during USBD_Initialize to initialize the USB CDC class instance (NCM)

Returns
none.

The function USBD_CDCn_NCM_Initialize initializes the hardware resources of the network device. It is called during USBD_Initialize. The function may be used to allocate resources and initialize peripherals.

Modify this function to the application needs.

Note
Remember to release used resources and de-initialize peripherals using USBD_CDCn_NCM_Uninitialize.

Code Example

// Add code for initialization
ARM_ETH_MAC_CAPABILITIES capabilities;
int32_t status;
MAC_wstr_to_addr(wsMacAddress, (uint8_t *)&MacAddress);
memset(&NCM_State, 0, sizeof(NCM_State));
NCM_State.ntb_input_size = USBD_CDCn_NCM_DW_NTB_IN_MAX_SIZE;
NCM_State.max_datagram_size = USBD_CDCn_NCM_W_MAX_SEGMENT_SIZE;
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x02) != 0)
memcpy(&NCM_State.net_address, &MacAddress, 6);
#endif
NCM_State.packet_filter_bitmap = 0x0CU;
LinkState = ARM_ETH_LINK_DOWN;
LinkInfo.speed = 0U;
LinkInfo.duplex = 0U;
LinkSpeed = 0U;
PacketFilter = ARM_ETH_MAC_ADDRESS_BROADCAST;
FrameIN_Size = 0U;
// Initialize Media Access Controller
capabilities = EthMac->GetCapabilities();
status = EthMac->Initialize(EthMac_Notify);
if (status != ARM_DRIVER_OK) { return; }
status = EthMac->PowerControl(ARM_POWER_FULL);
if (status != ARM_DRIVER_OK) { return; }
status = EthMac->SetMacAddress(&MacAddress);
if (status != ARM_DRIVER_OK) { return; }
// Initialize Physical Media Interface
status = EthPhy->Initialize(EthMac->PHY_Read, EthMac->PHY_Write);
if (status != ARM_DRIVER_OK) { return; }
status = EthPhy->PowerControl(ARM_POWER_FULL);
if (status != ARM_DRIVER_OK) { return; }
status = EthPhy->SetInterface(capabilities.media_interface);
if (status != ARM_DRIVER_OK) { return; }
status = EthPhy->SetMode(ARM_ETH_PHY_AUTO_NEGOTIATE);
if (status != ARM_DRIVER_OK) { return; }
// Create Threads
Connection_ThreadId = osThreadCreate(osThread(Connection_Thread), NULL);
DataIN_ThreadId = osThreadCreate(osThread(DataIN_Thread), NULL);
DataOUT_ThreadId = osThreadCreate(osThread(DataOUT_Thread), NULL);
}
void USBD_CDCn_NCM_NTB_IN_Sent ( void  )

Callback function called when NTB was successfully sent.

Returns
none.

The function USBD_CDCn_NCM_NTB_IN_Sent is called when an NCM Transfer Block (NTBs) has been sent successfully.

Code Example

// Add code for handling request
osSignalSet(DataIN_ThreadId, 1U);
}
void USBD_CDCn_NCM_NTB_OUT_Received ( void  )

Callback function called when NTB was successfully received.

Returns
none.

The function USBD_CDCn_NCM_NTB_OUT_Received is called when an NCM Transfer Block (NTBs) has been received successfully.

Code Example

// Add code for handling request
osSignalSet(DataOUT_ThreadId, 1U);
}
void USBD_CDCn_NCM_Reset ( void  )

Callback function called upon USB Bus Reset signaling.

Returns
none.

The function USBD_CDCn_NCM_Reset resets the network device.

Modify this function to the application's needs.

bool USBD_CDCn_NCM_SetCrcMode ( uint16_t  crc_mode)

Callback function called upon USB Host request to control CRC mode.

Parameters
[in]crc_modeCRC mode :
  • value 0 : CRCs shall not be appended
  • value 1 : CRCs shall be appended
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetCrcMode is called when the USB Host requests to set the CRC mode to be used for data transmissions.

The argument crc_mode is a value of the current CRC mode.

Code Example

bool USBD_CDCn_NCM_SetCrcMode (uint16_t crc_mode) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x10) != 0)
if (crc_mode > 1) { return false; }
NCM_State.crc_mode = crc_mode;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetEthernetMulticastFilters ( const uint8_t *  addr_list,
uint16_t  num_of_filters 
)

Callback function called upon USB Host request to set the Ethernet device multicast filters.

Parameters
[in]addr_listPointer to list of 48-bit Multicast addresses.
[in]num_of_filtersNumber of filters.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetEthernetMulticastFilters is called when the USB Host requests to set the USB Device's Ethernet multicast filters.

The argument addr_list is a pointer to the list of 48-bit Multicast addresses.

The argument num_of_filters specifies the number of filters to be used.

Code Example

bool USBD_CDCn_NCM_SetEthernetMulticastFilters (const uint8_t *addr_list, uint16_t num_of_filters) {
#if (USBD_CDCn_NCM_W_NUMBER_MC_FILTERS != 0)
int32_t status;
if (num_of_filters > (USBD_CDCn_NCM_W_NUMBER_MC_FILTERS & 0x7FFF)) { return false; }
// Add code for handling request
status = EthMac->SetAddressFilter((ARM_ETH_MAC_ADDR *)addr_list, num_of_filters);
if (status != ARM_DRIVER_OK) { return false; }
memcpy(&NCM_State.mc_filters, addr_list, num_of_filters * 6);
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetEthernetPacketFilter ( uint16_t  packet_filter_bitmap)

Callback function called upon USB Host request to configure device Ethernet packet filter settings.

Parameters
[in]packet_filter_bitmapPacket Filter Bitmap.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetEthernetPacketFilter is called when the USB Host requests to configure the USB Device's Ethernet packet filter settings.

The argument packet_filter_bitmap is the packet filter's bitmap.

Code Example

bool USBD_CDCn_NCM_SetEthernetPacketFilter (uint16_t packet_filter_bitmap) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x01) != 0)
int32_t status;
// Add code for handling request
PacketFilter = ((packet_filter_bitmap & 0x01U) ? ARM_ETH_MAC_ADDRESS_ALL : 0) |
((packet_filter_bitmap & 0x02U) ? ARM_ETH_MAC_ADDRESS_MULTICAST : 0) |
((packet_filter_bitmap & 0x08U) ? ARM_ETH_MAC_ADDRESS_BROADCAST : 0);
status = EthMac->Control(ARM_ETH_MAC_CONFIGURE,
LinkInfo.speed << ARM_ETH_MAC_SPEED_Pos |
LinkInfo.duplex << ARM_ETH_MAC_DUPLEX_Pos |
PacketFilter);
if (status != ARM_DRIVER_OK) { return false; }
NCM_State.packet_filter_bitmap = packet_filter_bitmap;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetEthernetPowerManagementPatternFilter ( uint16_t  filter_number,
const uint8_t *  pattern_filter,
uint16_t  pattern_filter_size 
)

Callback function called upon USB Host request to set up the specified Ethernet power management pattern filter.

Parameters
[in]filter_numberFilter number.
[in]pattern_filterPower management pattern filter structure.
[in]pattern_filter_sizeSize of pattern filter structure.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetEthernetPowerManagementPatternFilter is called when the USB Host requests to set up the USB Device's Ethernet power management pattern filter.

The argument filter_number specifies the filter number.

The argument pattern_filter is a pointer to the pattern filter structure.

The argument pattern_filter_size specifies the size of the pattern filter structure.

Code Example

bool USBD_CDCn_NCM_SetEthernetPowerManagementPatternFilter (uint16_t filter_number, const uint8_t *pattern_filter, uint16_t pattern_filter_size) {
#if (USBD_CDCn_NCM_B_NUMBER_POWER_FILTERS != 0)
if (filter_number >= USBD_CDCn_NCM_B_NUMBER_POWER_FILTERS) { return false; }
// Add code for handling request
NCM_State.power_filter_active[filter_number / 8] |= 1U << (filter_number % 8);
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetMaxDatagramSize ( uint16_t  max_datagram_size)

Callback function called upon USB Host request to select the maximum datagram size that can be sent in an NTB.

Parameters
[in]max_datagram_sizeMaximum datagram size.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetMaxDatagramSize is called when the USB Host requests to set the maximum datagram size that can be sent in an NCM Transfer Block (NTBs).

The argument max_datagram_size is a pointer to current maximum datagram size.

Code Example

bool USBD_CDCn_NCM_SetMaxDatagramSize (uint16_t max_datagram_size) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x08) != 0)
if (max_datagram_size > USBD_CDCn_NCM_W_MAX_SEGMENT_SIZE) { return false; }
NCM_State.max_datagram_size = max_datagram_size;
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetNetAddress ( const uint8_t *  net_addr)

Callback function called upon USB Host request to set the USB Device's current EUI-48 station address.

Parameters
[in]net_addrPointer to EUI-48 address, in network byte order.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetNetAddress is called when the USB Host requests to set the USB Device's current EUI-48 station address.

The argument net_addr is a pointer to the EUI-48 network address.

Code Example

bool USBD_CDCn_NCM_SetNetAddress (const uint8_t *net_addr) {
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x02) != 0)
int32_t status;
// Add code for handling request
status = EthMac->SetMacAddress((ARM_ETH_MAC_ADDR *)net_addr);
if (status != ARM_DRIVER_OK) { return false; }
memcpy(&NCM_State.net_address, net_addr, 6);
return true;
#else
return false;
#endif
}
bool USBD_CDCn_NCM_SetNtbFormat ( uint16_t  ntb_format)

Callback function called upon USB Host request to select the format of NTB to be used for NTBs transmitted to the USB Host.

Parameters
[in]ntb_formatNTB format selection :
  • value 0 : NTB-16
  • value 1 : NTB-32
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetNtbFormat is called when the USB Host requests to set the NCM Transfer Block (NTBs) data format to be used by the USB Device for transfers to the host.

The argument ntb_format is a pointer to the NTB format code.

Code Example

bool USBD_CDCn_NCM_SetNtbFormat (uint16_t ntb_format) {
#if (USBD_CDCn_NCM_BM_NTB_FORMATS_SUPPORTED > 1)
if (ntb_format > 1) { return false; }
#else
if (ntb_format > 0) { return false; }
#endif
NCM_State.ntb_format = ntb_format;
return true;
}
bool USBD_CDCn_NCM_SetNtbInputSize ( uint32_t  ntb_input_size)

Callback function called upon USB Host request to select the maximum size of NTB that is permitted to be sent to the USB Host.

Parameters
[in]ntb_input_sizeMaximum NTB size.
Returns
request handled status :
  • value true : request was handled
  • value false : request was not handled

The function USBD_CDCn_NCM_SetNtbInputSize is called when the USB Host requests to set the maximum size of NCM Transfer Block (NTBs) that USB Device can send to the USB Host.

The argument ntb_input_size is a pointer to the NTB input size.

Code Example

bool USBD_CDCn_NCM_SetNtbInputSize (uint32_t ntb_input_size) {
if (ntb_input_size > USBD_CDCn_NCM_DW_NTB_IN_MAX_SIZE) { return false; }
NCM_State.ntb_input_size = ntb_input_size;
return true;
}
void USBD_CDCn_NCM_Start ( void  )

Callback function called when USB Host changes data interface from alternate 0 to alternate 1 (activates data interface)

Returns
none.

The function USBD_CDCn_NCM_Start is called when the USB Host activates the data interface.

Code Example

void USBD_CDCn_NCM_Start (void) {
// Add code for data interface activation
osSignalSet(Connection_ThreadId, 1U);
osSignalSet(DataIN_ThreadId, 1U);
}
void USBD_CDCn_NCM_Stop ( void  )

Callback function called when USB Host changes data interface from alternate 1 to alternate 0 (de-activates data interface)

Returns
none.

The function USBD_CDCn_NCM_Stop is called when the USB Host de-activates the data interface.

Code Example

void USBD_CDCn_NCM_Stop (void) {
// Add code for data interface de-activation
// Explained in ncm10.pdf document from www.usb.org in paragraph 7.2
FrameIN_Size = 0U;
osSignalClear(DataIN_ThreadId, 1U);
memset(&NCM_State, 0, sizeof(NCM_State));
NCM_State.ntb_input_size = USBD_CDCn_NCM_DW_NTB_IN_MAX_SIZE;
NCM_State.max_datagram_size = USBD_CDCn_NCM_W_MAX_SEGMENT_SIZE;
#if ((USBD_CDCn_NCM_BM_NETWORK_CAPABILITIES & 0x02) != 0)
memcpy(&NCM_State.net_address, &MacAddress, 6);
#endif
NCM_State.packet_filter_bitmap = 0x0CU;
PacketFilter = ARM_ETH_MAC_ADDRESS_BROADCAST;
EthMac->SetMacAddress(&MacAddress);
EthMac->SetAddressFilter(NULL, 0);
EthMac->Control(ARM_ETH_MAC_CONFIGURE,
LinkInfo.speed << ARM_ETH_MAC_SPEED_Pos |
LinkInfo.duplex << ARM_ETH_MAC_DUPLEX_Pos |
PacketFilter);
}
void USBD_CDCn_NCM_Uninitialize ( void  )

Callback function called during USBD_Uninitialize to de-initialize the USB CDC class instance (NCM)

Returns
none.

The function USBD_CDCn_NCM_Uninitialize de-initializes/releases the hardware resources of the network device. It is called during USBD_Uninitialize. If USBD_CDCn_NCM_Initialize has been adapted to the application, USBD_CDCn_NCM_Uninitialize should release resources and should de-initialize peripherals.

Code Example

// Add code for de-initialization
osThreadTerminate(Connection_ThreadId);
osThreadTerminate(DataIN_ThreadId);
osThreadTerminate(DataOUT_ThreadId);
EthPhy->PowerControl(ARM_POWER_OFF);
EthPhy->Uninitialize();
EthMac->PowerControl(ARM_POWER_OFF);
EthMac->Uninitialize();
}