How to make a driver configurable
How to add a new configuration option
Steps:
- Define the new option
- Add the option to the common option pool (optional)
- Add the new option to common/xmlpool/t_options.h
- Update common/xmlpool/options.h
- Add the new option to
__driConfigOptions - Query the option in a convenient place
1. Define the new option
Configuration options are described to the driver and external configuration tools in XML. A set of macros in src/mesa/drivers/dri/common/xmlpool.h helps building such descriptions.
An option description always starts with DRI_CONF_OPT_BEGIN or DRI_CONF_OPT_BEGIN_V depending on whether you intend to limit the valid range of option values. These macros have 3 or 4 parameters respecitively: name, type, default value and optionally valid range.
An option description ends with DRI_CONF_OPT_END. Inbetween you can place verbal descriptions of your options in any number of languages. In the simplest case a description looks like this: DRI_CONF_DESC(lang,"text").
Note: Descriptions must be UTF-8 encoded.
If you are describing enum type options then you start a description with DRI_CONF_DESC_BEGIN(lang,"text") and end it with DRI_CONF_DESC_END. Inbetween you can place descriptions of different values of the enum option like DRI_CONF_ENUM(value,"text").
For enum options it is recommended that you also define macros to give option values symbolic names to be used in the driver.
2. Add the option to the common option pool (optional)
It is recommended that new options that are likely to be used by more than one driver are added to the common pool of configuration options. This makes maintainance easier and increases the chances of the option description being translated to more languages.
2.1. Add the new option to common/xmlpool/t_options.h
Common options are defined in common/xmlpool/t_options.h. This file is not directly used by drivers, it is only a template containing macros with option definitions and their English descriptions. There is a Python script that generates common/xmlpool/options.h by filling in all available translations.
You add an option by defining a macro that expands to the entire option description as outlined in the previous section. In order to get your option description translated to other languages, translatable strings must be wrapped in gettext(...). You may choose to make the default value a parameter of this macro so that the driver can choose an appropriate default value. For some options it may also make sense to make the valid range of values a parameter.
2.2. Update common/xmlpool/options.h
Option definitions in t_options.h are not directly available to drivers. You need to update common/xmlpool/options.h. This is done automatically by running make in common/xmlpool. The actual work is done by a Python script, so you need Python installed on your system.
Now the option will have only an English description. It's the translators job to update the translations. If your native language is not English then you may want to add a translation for your native language yourself. See Section How to translate option descriptions below for details.
Finally you should commit the new common/xmlpool/t_options.h and common/xmlpool/options.h to CVS.
3. Add the new option to __driConfigOptions
In order to inform the driver and external configuration tools about the new option it has to be added to the XML document that advertises the driver's configuration options. It is stored in the global variable __driConfigOptions which is usually found in driverscreen.c or driverxmesa.c.
If you added the option to the common pool of options then you just use the macro defined there. Otherwise you fill in the entire option description here. Related options are grouped in sections in __driConfigOptions. Either choose an appropriate section or add a new one if the new options doesn't fit in an existing one.
Finally, don't forget to increment the value of __driNConfigOptions after adding a new option. If you do, the driver will output an error message that reminds you.
4. Query the option in a convenient place
Now you can query the option value. This must happen after driParseOptionInfo and driParseConfigFiles have been called. This means that you can't query an option before context creation. There are three functions driQueryOption[bif] for querying options for boolean, integer and floating point options respectively. Enum options are queried like integer options.
The query functions take two arguments, a pointer to the option cache in the driver's context record and the name of the option to be queried as a string. If you need the option value very frequently then it is best to query the option once during context creation and store its value in the driver's context record.
If you try to query an option that is not available or has a different type then an assertion fails. Therefore common code that is linked to different drivers should first check if an option is really available. This is done with driCheckOption. It takes three arguments, a pointer to the option cache, the option name and the type. It returns a boolean indicating if an option with matching name and type is available.
How to translate option descriptions
Option descriptions in the common option pool in common/xmlpool are managed by GNU gettext. This should make it easy to manage translations even for translators without programming experience. There is one .po-file for each language for which there is a translation. If there is a translation for your language and you just want to update it for new or changed options or fix a typo somewhere, you can skip the next section and continue with Updating existing translations. Otherwise read on here.
Adding new translations
The Makefile common/xmlpool/Makefile is used to manage translations of option descriptions. Near the start of the file, below a longish comment with instructions, there is a variable definition looking like this:
POS=de.po
... and hopefully many more languages soon. Add a new .po-file for your language here. For example, if you want to make a french translation, add fr.po:
POS=de.po fr.po
Updating existing translations
Run make po in common/xmlpool. This will update existing .po-files from common/xmlpool/t_options.h or initialize new ones for added languages. Now you can edit the .po-file for your language, fixing fuzzy translations or translating new options. I'm assuming that you're familiar with GNU gettext and the .po-file syntax.
When you're done, save the file and run make in common/xmlpool. This will update common/xmlpool/options.h with new translations. Finally you can recompile the DRI drivers. After that they will contain option descriptions with your updated translations. When you run DriConf in the right locale you should see your updated option descriptions.
If you have CVS write access, you can commit your updated .po-file and common/xmlpool/options.h to CVS. Otherwise send the .po-file to dri-devel@lists.sourceforge.net and someone will take care of updating it in CVS.