io_net_registrant_funcs_t

Functions in your driver that io-net can call

Synopsis:

typedef struct _io_net_registrant_funcs {
    int nfuncs;
    int (*rx_up) (...);
    int (*rx_down) (...);
    int (*tx_done) (...);
    int (*shutdown1) (...);
    int (*shutdown2) (...);
    int (*dl_advert) (...);
    int (*devctl) (...);
    int (*flush) (...);
    int (*raw_open) (...);
    int (*raw_umount_ok) (...);
} io_net_registrant_funcs_t;

Description:

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 10. The functions are described below.

• rx_up()
• rx_down()
• tx_done()
• shutdown1()
• shutdown2()
• dl_advert()
• devctl()
• flush()
• raw_open()
• raw_umount_ok()

rx_up()

The io-net manager calls this function when your module is to receive an up-headed packet from a module below you. The prototype is:

int (*rx_up) (npkt_t *npkt,
              void *func_hdl,
              int off,
              int framlen_sub,
              uint16_t cell,
              uint16_t endpoint,
              uint16_t iface);

The arguments are:

npkt

A pointer to the packet.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

off

The number of bytes at the beginning of the packet that your driver's rx_up() should ignore.

framlen_sub

The number of bytes at the end of the packet that your driver's rx_up() should ignore.

cell, endpoint, and iface

Describe which module the packet is coming from.

This function should always return 0.

rx_down()

This function is called when your module receives a down-headed packet from a module above you. The prototype is:

int (*rx_down) (npkt_t *npkt,
                void *func_hdl);

The arguments are:

npkt

A pointer to the packet.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

The cell, endpoint, and iface members of the npkt structure describe the destination of the packet, and the buffers member contains the packet data.

The return value depends on the situation:

• For the layer that consumes a packet, rx_down() should return TX_DOWN_OK or TX_DOWN_FAILED.
• If the layer passes a packet to a lower layer, rx_down() should return whatever io-net's tx_down() function returned.
• A module that's registered as _REG_FILTER_BELOW may additionally return TX_DOWN_AGAIN, provided that it's supported by the upper layer. See the skip member of the npkt_t structure.

tx_done()

This function is called when a packet that you're responsible for has its reference count go to zero, effectively indicating that it has been consumed and may now be "recycled" (or disposed of). The prototype is:

int (*tx_done) (npkt_t *npkt,
                void *done_hdl,
                void *func_hdl);

The arguments are:

npkt

A pointer to the packet.

done_hdl

A pointer to extra data that your driver wants to pass to this function. It's specified when your driver calls io-net's reg_tx_done() or tx_up_start() function (see the description of io_net_self_t).

func_hdl

The handle you specified for your driver in io_net_registrant_t.

This function should always return 0.

shutdown1()

This is the first "shutdown" function that gets called when your driver is asked to shut down. The prototype is:

int (*shutdown1) (int registrant_hdl,
                  void *func_hdl);

The arguments are:

registrant_hdl

The registrant handle that was filled in when your driver registered by calling io-net's reg() function.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

This function can return:

• EOK to let the shutdown occur.

  Or:

• Some other indication (for example, EBUSY to indicate that there are active transmissions occurring) to prevent the driver from being shut down. It's up to the higher level to retry later. The implication here is that one can't force a shutdown of a driver that returns an error indication.

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.

shutdown2()

The prototype is:

int (*shutdown2) (int registrant_hdl,
                  void *func_hdl);

At this point, everything in your module is detached from all others, and you must shut down. This is the call that you'd use to kill off any of your worker threads, for example. Generally speaking, shutdown2() does most of the work associated with shutting down the driver.

When all of the shared object's registrants are closed, the "master" shutdown() function defined in io_net_dll_entry_t is called.

The arguments to shutdown2() are:

registrant_hdl

The registrant handle that was filled in when your driver registered by calling io-net's reg() function.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

This function should return 0.

dl_advert()

The prototype is:

int (*dl_advert) (int registrant_hdl,
                  void *func_hdl);

This function is used to advertise your driver's capabilities to other modules. You should call it from your driver's initialization function; Whenever a new higher-level module starts up, io-net calls dl_advert() so that the new module can made aware of the capabilities of all modules underneath it.

The arguments are:

registrant_hdl

The registrant handle that was filled in when your driver registered by calling io-net's reg() function.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

This function should return 0.

devctl()

The prototype is:

int (*devctl) (void *registrant_hdl,
               int dcmd,
               void *data,
               size_t size,
               int *ret);

This is the call-in to your driver to perform a devctl() function. This is invoked when someone does a devctl() on your driver's /dev/io-net/driver pathname. Currently, only the "nic info" devctl() is defined, which is used to fetch statistics from a driver. You don't have to support a devctl() handler.

The arguments are:

registrant_hdl

The registrant handle that was filled in when your driver registered by calling io-net's reg() function?

dcmd

The command being sent to your driver. For a nicinfo command, this is DMD_IO_NET_NICINFO.

data

A pointer to data to be passed to the driver, filled in by the driver, or both, depending on the command.

size

The maximum amount of data to be sent to the driver or filled in by the driver. If size is 0, an unspecified amount of data is transferred.

ret

A pointer to additional device data to be returned.

This function should return 0.

flush()

This function should flush any packets that the module may have queued pending transmission. The prototype is:

int (*flush) (int registrant_hdl,
              void *func_hdl);

The arguments are:

registrant_hdl

The registrant handle that was filled in when your driver registered by calling io-net's reg() function.

func_hdl

The handle you specified for your driver in io_net_registrant_t.

This function should call io-net's tx_done() function for each queued packet, and should return 0.

raw_open()

This function is looked at only for a _REG_FILTER_ABOVE module that wishes to provide additional I/O support for up-producer modules below it.

You can specify NULL for this function if you're writing a network driver.

The prototype is:

int (*raw_open) (resmgr_context_t *ctp,
                 io_open_t *msg,
                 io_net_iofunc_attr_t *attr,
                 void *extra);

This function should return EOK on success, or an error code on failure.

raw_umount_ok()

This function is looked at only for a _REG_FILTER_ABOVE module that provides additional I/O support for modules below it. If a umount request is made on a module below such a filter, this function is called to determine if the umount can proceed.

You can specify NULL for this function if you're writing a network driver.

The prototype is:

int (*raw_umount_ok) (io_net_iofunc_attr_t *attr);

This function should return EOK if the umount can proceed, or an error code.

Classification:

QNX

See also:

io_net_registrant_t, io_net_self_t, npkt_t