Instrumentation and Tuning
ddcutil has extensive facilities for reporting DDC protocol errors and peformance statistics, and some ability to tweak execution parameters from the command line.
I2C is an inherently unreliable protocol, requiring retry management. Furthermore, 90% of ddcutil's elapsed time is spent in timeouts mandated by the DDC specification.
The relevant options are:
| Option | Function |
|---|---|
| --stats | Report execution statistics |
| --ddc | Report DDC protocol errors |
| --maxtries() | Set maximum tries |
| --force-slave-address | Force control of I2C slave addresses |
| --force | Relax various internal checks |
| --nodetect | Skip display detection (valid only with --bus) |
| --async | Execute portion of monitor detection in parallel |
Option --ddc
If option --ddc is specified, ddcutil reports protocol errors that it detects. These may reflect I2C bus errors, or deviations by monitors from the MCCS specfication. Most I2C errors cause a retry. Some monitors are very clean. Others, like the Dell P2411h, are very dirty.
Option --stats
Option --stats causes ddcutil to report execution statistics. It takes the following optional arguments:
| --stats Argument | Action |
|---|---|
| errors | Report I2C/DDC error counts |
| tries | Report retry statistics |
| calls | Report system call counts and time |
| elapsed | Report elapsed time |
| time | Synonum for elapsed |
| all | Report all statistics |
If --stats all is specified, or no argument is given, then all statistics are output.
--stats calls implies --stats elapsed
Option --maxtries
There are 3 kinds of exchanges in which retry is possible:
- write-only exchange. Bytes are written with no subsequent read.
Used only to set a VCP feature value. - write-read exchange. A write to the monitor, followed by a read.
Most DDC protocol exchanges are of this form. - multi-part exchange. This is a "meta" exchange, consisting multiple write-read exchanges. Used to query monitor capabilities, and for querying and setting Table type VCP features.
By default, the maximum number of tries for each exchange is:
- write-only exchange: 4
- write-read exchange: 10
- multi-part exchange: 8
Option --maxtries allows you to play with the maximum try count. Its argument consists of 3 comma-separated values. The following example sets the maximum try counts to 3 for write-only exchanges, 6 for write-read exchanges, and 9 for multi-part exchanges.
--maxtries(3,6,9)
A blank value leaves the corresponding try count unchanged. The following example changes only the maximum write-read try count:
--maxtries(,7,)
The maximum maximum value is 15.
Option --force-slave-address
Per the DDC specification, ddcutil reads the EDID over an I2C bus using slave address x50, and performs DDC communication using slave address x37. Occasionally, communication cannot be established because these addresses are marked as busy. This option allows ddcutil to take control of those slave addresses, potentially impacting the other program. (Internally, ddcutil uses ioctl(I2C_SLAVE_FORCE) instead of ioctl(I2C_SLAVE).)
Option --nodetect
If a display is specified by its I2C bus number (option --bus) and option --nodetect is specified, global display detection is skipped, improving startup time.
Option --async
If there are multiple monitors and option --async is specified, initial monitor checks are performed in separate threads. improving startup time.
Option --force
A catchall option that allows ddcutil to continue execution despite various failure conditions. May be fatal. Subject to change.