cyg_lwip_eth_ioctl()

Name

cyg_lwip_eth_ioctl() -- Control interface

Synopsis

#include <cyg/io/eth/eth_drv.h>

int cyg_lwip_eth_ioctl(struct netif *netif, unsigned long key, void *data, intdata_length);

Description

This function is used to perform low-level “control” operations on the specified lwIP network interface. It provides an interface to the hardware where the function cannot be performed totally by the platform-independent layers.

The key parameter selects the operation, and the data and data_length parameters describe, as required, some data for the specified operation.

Available Operations:

ETH_DRV_SET_MAC_ADDRESS

This operation sets the ethernet station address (ESA or MAC) for the specified network interface. Normally this address would be kept in non-volatile memory and is unique in the world. This function must at minimum set the hardware interface to use the supplied address, but (if required) it may also update the non-volatile memory as appropriate.

ETH_DRV_SET_MC_LIST

Configure the driver with the given list of multicast filters so that only received packets with a matching filter are accepted and passed onto the lwIP stack.

The common ethernet support currently defines a fixed size vector for holding the “list” of multicast filter addresses:

#define ETH_DRV_MAX_MC 8
struct eth_drv_mc_list {
  int len;
  unsigned char addrs[ETH_DRV_MAX_MC][ETHER_ADDR_LEN];
};
       

For the lwIP ethernet driver support the passed list may have unused entries (marked by the first byte having the multicast flag bit 0 clear). This is an optimisation, and still allows for users to pass a front-filled len count of used entries, or for the driver to avoid having to copy-down data when list entries are removed by marking individual passed list entries as unused.

For simple, lightweight, drivers it is common for the list support to simply perform the equivalent of the ETH_DRV_SET_MC_ALL option, where the lwIP stack filters unwanted multicast packets instead of the driver having pre-filtered based on the specified list.

ETH_DRV_SET_MC_ALL

Configure the driver to accept all multicast packets.

ETH_DRV_GET_IF_STATS, ETH_DRV_GET_IF_STATS_UD

These options acquire a set of statistical counters from the interface, and write the information into the memory referenced by data. The calls to these options are typically made by SNMP agents. The “UD” variant explicitly instructs the driver to acquire up-to-date values. This is a separate option because doing so may take some time, depending on the hardware.

The definition of the data structure can be found in the header file cyg/io/eth/eth_drv_stats.h.

Return value

Successful completion of the operation is indicated by a result of 0 being returned. If a specific key operation is not supported by the driver, or there is an error processing the requested operation then a result of 1 is returned to indicate failure.

2017-02-09
Documentation license for this page: Open Publication License