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

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