User API

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

USBD_CDC_NCM_NTB_IN_Initialize()

int32_t USBD_CDC_NCM_NTB_IN_Initialize

(

uint8_t

instance

)

Clear the active NTB (prepared for sending)

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_IN_CreateNDP()

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]	instance	Instance of CDC class.
[in]	num_datagrams	Maximum 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

USBD_CDC_NCM_NTB_IN_WriteDatagram()

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]	instance	Instance of CDC class.
[in]	buf	Buffer containing data bytes to write.
[in]	len	Number 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

USBD_CDC_NCM_NTB_IN_Send()

int32_t USBD_CDC_NCM_NTB_IN_Send

(

uint8_t

instance

)

Send the active NTB.

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_IN_IsSent()

int32_t USBD_CDC_NCM_NTB_IN_IsSent

(

uint8_t

instance

)

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

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_IsReceived()

int32_t USBD_CDC_NCM_NTB_OUT_IsReceived

(

uint8_t

instance

)

Check if NTB was received and is available for processing.

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_Release()

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]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_ProcessNDP()

int32_t USBD_CDC_NCM_NTB_OUT_ProcessNDP

(

uint8_t

instance

)

Process the next NDP in the received NTB.

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_GetDatagramSize()

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]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_ReadDatagram()

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]	instance	Instance of CDC class.
[out]	buf	Buffer that receives read data.
[in]	max_len	Maximum 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

USBD_CDC_NCM_NTB_IN_RawSend()

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]	instance	Instance of CDC class.
[in]	buf	Buffer containing NTB.
[in]	len	Size 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

USBD_CDC_NCM_NTB_OUT_RawGetSize()

uint32_t USBD_CDC_NCM_NTB_OUT_RawGetSize

(

uint8_t

instance

)

Get size of the received NTB.

Parameters

[in]

instance

Instance 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

USBD_CDC_NCM_NTB_OUT_RawReceive()

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]	instance	Instance of CDC class.
[out]	buf	Buffer that receives NTB.
[in]	max_len	Maximum 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

USBD_CDC_NCM_Notify_NetworkConnection()

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]	instance	Instance of CDC class.
[in]	status	Connection 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

USBD_CDC_NCM_Notify_ConnectionSpeedChange()

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]	instance	Instance of CDC class.
[in]	us_bitrate	Upstream bitrate.
[in]	ds_bitrate	Downstream 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

USBD_CDCn_NCM_Initialize()

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

void USBD_CDCn_NCM_Initialize (void) {
  // 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);
}

USBD_CDCn_NCM_Uninitialize()

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

void USBD_CDCn_NCM_Uninitialize (void) {
  // 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();
}

USBD_CDCn_NCM_Reset()

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.

USBD_CDCn_NCM_Start()

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);
}

USBD_CDCn_NCM_Stop()

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);
}

USBD_CDCn_NCM_SetEthernetMulticastFilters()

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_list	Pointer to list of 48-bit Multicast addresses.
[in]	num_of_filters	Number 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
}

USBD_CDCn_NCM_SetEthernetPowerManagementPatternFilter()

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_number	Filter number.
[in]	pattern_filter	Power management pattern filter structure.
[in]	pattern_filter_size	Size 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
}

USBD_CDCn_NCM_GetEthernetPowerManagementPatternFilter()

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_number	Filter number.
[out]	pattern_active	Pointer 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
}

USBD_CDCn_NCM_SetEthernetPacketFilter()

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_bitmap

Packet 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
}

USBD_CDCn_NCM_GetEthernetStatistic()

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_selector	Feature Selector.
[out]	data	Pointer 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
}

USBD_CDCn_NCM_GetNtbParameters()

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_params

Pointer 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;
}

USBD_CDCn_NCM_GetNetAddress()

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_addr

Pointer 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
}

USBD_CDCn_NCM_SetNetAddress()

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_addr

Pointer 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
}

USBD_CDCn_NCM_GetNtbFormat()

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_format

Pointer 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;
}

USBD_CDCn_NCM_SetNtbFormat()

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_format

NTB 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;
}

USBD_CDCn_NCM_GetNtbInputSize()

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_size

Pointer 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;
}

USBD_CDCn_NCM_SetNtbInputSize()

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_size

Maximum 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;
}

USBD_CDCn_NCM_GetMaxDatagramSize()

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_size

Pointer 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
}

USBD_CDCn_NCM_SetMaxDatagramSize()

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_size

Maximum 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
}

USBD_CDCn_NCM_GetCrcMode()

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_mode

Pointer 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
}

USBD_CDCn_NCM_SetCrcMode()

bool USBD_CDCn_NCM_SetCrcMode

(

uint16_t

crc_mode

)

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

Parameters

[in]

crc_mode

CRC 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
}

USBD_CDCn_NCM_NTB_IN_Sent()

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

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

USBD_CDCn_NCM_NTB_OUT_Received()

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

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