Notes for Upcoming ddcutil Release 2.2.0 (Draft)

Note: Reflecting the extensive changes, the next ddcutil release will be numbered 2.2.0, not 2.1.5.

For ddcui changes, see ddcui Release Notes

2.2.0

05 Dec 2024

Release 2.2.0 contains some major enhancements, particularly for display change detection, numerous small changes, and a large number of bug fixes.

DisplayLink devices, using the evince driver, are supported.

Raspberry Pi

  • Fix display not found and DDC communication failure on Raspberry Pi. Do not rely on sysfs attributes that do not exist for ARM devices. Resolves github issues 403, 413.
  • Miscellaneous changes to allow for building on raspbian.

User Defined Features

  • Add feature type XNC (Extended Non-Continous). This is like simple NC, but the SH byte is also reported. Provides a solution to the primary problem raised in github issue 403. Note that this feature type was created for use in user defined feature definitions; there are no features of this type defined in the Monitor Control Command Set specification.
  • Allow SNC (Simple Non-Continuous) as alternative name for NC.
  • Report user defined features as part of parsed capabilities.
  • Commands recognizing user defined features now fail if there's an error loading a user defined feature file. These are capabilities, setvcp, dumpvcp, and probe.
  • Fix error msg when nothing follows VALUE in user defined feature file.
  • When processing a user defined feature file, recognize any whitespace character (e.g. tab), not just space.

Command detect

  • Only show details about DDC communication errors if option --verbose is in effect.
  • Provide a clearer message if slave address x37 is inactive:
    • "Monitor does not support DDC" instead of generic "DDC_commnication failed"
    • If option --verbose is in effect, emit an additional message to check the monitor's OSD.
  • Report the Monitor Model Id in the --verbose output.

Command setvcp

  • Do not report "Interpretation may not be accurate." when the VCP version cannot be determined. This message is irrelevant for setvcp, which does not interpret feature values. Partially addresses github issue 454.

Commands interrogate and environment --verbose

  • Force settings --disable-cross-instance-locking, --disable-dynamic-sleep.
  • Forced settings apply to environment --verbose as well as interrogate
  • When probing DRM, recognize bus types DRM_BUS_PLATFORM, DRM_BUS_HOST1X, report as "platform", "host1x".
  • Simple getvcp test was not reporting the bytes of the response packet.
  • If no device with class x03 was found, the user's home directory was dumped. Addresses github issue 413.
  • Remove "-i" option on get-edid command. Does not exist on some versions.

Udev rules

  • /usr/lib/udev/rules.d/60-ddcutil-i2c-rules:
  • Also give logged on user r/w access to /dev/dri/cardN, needed to allow logged on user to probe connectors using DRM.
  • Do not install /usr/lib/udev/rules.d/60-ddcutil-usb.rules, delete it if previously installed. Addresses github issues 405, 428, 437.

Parser changes

  • Add alternative option names for symmetry with other options:
    • --discard-capabilities-cache is an alias for --discard-cache capabilities
    • --discard-sleep-cache is an alias for --discard cache dsa
    • --discard-dsa-cache is an alias for --discard cache dsa
  • Eliminate --enable-dsa-cache as alias for --enable-dynamic-sleep-cache.
  • Improve handling of --verify/--noverify, error if both specified
  • Add --enable-flock and --disable-flock as aliases for --enable-cross-instance-locks and --disable-cross-instance-locks.

Minor Bug Fixes and Changes

  • Configuration file ddcutilrc: If there is a pound sign "#" on a line, the remainder of the line is treated as a comment.
  • If option --bus is specified, only check accessability for that bus, avoiding irrelevant warning messages regarding other buses. Addresses github issue 461.
  • Add command noop, which allows for executing options such as --settings without having to execute a real command.
  • Change the system log message level when sleep time is adjusted from WARNING to VERBOSE. Addresses github issue 427: Adjusting multiplier message fills system log when libddcutil used by clightd.
  • When processing environment variable user $XDG_DATA_DIRS, or $XDG_CONFIG_DIRS, the final directory in the list was ignored. See github issue 438.
  • Fix core dump on ddcutil getvcp. Fixes github issue 407.
  • Convert CRLF line endings in source to LF.
  • Rework laptop detection. A non-laptop display can have an eDP connector. This is an i915 video driver bug that will not be fixed. See freedesktop.org issue [DRM connector for external monitor has name card1-eDP-1] (https://gitlab.freedesktop.org/drm/i915/kernel/-/issues/10389)

Building ddcutil

  • As an aid to development, the build date and time are normally embedded in the ddcutil and libddcutil executables. This is reported using command ddcutil --version --verbose". libddcutil reports this to the system log. If reproducible builds are required, use configure option --disable-build-timestamp**.
  • configure options --enable-x11/--disable-x11 are restored. The default is --enable-x11. The X11 API continues to be used to test for DPMS sleep mode.
  • Changes for portability:
  • Use printf() formats %jd and %zd to portably print variables of type ssize_t, and time_t, so as to build unchanged on architectures such as armel, armhf.
  • Avoid compiler warning possible depending on compiler configuration when a switch() construct is used. Replaced with if/else if/else. Resolves issue #458.
  • Compile using option -Wformat-security. Issue 458.

Shared Library

Shared library libddcutil is backwardly compatible with the one in ddcutil 2.1.0. The SONAME is unchanged as libddcutil.so.5. The released library file is libddcutil.so.5.2.0.

Display Change Reporting

Detection of display connection and disconnection has been extensively reworked.

  • Detecting and reporting sleep mode has proven very problematic. libddcutil no longer watches for and reports changes to DPMS state. However, if an API function is called to perform an operation that requires communiation with a display that is asleep, status DDCRC_DPMS_ASLEEP is returned.
  • ddca_start_watch_displays() has been modifed accordingly in a backwards compatible way.
    • The only event class that can be enabled is DDCA_EVENT_CLASS_DISPLAY_DETECTION. . - DDCA_EVENT_CLASS_ALL is effectively the same as DDCA_EVENT_CLASS_DISPLAY_CONNECTION.
    • It is an error if either DDCA_EVENT_CLASS_DPMS or DDCA_EVENT_CLASS_NONE are specified.
  • Performance is improved using UDEV and /sys to watch for changes and to get the EDID if possible.

  • Connection of Multi-Stream Transport (MST) hub devices is detected if the driver/device combination supports it. Not all drivers do.

  • Display change detection is unreliable with the nvidia proprietary driver.

    • The nvidia driver does not use /sys in the same way as amdgpu, i915, nouveau and other drm enabled drivers that are part of the Linux kernel.
    • Depending on driver version the phase of the moon, the /sys file system does not reflect display changes and UDEV events are not generated. In that case no display changes are reported.
    • There is an alternate, much less efficient algorithm that does not rely on UDEV and /sys that can be used for nvidia. It instead attempts to read an EDID from every (plausible) /dev/i2c device in a polling loop. Users with all but the most powerful machines will likely find it much too resource consumptive. It is enabled by option --watch-mode poll.
  • The following named options affect display change detection.
    • ---watch-mode udev|poll. the default is UDEV.
    • --enable/disable-try-get-edid-from-sysfs (default --enable-try-get-edid-from-sysfs) This may or may not improve performance at the expense of reliability.
  • Some monitors behave in ways that make KDE PowerDevil unstable. See, for example, ddcutil github issue 466, github issue 470 and KDE bug 495746. Specific monitor models can be excluded from display change detection using option --disable-ddc, which takes a Monitor Model Id, e.g. SAM-U32H75x-3587, as an argument. The monitor model id can be found in the output of command ddcutil detect --verbose, and is the same monitor model id that is used in the name of a user defined features file.
    -- Typically, this option will be added to the [libddcutil] section of configuration file ddcutilrc. It can also be included in the options string passed in the opts argument to ddca_init2().
  • Display change detection can be completely disabled using libddcutil only option --disable-watch-displays. This blocks ddca_start_watch_displays() from starting the thread that watches for display changes. Workaround for issue 470. Unlike the use of KDE Plasma environment variable POWERDEVIL_NO_DDCUTIL=1, this disables display change detection while leaving other libddcutil services available.

  • In addition to the named option, several utility options currently affect display change detection. Some of these will become named options when ddcutil version 2.2.0 is released, others will be removed once testing is finished.

    • --f17 do not use sysfs connector_id (default is to use it)
    • --f18 always report UDEV events
    • --f20 do not try to avoid rechecking DDC responsiveness when a display is reconnected (default is to remember prior checks)
    • --f21 always treat sysfs as unreliable for reporting display changes
    • --f22 never treat sysfs as unreliable for reporting display changes
    • --i6 watch loop sleep multiplier (multiply default watch loop settings)
    • --i7 extra stabilization milliseconds after apparent disconnection
    • --i8 explicit udev poll loop milliseconds (takes precedence over --i6)
    • --i9 explicit non-udev poll loop milllisec (takes precedence over --i6)
    • As the requirements become clearer, it is expected that the API will add functionality currently specified only as libddcutil options.

Other Shared Library Changes

Quiesce operation:
- Quiesce the API during ddca_redetect_displays(). Operations that access display state are not permitted, and return DDCRC_QUIESCED.

Status codes:
- Most functions that specify a DDCA_Display_Ref now return status code DDCRC_DISCONNECTED if the display reference is no longer valid.
- Status code DDCRC_INVALID_CONFIG_FILE has been renamed to more general DDCRC_CONFIG_ERROR, and is used instead of DDCRC_BAD_DATA for User Defined Feature File errors. DDCRC_INVALID_CONFIG_FILE is a valid alias.

System log:
- Write build date and time to system log when starting libddcutil.
- Rework libdccutil output to avoid duplicate msgs in the system log when all terminal output is directed to the log, as with KDE Plasma.
- Include thread id in messages written to syslog.

Miscellaneous:
- Use mutexes to control access to corruptable data structures, such as the table of open monitors. - Recover instead of abort when more than one non-removed display refs exist for the same display.
- Enum value DDCA_STATS_API is added to enum DDCA_Stats_Type, for reporting API specific stats.
- ddca_start_watch_displays(): Fixed segfault that occured with driver nvidia when checking if all video adapters implement drm. github issue 390.
- During initial display reference validation, an otherwise valid display reference may be for a removed display. Avoid a segfault in this case. Addresses github issue 418.
- Ignore phantom displays when searching for a display reference. Addresses github issue 412.
- ddca_get_display_refs() and ddca_get_display_info_list2() always return 0, even if an error occured when examining a particular monitor. Addresses github issue 417
- Errors that occur opening individual displays or reading their EDIDs are are still reported using ddca_get_error_detail(). In addition, error messages are written to the terminal and, depending on the current syslog level, to the system log.
- It is useful to create a string representation of a display reference even if it is no longer valid. Addresses github ddcui issue 55.