ROM file parsing utilities

When writing a protocol that provides user-configurable ROM file options, you can make use of the ROM file parsing utilities to process the ROM file entries. To use these utilities:

1. Write separate routines to handle each ROM option your protocol will support. These routines should be of the following type:

    
   		typedef XkReturn (*ProtlRomOptFunc)(Protl protl, char **fields,
   int numFields,
   
   				int lineNumber, void *arg)
   
   

   The ROM file parsing code will call this handler routine when it finds an appropriate line in the ROM file. The number of fields on that line and the fields themselves will be placed in numFields and fields, respectively. The line number is provided to allow the handler to produce error messages if desired.

   If the handler returns XK_FAILURE, the parsing code will print a generic ``ROM file format error'' message, specifying the name of the protocol and the line number.

2. Create an array of ProtlRomOpt structures which bind option names to their handling functions. There is one ProtlRomOpt structure for each ROM option.

    
   		typedef struct {
   
   				char      		*name;     		/* name of the option as specified in ROM file */
   
   				int       		minFields; 		/* minimum number of fields for this option */
   
   				ProtlRomOptFunc 		func; 		/* handler function */
   
   		} ProtlRomOpt;
   
   

3. Somewhere in your protocol's initialization code, call findProtlRomOpts.

    
   		XkReturn findProtlRomOpts(Protl protocol, ProtlRomOpt *opts, int numOpts,
   void *arg)
   
   

   This routine scans through the ROM file, looking for lines where the first field matches either the protocol name or the full instance name of protocol (e.g., if the protocol instance is ethdrv/SE0, ROM file entries with either ethdrv/SE0 or ethdrv would match). When such a match is found, the array opts, of ProtlRomOpts, is scanned. If the second field of the line matches the name field of one of the opts entries, or if the name field of one of the opts entries is the empty string, the ProtlRomOptFunc for that option is called with the protocol, all ROM fields on that line, the number of fields on that line, the line number and the user-supplied argument.

   If the first field of a ROM line appears to match protocol, but none of the supplied opts entries matches the second field, an error message will be printed and XK_FAILURE will be returned. The rest of the ROM entries will not be scanned. This same behavior results from the ProtlRomOptFunc returning XK_FAILURE and from a ROM line with too few fields for its associated handler.

As an example, consider a protocol which supports two ROM options, a port option and an mtu option, both of which take single integer parameters. The example in Figure 5 shows how this protocol would interface with the romopt parsing utilities.

 
Figure 5: Interfacing with the romopt parsing utilities