This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

io_net_self_t

Functions in io-net that your driver can call

Synopsis:

typedef struct _io_net_self {
    int    *(reg);
    int    *(dereg) (...);
    void    (*alloc) (...);
    npkt_t *(alloc_up_npkt) (...);
    int     (*free) (...);
    paddr_t (*mphys) (...);
    npkt_t  (*tx_up_start) (...);
    int     (*tx_done) (...);
    int     (*devctl) (...);
} io_net_self_t;

The driver should always use the function table to call these functions. In addition, the driver should use a pointer to the function table that was passed to its primary entry point rather than copying the table or caching individual function pointers. The function pointers can change during the interface's lifetime.

The io_net_self_t structure points to functions that allow your driver to call back into the networking framework.

The functions are described below.

reg()
dereg()
alloc()
alloc_up_npkt()
free()
mphys()
tx_up_start()
tx_done()
devctl()

reg()

This function registers an interface with io-net. It should be called once for each NIC interface that the driver wishes to instantiate.

This function must be called before any of the other functions in the io_net_self_t structure.

The prototype is:

int (*reg) (void *dll_hdl,
            io_net_registrant_t *registrant,
            int *reg_hdlp,
            uint16_t *cell,
            uint16_t *endpoint)

The arguments are:

dll_hdl: The driver should specify the value that was passed into the primary driver entry point.
registrant: A pointer to an io_net_registrant_t structure that describes how the interface should be instantiated. It also contains a pointer to a table of additional driver entry points.
reg_hdlp: On success, a value is stored at the location that this points to, which should be used as the registrant_hdl parameter to subsequent calls into io_net.
cell: The driver should specify a pointer to a 16-bit variable. A value is stored at this location for later use when the driver delivers received packets to the upper layers.
endpoint: This is the interface number (LAN number) The driver should specify a pointer to a 16-bit variable. A value is stored at this location for later use when the driver delivers received packets to the upper layers. Typically io-net decides how the LAN number is chosen, but it's possible for the driver to influence how the LAN number is chosen. For details, see the io_net_registrant_t() entry.

This function returns:

0: Success.
-1: An error occurred; errno is set.

dereg()

The prototype is:

int (*dereg) (int registrant_hdl)

Deregister an interface from io-net. Typically, this function is called only if the driver encounters an error after registering with io-net and wishes to undo the registration.

The registrant_hdl argument is the registrant handle that was filled in via the reg_hdlp parameter when your driver registered by calling the reg() callback.

This function returns EOK on success, or an error code.

alloc()

The prototype is:

void *(*alloc) (size_t size,
                int flags)

This function allocates a buffer of the given size that's safe to pass to any other module. It's typically used to allocate buffers to store data that's received from the medium.

The size parameter specifies the amount of memory, in bytes, that's to be allocated.

There are currently no flags defined.

This function returns a pointer to the allocated memory, or NULL if an error occurred.

alloc_up_npkt()

The prototype is:

npkt_t *(*alloc_up_npkt) (size_t size,
                          void **data)

Allocates an npkt_t structure suitable to deliver packet data upstream. This function allocates only the structures that describe the packet data, and not the packet data itself.

The arguments are:

size: Specifies additional data that should be allocated in addition to the npkt_t() structure.
data: Points to an address where a pointer to the additional data that was allocated, will be stored.

The additional allocated data can be used to hold buffer descriptor (net_buf_t()) structures, and iov_t() structures, that point to the packet data. Note that the memory for the npkt_t() structure and the additional data will be allocated as a contiguous block of memory, and should be freed with a single call (as opposed to being freed piecemeal.)

This function returns a pointer to the allocated structure, or NULL if an error occurred.

free()

The prototype is:

int (*free) (void *ptr)

This function frees a buffer, pointed to by ptr, that was allocated by the alloc() or alloc_up_npkt() callbacks.

This function returns:

0: Success.
-1: An error occurred; errno is set.

mphys()

The prototype is:

paddr_t (*mphys) (void *ptr)

This function does a quick lookup of the physical address of the memory, pointed to by ptr, that was allocated by either alloc(), or alloc_up_npkt().

This function returns the physical address of the buffer on success, or -1 if an error occurred (errno is set).

tx_up_start()

The prototype is:

npkt_t *(*tx_up_start) (int registrant_hdl,
                        nptk_t *npkt,
                        int off,
                        int framelen_sub,
                        uint16_t cell,
                        uint16_t endpoint,
                        uint16_t iface,
                        void *tx_done_hdl)

A function used to send data packet and advertisement messages upstream. This function can be called from the driver's receive event-handler. Note that the thread that calls this function could re-enter the driver through one of its entry points. Be careful not to hold locks when calling this function; one of the driver's entry points could attempt to reacquire them. Note that for all packets sent upstream, the data must be contained in a single fragment.

The arguments are:

registrant_hdl: The registrant handle that was filled in when your driver registered by calling io-net's reg() callback.
npkt: A pointer to a linked list of packets to be sent upstream.
off: Zero should be specified.
framelen_sub: Zero should be specified.
cell: Specify the cell value supplied to you by io-net when you registered.
endpoint: Specify the endpoint value supplied to you by io-net when you registered.
iface: Zero should be specified.
tx_done_hdl: When the packets that were sent upstream have been processed by the upper layers, a driver entry point is called to return the packet to the driver. The driver can then either release or reuse the npkt_t() structures and their associated buffers. The driver entry point is passed an additional argument, so that the driver can access its internal state structures. This parameter specifies the value that's passed to the driver entry point.

This function returns NULL upon success. If this is non-NULL, errno is set, and a linked list of npkt structures for which a tx_done() callback couldn't be registered (i.e. for which reg_tx_done() failed) is returned. The driver should immediately release (or reuse) any packets that are returned in this way.

tx_done()

The prototype is:

int (*tx_done) (int registrant_hdl,
                 npkt_t *npkt)

Notifies the packet's originator that the packet is ready for release or reuse. When the packet data has been copied or transmitted, the driver's transmit routine calls this function. This function should also be called if your driver decides to discard the packet rather than attempt to transmit it.

The registrant_hdl argument is the registrant handle that was filled in when your driver registered by calling io-net's reg() callback. The npkt argument points to a linked list of packets that the driver has finished processing.

This function returns:

0: Success.
-1: An error occurred; errno is set.

devctl()

The prototype is:

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

Send a devctl() (device control) command to io-net.

The arguments are:

registrant_hdl

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

dcmd

The command being sent to your driver. Only one value for dcmd is currently supported:

DCMD_IO_NET_CHANGE_MCAST -- for multicast support. If the driver loses track of which multicast addresses to accept packets from, it can send this devctl so that io-net can resend the list of enabled multicast addresses to the driver.

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. (currently unused)

This function returns EOK on success, or an error code.

Classification:

QNX Neutrino

io_net_self_t

Synopsis:

Description:

reg()

dereg()

alloc()

alloc_up_npkt()

free()

mphys()

tx_up_start()

tx_done()

devctl()

Classification:

See also: