Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

IONetworkDeviceMethods

Adopted By:	IOEthernet
IOTokenRing

Declared In:	driverkit/IONetwork.h

Protocol Description

This protocol must be implemented by network direct device drivers that use IONetwork to tie into the kernel network system. These methods are invoked by IONetwork objects in response to events in the network system.

Note:  Network drivers must run at kernel level.

Method Types

Creating netbufs	- allocateNetbuf

Initializing the hardware	- finishInitialization

Sending out a packet	- outputPacket:address:

Performing control commands	- performCommand:data:

Instance Methods

allocateNetbuf

- (netbuf_t)allocateNetbuf

This method creates and returns a netbuf to be used for an impending output.

This method doesn't always have to return a buffer. For example, you might want to limit the number of buffers your driver instance can allocate (say, 200 kilobytes worth) so that it won't use too much wired-down kernel memory. When this method fails to return a buffer, it should return NULL.

Here's an example of implementing allocateNetbuf.

#define my_HDR_SIZE    14
#define my_MTU        1500
#define my_MAX_PACKET  (my_HDR_SIZE + my_MTU)

- netbuf_t allocateNetbuf
{
    if (_numbufs == _maxNumbufs)
        return(NULL);
    else {
        _numbufs++;
        return(nb_alloc(my_MAX_PACKET));
    }
}

See also:  nb_alloc() (NEXTSTEP Operating System Software)

finishInitialization

- (int)finishInitialization

This method should perform any initialization that hasn't already been done. For example, it should make sure its hardware is ready to run. You can specify what the integer return value (if any) should be. 

If you implement this method, you need to check that [self isRunning] == YES.

outputPacket:address:

- (int)outputPacket:(netbuf_t)packet address:(void *)address

This method should deliver the specified packet to the given address. Its return value should be zero if no error occurred; otherwise, return an error number from the header file sys/errno.h.

If you implement this method, you need to check that [self isRunning] == YES. If so, insert the necessary hardware addresses into the packet and check it for minimum length requirements.

performCommand:data:

- (int)performCommand:(const char *)command data:(void *)data

This method performs arbitrary control operations; the character string command is used to select between these operations. Although you don't have to implement any operations, there are five standard operations. You can also define your own operations. 

The standard commands are listed in the following table. The constant strings listed below are declared in the header file net/netif.h (under the bsd directory of /NextDeveloper/Headers).

Command	Operation

IFCONTROL_SETFLAGS	Request to have interface flags turned on or off. The data argument for this command is of type union ifr_ifru (which is declared in the header file net/if.h).

IFCONTROL_SETADDR	Set the address of the interface.

IFCONTROL_GETADDR	Get the address of the interface.

IFCONTROL_AUTOADDR	Automatically set the address of the interface.

IFCONTROL_UNIXIOCTL	Perform a UNIX ioctl() command. This is only for compatibility; ioctl() isn't a recommended interface for network drivers. The argument is of type if_ioctl_t *, where the if_ioctl_t structure contains the UNIX ioctl request (for example, SIOCSIFADDR) in the ioctl_command field and the ioctl data in the ioctl_data field.

An example of implementing performCommand:data: follows.

- (int)performCommand:(const char *)command data:(void *)data
{
    int error = 0;

    if (strcmp(command, IFCONTROL_SETFLAGS) == 0)
        /* do nothing */;
    else
    if (strcmp(command, IFCONTROL_GETADDR) == 0)
        bcopy(&my_address, data, sizeof (my_address));
    else
        error = EINVAL;
    
    return (error);
}