![[Previous]](prev.gif) |
![[Contents]](contents.gif) |
![[Index]](keyword_index.gif) |
![[Next]](next.gif) |
|
|
|
|
 |
This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs. |
Functions in your driver that io-net can call
typedef struct _io_net_registrant_funcs {
int nfuncs;
int (*rx_down) (...);
int (*tx_done) (...);
int (*shutdown1) (...);
int (*shutdown2) (...);
int (*dl_advert) (...);
int (*devctl) (...);
int (*flush) (...);
} io_net_registrant_funcs_t;
The io_net_registrant_funcs_t structure is a table of functions that your driver wants to register with io-net. The funcs member of the io_net_registrant_t structure is a pointer to an instance of this structure.
The nfuncs member specifies the number of function pointers in the structure. For the structure as given above, this is 8. The functions are described below.
This function is called when your module receives a down-headed packet from a module above you. The driver must traverse the buffers and their associated data fragments, and send the data to the hardware to be transmitted. Depending on the nature of the NIC device, the driver may do one of the following:
If the driver passes pointers, then the hardware will typically be programmed with the physical addresses of the data fragments, which are stored in the net_iov_t structure.
If the driver copies the data, it can then call the tx_done() function to return the buffer to the sender, since it's finished with the buffer. However, if the hardware has DMA capability, there may be a long time delay from when the packet is submitted to the NIC device until the NIC copies the data from the buffers. For performance reasons, the driver wouldn't want to wait around until the packet has been copied. Instead, it would store a pointer to the packet, perhaps by maintaining a linked-list of packets that are pending transmission, and return from the entry point. At a later time (e.g. the next time the transmit entry point is called, or perhaps when a hardware interrupt or timer triggers an event) the packet can be returned to the sender by calling tx_done(). The prototype is:
int (*rx_down) (npkt_t *npkt,
void *func_hdl);
The arguments are:
This function is called when the upper layers have finished processing packets that originated from the driver, effectively indicating that they have been consumed and may now be "recycled" (or disposed of). A previous call to tx_up_start() results in this function being called. The prototype is:
int (*tx_done) (npkt_t *npkt,
void *done_hdl,
void *func_hdl);
This entry point should not be confused with the tx_done callback in the io_net_self_t structure. This function will be called when the upper layers have finished processing packets that originated from the driver. This function will be called as a result of a previous call to tx_up_start(). In this entry point, the driver can either free the packets, and their associated buffer(s), or it can reuse them. The arguments are:
The shutdown entry points are called when the interface is no longer needed. They are called when either when the user unmounts the interface, or when the io-net process is terminating. Since the process of removing an interface from the networking subsystem is a delicate operation, the shutdown of an interface is done in two stages. After shutdown1() is called, the driver should no longer send packets upstream. However, it should still be prepared to have outstanding packets that were previously sent upstream be returned. It should also allow any pending transmits to complete, and return the buffers to the sender when they do (by calling the tx_done callback). The prototype is:
int (*shutdown1) (int registrant_hdl,
void *func_hdl);
The arguments are:
This function can return:
or:
Your driver is still connected to the other modules when shutdown1() is called. It's your last chance to transmit data either up or down, which must be done using the thread that called shutdown1() because of io-net's locking mechanism.
The prototype is:
int (*shutdown2) (int registrant_hdl,
void *func_hdl);
When shutdown2() is called, the driver should throw away any pending transmits, and return them by calling the tx_done callback. The driver should then de-activate the NIC device, and free up any resources that were allocated by the driver, during and since the instantiation of the interface.
The arguments to shutdown2() are:
The prototype is:
int (*dl_advert) (int registrant_hdl,
void *func_hdl);
After a driver registers an interface with io-net it sends a message packet upstream in order to advertise its capabilities. However, sometimes the networking subsystem requires that the driver resend the advertisement message upstream. In this case, this entry point will be called. The driver should create a message packet as per "Advertising device capabilities" in the Writing a Network Driver chapter and send it upstream.
The arguments are:
The prototype is:
int (*devctl) (void *func_hdl,
int dcmd,
void *data,
size_t size,
union _io_net_dcmd_ret_cred *ret);
This entry point is called when a devctl() (device control) message is sent to be processed by the driver.
The arguments are:
This function should return ENOTSUP if the driver receives a devctl() it doesn't recognise. It should return EOK if the devctl() was processed correctly; otherwise, an appropriate error code should be returned. See <errno.h> for details.
This function is called to flush out any packets that are pending for transmission on the medium. This is needed for drivers that return from their packet transmission entry point without immediately returning the packet to the originator without having called the tx_done callback. When this function returns, the driver should call the tx_done callback to make sure all outstanding packets have been returned. The prototype is:
int (*flush) (int registrant_hdl,
void *func_hdl);
The arguments are:
This function should call io-net's tx_done() function for each queued packet, and should return 0.
QNX Neutrino
io_net_registrant_t, io_net_self_t, npkt_t
|
|
|
|