1# libdisplay-info 2 3EDID and DisplayID library. 4 5Goals: 6 7- Provide a set of high-level, easy-to-use, opinionated functions as well as 8 low-level functions to access detailed information. 9- Simplicity and correctness over performance and resource usage. 10- Well-tested and fuzzed. 11 12Documentation is available on the [website]. 13 14## Using 15 16The public API headers are categorised as either high-level or low-level API 17as per the comments in the header files. Users of libdisplay-info should prefer 18high-level API over low-level API when possible. 19 20If high-level API lacks needed features, please propose additions to the 21high-level API upstream before using low-level API to get what you need. 22If the additions are rejected, you are welcome to use the low-level API. 23 24This policy is aimed to propagate best practises when interpreting EDID 25and DisplayID information which can often be cryptic or even inconsistent. 26 27libdisplay-info uses [semantic versioning]. The public API is not yet stable. 28 29## Contributing 30 31Open issues and merge requests on the [GitLab project]. Discuss and ask 32questions in the [#wayland] IRC channel on OFTC. 33 34In general, the [Wayland contribution guidelines] should be followed. In 35particular, each commit must carry a Signed-off-by tag to denote that the 36submitter adheres to the [Developer Certificate of Origin 1.1]. This project 37follows the [freedesktop.org Contributor Covenant]. 38 39## Building 40 41libdisplay-info has the following dependencies: 42 43- [hwdata] for the PNP ID database used at build-time only. 44 45libdisplay-info is built using [Meson]: 46 47 meson setup build/ 48 ninja -C build/ 49 50## Testing 51 52The low-level EDID library is tested against [edid-decode]. `test/data/` 53contains a small collection of EDID blobs and diffs between upstream 54`edid-decode` and our `di-edid-decode` clone. Our CI ensures the diffs are 55up-to-date. A patch should never make the diffs grow larger. To re-generate the 56test data, build `edid-decode` at the Git revision mentioned in 57`.gitlab-ci.yml`, put the executable in `PATH`, and run 58`ninja -C build/ gen-test-data`. 59 60The latest code coverage report is available on [GitLab CI][coverage]. 61 62## Fuzzing 63 64To fuzz libdisplay-info with [AFL], the library needs to be instrumented: 65 66 CC=afl-gcc meson build/ 67 ninja -C build/ 68 afl-fuzz -i test/data/ -o afl/ build/di-edid-decode/di-edid-decode 69 70[website]: https://emersion.pages.freedesktop.org/libdisplay-info/ 71[semantic versioning]: https://semver.org/ 72[GitLab project]: https://gitlab.freedesktop.org/emersion/libdisplay-info 73[#wayland]: ircs://irc.oftc.net/#wayland 74[Wayland contribution guidelines]: https://gitlab.freedesktop.org/wayland/wayland/-/blob/main/CONTRIBUTING.md 75[Developer Certificate of Origin 1.1]: https://developercertificate.org/ 76[freedesktop.org Contributor Covenant]: https://www.freedesktop.org/wiki/CodeOfConduct/ 77[hwdata]: https://github.com/vcrhonek/hwdata 78[Meson]: https://mesonbuild.com/ 79[coverage]: https://gitlab.freedesktop.org/emersion/libdisplay-info/-/jobs/artifacts/main/file/build/meson-logs/coveragereport/index.html?job=build-gcc 80[edid-decode]: https://git.linuxtv.org/edid-decode.git/ 81[AFL]: https://lcamtuf.coredump.cx/afl/ 82