dnx RTOS 2.2.0 "Eagle"
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
ETHMAC Driver

Detailed Description

Description

Driver handles Ethernet MAC peripheral. In general usage this driver is handled directly by protocol stack.

Supported architectures

Details

Meaning of major and minor numbers

The major number determines selection of Ethernet peripheral. Minor number has no meaning and should be set to 0.

Driver initialization

To initialize driver the following code can be used:

driver_init("ETHMAC", 0, 0, "/dev/eth0");

Driver release

To release driver the following code can be used:

driver_release("ETHMAC", 0, 0);

Driver configuration

Entire driver configuration is realized by using configuration files in the ./config directory or by using Configtool.

Data write

Data to driver can be written as for regular file but if buffer is bigger than MTU then buffer is send is few parts. In general case this method is not recommended to handle communication protocol. To handle driver more efficient please use ioctl() family requests.

Data read

Data from driver can be received as from regular file but with exception that read data buffer should be a size of ETH_MAX_PACKET_SIZE. In general case this method is not recommended to handle communication protocol. To handle driver more efficient please use ioctl() family requests.

Peripheral start

There are only two steps that should be done to start Ethernet peripheral:

After this operations packets will be received and transmitted.

Packet handling

To send and receive packets driver uses special data chains (ETHMAC_packet_chain_t). This object is a chain buffer that sum of all chain links payloads is a size of entire packet. Object can contain only single packet. In both cases, receiving and transmitting, the chain buffer should be created by user.

There is a big advantage of placing packets in to chain buffers – there is no need to allocate a single packet buffer, thus payload data can originate from e.g. different memories (RAM, ROM, etc). The chain buffer behave as simple one direction linked list.

Packet receiving

To receive packet one should wait for reception of Ethernet peripheral. To check this event the ioctl() request should be used: IOCTL_ETHMAC__WAIT_FOR_PACKET. User should specify the timeout value. If packet is received then ETHMAC_packet_wait_t object indicate a size of packet. This information should be used to create specified ETHMAC_packet_chain_t object. The object should be prepared by application that receive packet, example:

// initialization
// ...
FILE *eth = fopen(...);
// ...
// reception thread
while (true) {
// wait for packet to be received
ETHMAC_packet_wait_t wait = {.timeout = MAX_DELAY_MS, .pkt_size = 0};
if (ioctl(fileno(eth), IOCTL_ETHMAC__WAIT_FOR_PACKET, &wait) != 0) {
// ... error handling
}
// receive packet from peripheral buffer
bufch.next = NULL; // there is single chain
bufch.payload = malloc(wait.pkt_size); // allocate memory for packet
bufch.total_size = wait.pkt_size; // total size, packet size
bufch.payload_size = wait.pkt_size; // one chain has size the same as total size
// ... error handling
}
// ... received data handling
free(bufch.payload); // can be allocated only one time below the loop.
}

The input buffer can be created by using many chain links and the total chain size can be much bigger than received packet. The driver will fill the chain buffer by packet data and will set correct total size value. Only the first chain link has updated the total_size value.

Packet transmitting

To transmit packet the chain buffer should be used. The operation is opposite to packet receive but data sending is handled by the same chain buffer object type. The packet can be divided to many small parts. Packet sending example:

// initialization
// ...
FILE *eth = fopen(...);
// ...
// transmit thread
while (true) {
// ... data to send should be prepared earlier
// buffer prepare - buffer can be created dynamically
bufch.next = NULL; // there is single chain
bufch.payload = data_ptr; // pointer to data buffer
bufch.total_size = data_len; // total size - packet size
bufch.payload_size = data_len; // one chain has size the same as total size
// ... error handling
}
// ... packet transmitted
}

The best solution is to create specified packets dynamically at runtime. When data successively is added to chain buffer then new payload chains can be allocated and added to the buffer. The single chain will contain only small part of data. One should keep in mind that total_size field in first chain should be updated when new chain link is added, this field in other chain links is ignored by driver.

Data Structures

struct  ETHMAC_packet_chain_t
 
struct  ETHMAC_packet_wait_t
 

Macros

#define IOCTL_ETHMAC__WAIT_FOR_PACKET   _IOWR(ETHMAC, 0x00, ethmac_packet_wait_t*)
 Wait for receive of Rx packet. More...
 
#define IOCTL_ETHMAC__SET_MAC_ADDR   _IOW(ETHMAC, 0x01, u8_t*)
 Set MAC address. More...
 
#define IOCTL_ETHMAC__SEND_PACKET_FROM_CHAIN   _IOW(ETHMAC, 0x02, ethmac_packet_chain_t*)
 Send packet from chain buffer. More...
 
#define IOCTL_ETHMAC__RECEIVE_PACKET_TO_CHAIN   _IOR(ETHMAC, 0x03, ethmac_packet_chain_t*)
 Receive packet to chain buffer. More...
 
#define IOCTL_ETHMAC__ETHERNET_START   _IO(ETHMAC, 0x04)
 Starts Ethernet interface. More...
 
#define IOCTL_ETHMAC__ETHERNET_STOP   _IO(ETHMAC, 0x05)
 Stop Ethernet interface. More...
 
#define IOCTL_ETHMAC__GET_LINK_STATUS   _IOR(ETHMAC, 0x06, ETHMAC_link_status_t*)
 Return link status. More...
 

Enumerations

enum  ETHMAC_link_status_t
 

Data Structure Documentation

struct ETHMAC_packet_chain_t

Type represent packet chain.

Data Fields
struct ETHMAC_packet_chain * next

Next chain of payload.

void * payload

Payload.

u16_t payload_size

Payload size.

u16_t total_size

Total size.

struct ETHMAC_packet_wait_t

Type represent packet waiting with selected timeout.

Data Fields
size_t pkt_size

Size of received packet. Value is set by driver at response.

uint32_t timeout

Timeout value in milliseconds. Value is set by user at request.

Macro Definition Documentation

#define IOCTL_ETHMAC__ETHERNET_START   _IO(ETHMAC, 0x04)
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__ETHERNET_STOP   _IO(ETHMAC, 0x05)
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__GET_LINK_STATUS   _IOR(ETHMAC, 0x06, ETHMAC_link_status_t*)
Parameters
[RD]ETHMAC_link_status_t* link status.
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__RECEIVE_PACKET_TO_CHAIN   _IOR(ETHMAC, 0x03, ethmac_packet_chain_t*)
Parameters
[RD]ETHMAC_packet_chain_t* chain buffer reference (each chain must have allocated memory!).
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__SEND_PACKET_FROM_CHAIN   _IOW(ETHMAC, 0x02, ethmac_packet_chain_t*)
Parameters
[WR]ETHMAC_packet_chain_t* chain buffer reference.
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__SET_MAC_ADDR   _IOW(ETHMAC, 0x01, u8_t*)
Parameters
[WR]u8_t[6]: pointer to buffer of 6 elements.
Returns
On success 0 is returned, otherwise -1 and errno code is set.
#define IOCTL_ETHMAC__WAIT_FOR_PACKET   _IOWR(ETHMAC, 0x00, ethmac_packet_wait_t*)
Parameters
[WR,RD]ETHMAC_packet_wait_t* timeout value and received size.
Returns
On success 0 is returned, otherwise -1 and errno code is set.

Enumeration Type Documentation

Type represent link status.

Enumerator
ETHMAC_LINK_STATUS__CONNECTED 

Link connected.

ETHMAC_LINK_STATUS__DISCONNECTED 

Link disconnected.