Instrumentation and Tuning

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.

ddcutil has extensive facilities for reporting protocol errors, retry counts, and peformance statistics, and some ability to tweak execution parameters from the command line.

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

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
all Report all statistics

If --stats all is specified, or no argument is given, then all statistics are output.

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 onsists 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 --force

A catchall option that allows ddcutil to continue execution despite various failure conditions. May be fatal. Subject to change.