nic_parse_options()

Parse an option string for a network driver

Synopsis:

int nic_parse_options ( nic_config_t *cfg,
                        char *option );

Arguments:

cfg

A pointer to the members of the nic_config_t structure that the option string updates.

Based on the contents of the option string, this function updates various members of the nic_config_t structure, which the cfg argument points to. The various options that are recognized by this function affect the structure as follows:

ioport

The specified value is stored in the next free element (the element indexed by the num_io_windows field) of the io_window_base array. The num_io_windows field is incremented.

irq

The specified value is stored in the next free element (the element indexed by the num_irqs field) of the irq array. The num_irqs field is incremented.

dma

The specified value is stored in the next free element (the element indexed by the num_dma_channels field) of the dma_channel array. The num_dma_channels field is incremented.

vid

The specified value is stored in the vendor_id field.

did

The specified value is stored in the device_id field.

pci

The specified value is stored in the device_index field.

mac

The specified string is converted to an array of bytes, and stored in the current_address array.

lan

The specified value is stored in the lan field.

mtu

The specified value is stored in the mtu field.

mru

The specified value is stored in the mru field.

speed

The specified value is stored in the media_rate field.

duplex

The specified value is stored in the duplex field.

media

The specified value is stored in the media field.

promiscuous

This option doesn't need an argument. If specified, the NIC_FLAG_PROMISCUOUS flag is set in the flags field.

nomulticast

This option doesn't need an argument. If specified, the NIC_FLAG_MULTICAST flag is cleared in the flags field.

connector

The specified value is stored in the connector field.

deviceindex

The specified value is stored in the device_index field.

phy

The specified value is stored in the phy_addr field.

memrange

The specified value is stored in the next free element (i.e. the element indexed by the num_mem_windows field) of the mem_window_base array, and the num_mem_windows field is incremented. If a window size was specified in addition to a base (the base value was followed by a colon, followed by the length value), the element of the mem_window_size array at the corresponding array index is updated.

iorange

The specified value is stored in the next free element (i.e. the element indexed by the num_io_windows field) of the io_window_base array, and the num_io_windows field is incremented. If a window size was specified in addition to a base (the base value was followed by a colon, followed by the length value), the element of the io_window_size array at the corresponding array index is updated.

verbose

If specified without an argument, the verbose field is incremented. If specified with an argument, the verbose field is set to the specified value.

iftype

The specified value is stored in the ifype field.

uptype

The specified string value is copied into the uptype array.

priority

The specified value is stored in the priority field.

---

The driver typically initializes the fields of the nic_config_t structure with default values, before it parses the options. This allows the user to override the default values via driver options. In some cases, the driver should initialize a field with an invalid value. For example, if the driver sets the speed and duplex values to -1, it will be able to tell, after the options have been parsed, whether the user attempted to explicitly set the speed and/or duplex to specific values. Then the driver can determine whether to force the link configuration, or to allow link autonegotiation/autodetection to take place. The driver should set NIC_FLAG_MULTICAST in the flags field before parsing the options. If the nomulticast option is specified, this flag is subsequently cleared.

---

option

The options to parse.

Description:

The nic_parse_options() function assists in parsing a driver network string. This function parses standardized options. Drivers can parse their driver-specific option strings with the getsubopt() function. Standardized options have a well-defined behavior that's consistent across all network drivers.

If getsubopt() doesn't recognize an option as being driver-specific, the option should then be passed to the nic_parse_option() function. It will try to interpret the option; if it can't, the nic_config_t structure will be updated appropriately.

If the driver uses the nic_parse_options() function for option parsing, the nic_config_t structure stores the results.

---

The getsubopt() function modifies the option string that's passed to it, by changing commas to spaces. You should have the driver make a copy of the option string before using getsubopt() to parse it.

---

Examples:

Here's an example of how the fictitious "toad" driver, which has two driver-specific options, would parse its options. In the example, the toad_device_t structure is a driver-specific structure the driver uses to store its internal state.

#include  <sys/slog.h>    
#include  <sys/slogcodes.h>
#include  <string.h> 
#include  <stdlib.h>
#include  <errno.h>
#include  <drvr/nicsupport.h>
int
toad_parse_options(toad_device_t *toad,
    const char *optstring, nic_config_t *cfg)
{
    char        *value;
    int     opt;
    char        *options, *freeptr;
    char        *c;
    int     err = EOK;

       static char *toad_opts[] = {
               "receive",
               "transmit",
               NULL
       };
       enum {
               TOADOPT_RECEIVE = 0,
               TOADOPT_TRANSMIT
       };

       if (optstring == NULL)
           return 0;

       /* getsubopt() is destructive */
       freeptr = options = strdup(optstring);

       while (options && *options != '\0') {
           c = options;
           if ((opt = getsubopt( & options, toad_opts, & value)) == -1) {
               if (nic_parse_options(cfg, value) == EOK)
                   continue;
               nic_slogf(_SLOGC_NETWORK, _SLOG_WARNING,
                  "devn-toad: unknown option %s", c);
              err = EINVAL;
              break;
          }

          switch (opt) {
              case TOADOPT_RECEIVE:
                  if (toad != NULL)
                      toad->num_rx_descriptors =
                          strtoul(value, 0, 0);
                  continue;
              case TOADOPT_TRANSMIT:
                  if (toad != NULL)
                      toad->num_tx_descriptors =
                          strtoul(value, 0, 0);
                  continue;
              default:
                  /* Impossible */
          }
      }

      free(freeptr);
       errno = err;

       return (err == EOK) ? 0 : -1;
   }

Classification:

QNX Neutrino

See also:

nic_config_t