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 --busno)
--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 --busno) 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.