IP Instances

The first decision you need to make when you use this API is whether to accommodate multiple instances of IP running in the kernel or to only interact with the global zone.

To be aware of the presence of IP instances, register callback functions that are activated when an instance is created, destroyed, and shut down. Use net_instance_alloc() to allocate a net_instance_t packet event structure to store these three function pointers. Use net_instance_free() to free resources when you no longer need the callbacks and the structure. Specify nin_name to give the structure instance a name. Specify at least the nin_create() and nin_destroy() callbacks. The nin_create() function is called when a new instance of IP is created, and the nin_destroy() function is called when an instance of IP is destroyed.

Specifying nin_shutdown() is optional unless the code will be exporting information to kstats. To use kstats on a per-instance basis, use net_kstat_create() during the create callback. Cleanup of the kstat information must happen during the shutdown callback, not the destroy callback. Use net_kstat_delete() to clean up kstat information.

extern void *mycreate(const netid_t);

net_instance_t *n;

n = net_instance_alloc(NETINFO_VERSION);
if (n != NULL) {
    n->nin_create = mycreate;
    n->nin_destroy = mydestroy;
    n->nin_name = "my module";
    if (net_instance_register(n) != 0)
        net_instance_free(n);
}

If one or more instances of IP are present when net_instance_alloc() is called, the create callback will be called for each currently active instance. The framework that supports the callbacks ensures that only one of the create, destroy, or shutdown functions is active at any one time for a given instance. The framework also ensures that once the create callback has been called, the shutdown callback will only be called after create has completed. Similarly, the destroy callback does not start until the shutdown callback is complete.

The mycreate() function in the following example is a simple example of a create callback. The mycreate() function records the network instance identifier in its own private context structure and registers a new callback to be called when a new protocol (such as IPv4 or IPv6) is registered with this framework.

If no zones are running (and therefore no instances other than the global zone), calling net_instance_register() runs the create callback for the global zone. You must supply the destroy callback so that net_instance_unregister() can be called later. Attempts to call net_instance_register() with either the nin_create or nin_destroy fields set to NULL will fail.

void *
mycreate(const netid_t id)
{
    mytype_t *ctx;

    ctx = kmem_alloc(sizeof(*ctx), KM_SLEEP);
    ctx->instance_id = id;
    net_instance_notify_register(id, mynewproto, ctx);
    return (ctx);
}

The function mynewproto() should expect to be called each time a network protocol is either added to or removed from a networking instance. If registered network protocols are already operating within the given instance, then the create callback will be called for each protocol that already exists.