NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO
#include <ddi/net/ether/etherProp.h>
#include <ddi/net/ether/ether.h>
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
DDI
Provides ethernet driver interface services. There are two versions of this interface, version 1 and the INITIAL version. Version 1 is an adaptation of the INITIAL version and enables ethernet drivers to use a new DMA model for managing the memory allocated for network buffers. Drivers are able to use the so named "one copy" model where only one copy of the data is made, throughout the handling of the frames. This new DDI is also able to take advantage of the hardware checksum feature of some adapters. In the following driver service routines section, the routines that are available in the new version 1 DDI are indicated with a (+v1) next to the routine name.
#define ETHER_PROP_ADDR "ether-addr" #define ETHER_PROP_THROUGHPUT "link-throughput" #define ETHER_PROP_NOT_SIMPLEX "not-simplex" #define ETHER_PROP_MTU "mtu" #define ETHER_PROP_CHECKSUM "checksum" typedef uint8_f EtherPropAddr[6]; typedef enum { ETHER_10_MBS = 10000000, /* 10 Megabits link */ ETHER_100_MBS = 100000000 /* 100 Megabits link */ } EtherPropThroughput;
The value associated with the ETHER_PROP_ADDR property is an array of 6 bytes which contains the Ethernet Address of the device. The ETHER_PROP_ADDR property is mandatory for the client of the device. By default, its value is set by the device driver with the Ethernet address probed from the device's ROM.
The value associated with the ETHER_PROP_THROUGHPUT property is a 32-bit unsigned integer which specifies the throughput of the underlying Ethernet Link in bits per second. It must be set to 10000000 on a 10 Megabits link and to 100000000 on a 100 Megabits link. The ETHER_PROP_THROUGHPUT property is mandatory for the client of the device. By default, its value is set by the device driver which probes it from the device.
The value associated with the ETHER_PROP_NOT_SIMPLEX property is boolean (the property is present or not) and is interpreted by the client to provide the result of the driver configuration. If this property is added by the driver, the duplexing mode is FULL_DUPLEX. If the property is not added by the driver, the duplexing mode is HALF_DUPLEX (or SIMPLEX). The interpretation made by the driver of the existence or value of this property is specific to each driver, and if such an interpretation exists, it will be documented in the corresponding driver man page (9DRV).
The value associated with ETHER_PROP_MTU is used to inform the client of the 'Maximum Transmit Unit' configured. The interpretation made by the driver of the existence or value of this property is specific to each driver, and if such an interpretation exists, it will be documented in the corresponding driver man page (9DRV).
The ETHER_PROP_CHECKSUM property, if present, activates the hardware checksum calculation capability of the adapter, if it is available. This property is also used by the client of the driver (C_OS) to be informed on whether the checksum is already calculated, so that any extra processing can be avoided. No value is associated with this property.
The Ethernet device driver service routines are declared by the EtherDevOps structure shown below. A pointer to the EtherDevOps structure is exported by the driver via the svDeviceRegister microkernel call. A driver client invokes the svDeviceLookup and svDeviceEntry microkernel calls in order to obtain a pointer to the device service routines vector.
#define ETHER_CLASS "ethernet" typedef enum { ETHER_VERSION_INITIAL = 0, } EtherVersion; typedef struct { EtherVersion version; KnError (*open) (void* devId, void* client_cookie, EtherCallBack* clientOps); void (*close) (void* device_id); KnError (*frameTransmit) (void* device_id, NetFrame* outFrame); KnError (*frameReceive) (void* device_id, NetFrame* rcvFrame); void (*promiscuousEnable) (void* device_id); void (*promiscuousDisable) (void* device_id); void (*setMcastAddr) (void* device_id, uint32_f nb, EtherMcast* mcastAddrs); KnError (*dmaSetup) (void* device_id, PhAddr physAddr, void* mbufStart, size_t mbufSize); } EtherDevOps; typedef struct EtherMcast { struct EtherMcast *next; char mcastAddr[6]; } EtherMcast;
open
Arguments
The identifier assigned to the device by the device driver
The identifier assigned to the device by the Ethernet client
A pointer to an EtherCallBack structure which contains the set of functions exported by the Ethernet client of the device
Synopsis:
The open function is only invoked by the Ethernet client of the device to start communication over the underlying Ethernet device designated by the first argument device_id . The device driver must record in the structure it associates to the device the client_cookie and the clientOps arguments to make further upcalls to the Ethernet client. The client_cookie is the first argument of every function exported by the Ethernet client to the device driver.
The device driver must start the Ethernet device in the following default receive mode:
Receipt of unicast and broadcast frames (no multicast)
Promiscuous disabled
Invocation Context:
The open function is always invoked at base level. The Ethernet client ensures the same device is not opened again before having closed it.
Return Value:
If successful
Otherwise
close
device_id is the identifier assigned to the device by the device driver.
The close function tells the Ethernet driver that the device is no longer used by the Ethernet client. The close function must stop the Ethernet device cleanly. In particular, it must arrange to terminate all DMA-based I/O operations, if any, and to disable all device interrupts. The close function is responsible for ensuring that all the functions exported by the Ethernet client will no longer be invoked after it returns to the client. In addition, close must only return after all output frames which are currently transmitted have been freed.
Invocation Context:
The close function is only invoked once after a successful invocation of open for the same device. The close function is always invoked at base level. The close function is invoked in mutual exclusion with all other functions exported by the device driver on the same device. The Ethernet client guarantees that all the other functions exported by the device driver will never be invoked again (on the same device) after it invoked close .
frameTransmit
device_id is the identifier assigned to the device by the device driver. outFrame is the network frame to transmit.
Synopsis:
The frameTransmit function of the device driver is invoked by the Ethernet client to transmit an output frame. If the Ethernet device has enough transmission resources to start the transmit operation, frameTransmit returns immediately without waiting for the frame transmission to be completed. In this case, the device driver is responsible for freeing the output frame by invoking the freeFrame function embedded within the NetFrame structure associated to the output frame.
Invocation Context:
The frameTransmit function is guaranteed not to be re-entered. The frameTransmit function can be invoked at interrupt level.
Return Value:
If the transmit operation has been started successfully
Otherwise
frameReceive
Argument(s):
Is the identifier assigned to the device by the device driver.
Is a pointer to a structure of type NetFrame into which frameReceive must return:
The total size of the received frame in the frameSize field
List of network memory buffers which contain the received frame data in the bufList field
Synopsis:
The frameReceive function of the device driver is invoked by the Ethernet client of the device to retrieve the next input frame received by the device, if any.
If an input frame is available, frameReceive must invoke the netBufAlloc function exported by the Ethernet client to allocate a list of network memory buffers to which to copy the frame's content. Then, frameReceive returns this list of buffers and the total size of the frame into the NetFrame structure pointed to by its rcvFrame output argument.
In the presence of an erroneous input frame, frameReceive must notify the I/O error through an upcall to the ioErrorNotify function exported by the Ethernet client and skip the erroneous frame.
Invocation Context:
The frameReceive function is only invoked once the device driver has notified the Ethernet client through an upcall to receiptNotify . The frameReceive function can be invoked at interrupt level. The frameReceive function is guaranteed not to be re-entered.
Return Value:
If successful.
If no input frame is available.
If the allocation of network memory buffers failed.
promiscuousEnable
Argument(s):
device_id is the identifier assigned to the device by the device driver.
Synopsis:
The promiscuousEnable function starts the receipt of all Ethernet frames which are carried over the Ethernet link.
Invocation Context:
The Ethernet client ensures that promiscuousEnable is invoked in mutual exclusion with the promiscuousDisable function described below. The promiscuousEnable function is not re-entered. The promiscuousEnable function is always invoked at base level.
promiscuousDisable
Argument(s):
device_id is the identifier assigned to the device by the device driver.
Synopsis:
The promiscuousDisable function puts the Ethernet device in the default receipt mode.
Invocation Context:
The Ethernet client ensures that promiscuousDisable is invoked in mutual exclusion with the promiscuousEnable function described above. The promiscuousDisable function is not re-entered. The promiscuousDisable function is always invoked at base level.
setMcastAddr
Argument(s):
Is the identifier assigned to the device by the device driver.
Is the number of multicast addresses given in the list.
Points to the item's 6-byte multicast ethernet address.
Synopsis:
The setMcastAddr function is invoked to reset the Ethernet Multicast Address (which is invoked by the device's controller).
The controller does not maintain the current or previous state. Each time setMcastAddr is called, the state is reset. It is the responsability of the upper layers to keep track of the multicast addresses, as well as additions/deletions.
All addresses are guaranteed to be unique multicast addresses.
This function can invoke three reset states for the multicast address, depening on the value of the nb argument.
The controller state is reset to no-multicast mode.
The controller filters the given multicast addresses. If there are too many for it to handle, the controller switches automatically to the "all-multicast" mode. In this mode, no addresses are filtered, and therefore upper layers must handle filtering functions.
controller switches to "all-multicast" mode.
Invocation Context:
The setMcastAddr function is not re-entered, and is always invoked at base level.
dmaSetup
Argument(s):
Is the identifier assigned to the device by the device driver.
Is the physical address of the buffer area.
Is a pointer to the beginning of the buffer area where the client will allocate its packet buffers.
Is the length of the buffer area.
Synopsis:
The dmaSetup() function of the device driver is invoked by the Ethernet client of the device to optionally configure the device for DMA operation.
The client allocates its input and output frames in the memory area described by mbufStart and mbufSize. The device driver will attempt to access that memory area in the device address space (in general PCI) so that the controller can directly use the buffers.
The dmaSetup() function is not re-entered and called only once after the open only. It is always invoked at base level.
Return Value:
If successful.
In any other case.
The set of functions exported by the Ethernet client is represented by the EtherCallBack structure. A pointer to a structure of type EtherCallBack is provided to the Ethernet driver by the Ethernet client as an argument of the open function.
typedef enum { ETHER_TX_CARRIER_ERROR, ETHER_TX_HEARTBEAT_ERROR, ETHER_TX_COLLISION_ERROR, ETHER_RX_TOOLONG_ERROR, ETHER_RX_CRC_ERROR, ETHER_RX_FIFO_ERROR, } EtherIoError; typedef enum { ETHER_LINK_UP, ETHER_LINK_DOWN, } EtherLinkState; typedef struct { void (*transmitNotify) (void* client_cookie); void (*receiptNotify) (void* client_cookie); NetBuf* (*netBufAlloc) (void* client_cookie, uint32_f frameSize); void (*netBufFree) (void* client_cookie, NetBuf* bufList); void (*ioErrorNotify) (void* client_cookie, EtherIoError ioError); void (*linkStateNotify) (void* client_cookie, EtherLinkState linkState); } EtherCallBack;
transmitNotify
Argument(s):
Is the identifier assigned to the device by the Ethernet client.
Synopsis:
The transmitNotify function must be invoked by the device driver to inform the Ethernet client that transmission resources of the Ethernet device are available. If pending output frames need to be transmitted, the Ethernet client will invoke the frameTransmit function of the device driver, either in sequence or asynchronously.
Invocation Context:
The transmitNotify function can be invoked at interrupt level, which is usually the case. The device driver is allowed to invoke transmitNotify at any moment and multiple times, even if no output frame needs to be transmitted.
receiptNotify
Argument(s):
Is the identifier assigned to the device by the Ethernet client.
Synopsis:
The receiptNotify function must be invoked by the device driver to inform the Ethernet client that new input frames have been received by the Ethernet device. As a result, the Ethernet client will invoke the frameReceive function of the device driver, either in sequence or asynchronously.
Invocation Context:
The receiptNotify function can be invoked at interrupt level, which is usually the case. The device driver is allowed to invoke receiptNotify at any moment and multiple times, even if no (valid) input frame has been received.
netBufAlloc
Argument(s):
Is the identifier assigned to the device by the Ethernet client
Is the requested memory size
Synopsis:
The netBufAlloc function must be invoked by the frameReceive function of the device driver to allocate a list of network memory buffers into which it copies the contents of the next received frame. This list of memory buffers is returned to the Ethernet client into the second argument of the frameReceive function.
Invocation Context:
The netBufAlloc function can only by invoked by the frameReceive function of the device driver.
Return Value:
A list of NetBuf structures which fit the requested size
NULL
netBufFree
Argument(s):
Is the identifier assigned to the device by the Ethernet client
Is the list of network memory buffers to free
Synopsis:
The netBufFree function must be invoked by the frameReceive function of the device driver to free network memory buffers which it previously allocated through an upcall to the netBufAlloc function. This usually occurs when frameReceive detects an error while copying the contents of the next input frame from the device into the memory buffers.
Invocation Context:
The netBufFree function can only by invoked by the frameReceive function of the device driver.
ioErrorNotify
Argument(s):
Is the identifier assigned to the device by the device driver
Specifies the I/O error detected by the device controller
Synopsis:
The ioErrorNotify function is invoked by the device driver to notify the Ethernet client of an I/O related error detected by the Ethernet device controller. The ioErrorNotify function is mainly used for recording statistics.
Invocation Context:
This function can be invoked at interrupt level.
linkStateNotify
Argument(s):
Is the identifier assigned to the device by the device driver
Specifies the new state of the Ethernet link detected by the Ethernet device controller
Synopsis:
The linkStateNotify function provides to the Ethernet client the new state of the Ethernet link detected by the Ethernet device controller.
Invocation Context:
This function can be invoked at interrupt level.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO