wlconf - Configuration utility for TI wireless drivers ====================================================== Author: Luciano Coelho 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: [....] = 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: = 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: [....] 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;