wlconf - Configuration utility for TI wireless drivers
======================================================

Author: Luciano Coelho <coelho@ti.com>

Copyright (C) 2012, Texas Instruments Inc.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
USA

EXAMPLES
--------

* Get the value of phy_standalone in the phy struct inside wl18xx from
  the binary configuration file wl18xx-conf.bin in the current
  directory:

  # ./wlconf -i wl18xx-conf.bin -g wl18xx.phy.phy_standalone
  wl18xx.phy.phy_standalone = 0x00

* Set the window_size value in the hangover struct inside core, using
  the binary at /lib/firmware/ti-connectivity/wl18xx-conf.bin as input
  and writing the modified file into wl18xx-conf.bin in the local
  directory (default output location):

  # ./wlconf -i /lib/firmware/ti-connectivity/wl18xx-conf.bin -s core.hangover.window_size=0x20

* Parse a text configuration file and generate a configuration binary
  with the values specified:

  # ./wlconf -C example.conf

* Parse an INI file and generate a configuration binary with the
  values specified.  The values that are not specified here are read
  from the input binary file (default wl18xx-conf-default.bin):

  # ./wlconf -I example.ini

TEXT CONFIGURATION FORMAT
-------------------------

The text configuration file uses internal data representations.  With
this kind of file, any element inside the configuration structure can
be modified.  The file should contain one or more lines with the
following syntax:

<element>[.<element>...] = <value>

Check the example.conf file for more details.

INI FILE FORMAT
---------------

The INI file uses the format as specified by TI to the customers.  The
format is not structured and contains simple element names:

<element> = <value>

Check the example.ini for a real life example.

DICTIONARY FILE FORMAT
----------------------

The INI file format uses flat element names that must to be translated
into the internal structured format.  The dictionary.txt file is used
to specify the INI elements and their respective internal
representations.  The dictionary file format is:

<ini_flat_element> <element>[.<element>...]

Check the dictionary.txt file for an example and to see which values
can be used in INI files.

UPGRADING DATA STRUCTURES
-------------------------
In case the data structures change (conf.h changes in driver) the following need to be done:

* Update conf.h accordingly. Increment Versions (WLCORE and/or WL18xx)

* If there are changes in INI params, need to update dictionary.txt

* Recreate struct.bin:

  # ./wlconf -S conf.h -G struct.bin

* Update text conf files to new structures and defaults:
	example.conf
	example.ini
	default.conf

* Recreate default configuration bin file (wl18xx-conf-default.bin)

  # ./wlconf -D

KNOWN ISSUES AND LIMITATIONS
----------------------------

* Only the first struct in an array of structs can be set;

* It's too cumbersome and prone to errors to let the end-users parse
  the source header file.  Thus, a default struct.bin file with the
  current driver configuration structure is provided.  This binary
  should be updated here whenever the conf header files change in the
  driver code.

* The source header parser is very limited.  It doesn't do a full
  pre-processing, but matches on regular expressions.  The format of
  the file must be very strict;

* The source header parser can't expand macros or enums.  These
  symbols need to be translated manually and changed in the header
  file;

* The source header parser can't include other files (ie. the #include
  statements are ignored), so it's best to copy the hw-specific header
  (eg. wl18xx/conf.h) into the core header file (ie. wlcore/conf.h)
  and substitute the priv[0] with the name of the top priv structure
  (eg. wl18xx_priv_conf);

* Trying to use --get to read the header.checksum value will always
  return 0;

* Trying to use --set to write the header.checksum value will not
  work, as the checksum will be recalculated with the new value
  (instead of 0) before writing, generating a conf binary with an
  invalid checksum.

TODO
----

* Allow setting values in any structure inside an array of structs;

* Improve type-checking in the --set command;

* Allow setting all values in an array with the --set command;

* Allow setting a value in a specific index of an array;

* Implement a man page;

* Split into separate source files;

* Implement "expert-mode" or something that doesn't make it so easy
  for end-users to mangle with the source header parsing and
  generation of struct binaries;

* Improve checking of options that are allowed with each different
  command;

* Fix some compiler warnings on x86 and make sure it works well;

* Add option to change the root structure;

* Handle endianess and different type sizes for different archs;

* Validate the checksum of the struct binary;

* Prevent any of the special elements (such as header.magic,
  header.version and header.checksum) from being read or set.

* Check if output file size matches input file size.  If it doesn't
  there's probably something wrong in the struct.bin generation
  (eg. array sizes that were not expanded);

* Add an option to change the dictionary file;
