Shared Library Changes for the Next Release (Draft)
Overview
The shared library libddcutil is not backwardly compatible. The SONAME is now libddcutil.so.5. The released library file is libddcutil.so.5.0.0. In conformance with Debian practice, the package name is libddcutil5.
To support programs that that use the old shared library, libddcutil.so.4 will continue to be published as package libddcutil4.
Because necessary changes required incrementing the major version of the shared library, it provided an opportunity to remove a large number of functions that were deprecated, made unnecessary by the ability to pass command line options to libddcutil, or otherwise cluttered the API and ABI. In practice, most existing programs will require minimal changes to rebuild with the new version of the shared library. However, best practice is to use initialization function ddca_init(). It is required in order to read options from the configuration file,
Library Initialization
Library initialization has been reworked extensively to move operations that can fail, along with various settings that should be under control of the library user, into a new function ddca_init().
This function:
- controls the level of messages written to the system log
- optionally processes options obtained from the ddcutil configuration file
- processes additional options passed as a string
- sets error information for ddca_get_error_detail()
If this function is not called by the user program, any API function that relies on its having executed invokes ddca_init() using arguments such that it never fails, e.g. the configuration file is not processed.
Execution Options
These new options apply only to libddcutil, not to ddcutil. They can be specified in configuration file $HOME/.config/ddcutil/ddcutilrc, or in the libopts string passed to ddca_init().
- Option --trcapi
: Trace the specified API function and its called functions. - Option --profile-api: Collect performance statistics for API functions that perform display IO, and report them when the shared library is terminated.
API changes
| New typedefs | Comments |
|---|---|
| DDCA_Init_Options | enum of ddca_init() options |
| DDCA_Syslog_Level | enum of ddcutil severity levels for msgs written to the system log |
| DDCA_HotplugFunc | signature of callback function reporting a display hotplug event |
| New Functions | Comments |
|---|---|
| ddca_init | Perform library initialization |
| ddca_libddcutil_filename | Returns the fully qualified name of the shared library |
| ddca_syslog_level_from_name | Given its symbolic name, return a DDCA_Syslog_Level value |
| ddca_register_display_hotplug_callback | Registers a function of type DDCA_Display_Hotplug_Func which will be called to inform the client of display hotplug events. |
| ddca_unregister_display_hotplug_callback | Unregister a callback |
| Changed Functions | Comments |
|---|---|
| ddca_set_sleep_multiplier | Operates on the display, if any, open in the current thread |
| ddca_get_sleep_multiplier | Returns the value for the display, if any, open in the current thread |
| ddca_get_display_list | Returns status code, sets error detail |
| ddca_report_display_info | Returns DDCA_Status instead of void |
| ddca_show_stats | Optionally report per-display stats, not per-thread stats |
| ddca_get_feature_name() | Implementation had been removed but the function remained in the API. This change restores the implementation. |
| ddca-dfr_check_by_dref() | Do not return an error if no user defined feature file exists |
With the ability to configure libddcutil operation both by the ddcutil configuration file and by passing an option string in the ddca_init() arguments, many API functions are no longer needed and have been removed. These are unlikely to have been used by any existing clients other than ddcui.
| Removed Max-Tries Functions | Equivalent Option |
|---|---|
| ddca_max_max_tries | No option equivalent |
| ddca_get_max_tries | No option equivalent |
| ddca_set_max_tries | Use option --maxtries |
| Removed Sleep-Multiplier Functions | Comments |
|---|---|
| ddca_set_default_sleep_multiplier | Use option --sleep-multiplier |
| ddca_get_default_sleep_multiplier | No option equivalent |
| ddca_set_global_sleep_multiplier | Previously deprecated |
| ddca_get_global_sleep_multiplier | Previously deprecated |
| Removed USB Enablement Functions | Comments |
|---|---|
| ddca_enable_usb_display_detection | Use options --enable-usb / --disable-usb |
| ddca_is_usb_display_detection_enabled | No option equivalent |
| Miscellaneous Removed Functions | Comments |
|---|---|
| ddca_enable_report_ddc_errors | Use option --ddc |
| ddca_is_report_ddca_errors_enabled | No option equivalent |
| ddca_enable_error_info | Use option --excp |
| ddca_enable_force_slave_address | Use option --force-slave-address |
| ddca_is_force_slave_address_enabled | No option equivalent |
| Removed Tracing Typedefs | Comments |
|---|---|
| DDCA_Trace_Options | used by ddca_set-trace_options() |
| Removed Tracing Functions | Comments |
|---|---|
| ddca_add_traced_function | Use option --trcfunc |
| ddca_add_traced_file | Use option --trcfile |
| ddca_set_trace_groups | Use option --trace |
| ddca_add_trace_groups | Use option --trace |
| ddca_trace_group_name_to_value | Not needed |
| ddca_set_trace_options | Use options --thread-id --timestamp, --wall-timestamp |
Most per-thread statistics are now instead maintained on a per-display basis. The following functions are no longer useful and have been removed:
| Removed Per-Thread Functions | Comments |
|---|---|
| ddca_set_thread_description | No longer useful |
| ddca_append_thread_description | No longer useful |
| ddca_get_thread_desription | No longer useful |
Remove previously deprecated functions:
| Removed Function | Comments |
|---|---|
| ddca_get_feature_name_by_dref | Had been replaced by ddca_get_feature_metadata_by_dref |
| ddca_get_formatted_vcp_value | Did not support user defined features |
| ddca_open_display | Had been replaced by ddca_open_display2 |
| ddca_create_display_ref | Use ddca_get_display_ref |
| ddca_free_display_ref | Not needed. Display references are managed by the shared library. |
Remove vestiages of the old AMD proprietary driver. Regarding enum changes, while the constant numbers assigned to the remaining values values are unchanged, switch statements without a default case will fail to compile.
| Changed | Comments |
|---|---|
| enum DDCA_Build_Option_Flags | Eliminated value DDCA_BUILT_WITH_ADL |
| struct DDCA_Adlno | Eliminated |
| enum DDCA_IO_Mode | Eliminated value DDCA_IO_ADL |
| struct DDCA_IO_PATH | Removed variable adlno from path union |
Miscellaneous
Symbols for functions and enums that had previously been removed from ddcutil_c_api.h are no longer exported. In addition, many internal symbols had "leaked". These are no longer exported.