Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20220327042459.141515-1-yusisamerican@gmail.com> <20220327042459.141515-4-yusisamerican@gmail.com>
In-Reply-To: <20220327042459.141515-4-yusisamerican@gmail.com>
From:   Yusuf Khan <yusisamerican@gmail.com>
Date:   Sat, 26 Mar 2022 21:40:12 -0700
Message-ID: <CAJoG2+9We3n89m2HG0twjtxGB-ZQnkxBMW3dvQ=bt7JHyfpsWA@mail.gmail.com>
Subject: Re: [PATCH v9] drivers: ddcci: upstream DDCCI driver
To:     Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

Sorry for the incorrect titles, ill send another patch series shortly
with everything
sorted.

On Sat, Mar 26, 2022 at 9:25 PM Yusuf Khan <yusisamerican@gmail.com> wrote:
>
> This patch adds Documentation for the DDCCI driver.
>
> Signed-off-by: Yusuf Khan <yusisamerican@gmail.com>
> Signed-off-by: Christoph Grenz <christophg+lkml@grenz-bonn.de>
> ---
>  Documentation/ABI/testing/sysfs-driver-ddcci |  57 +++++++++
>  Documentation/driver-api/ddcci.rst           | 122 +++++++++++++++++++
>  2 files changed, 179 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-driver-ddcci
>  create mode 100644 Documentation/driver-api/ddcci.rst
>
> diff --git a/Documentation/ABI/testing/sysfs-driver-ddcci b/Documentation=
/ABI/testing/sysfs-driver-ddcci
> new file mode 100644
> index 000000000000..19f77ccf3ed0
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-driver-ddcci
> @@ -0,0 +1,57 @@
> +What:          /sys/bus/ddcci/ddcci<I=C2=B2C bus number>i<hex address>
> +Date:          March 2022
> +KernelVersion: 5.18
> +Contact:       Christoph Grenz <christophg+lkml@grenz-bonn.de>
> +Description:   This file is a user interface for an internal
> +               dependent device on the I2C bus, it exports the same
> +               information as the master device(/sys/bus/ddcci/
> +               ddcci<I=C2=B2C bus number>) that is referenced in this
> +               document.
> +
> +What:          /sys/bus/ddcci/ddcci<I=C2=B2C bus number>e<hex address>
> +Date:          March 2022
> +KernelVersion: 5.18
> +Contact:       Christoph Grenz <christophg+lkml@grenz-bonn.de>
> +Description:   This file is a user interface for an external
> +               dependent device on the I2C bus, it exports the same
> +               information as the master device(/sys/bus/ddcci/
> +               ddcci<I=C2=B2C bus number>) that is referenced in this
> +               document.
> +
> +What:          /sys/bus/ddcci/ddcci<I=C2=B2C bus number>
> +Date:          March 2022
> +KernelVersion: 5.18
> +Contact:       Christoph Grenz <christophg+lkml@grenz-bonn.de>
> +Description:   This file provides the user interface for the
> +               master device on the I2C bus. It exports the following
> +               peices of information:
> +               - idProt
> +               ACCESS.bus protocol supported by the device. Usually
> +               "monitor".
> +
> +               - idType
> +               ACCESS.bus device subtype. Usually "LCD" or "CRT".
> +
> +               - idModel
> +               ACCESS.bus device model identifier. Usually a
> +               shortened form of the device model name.
> +
> +               - idVendor
> +               ACCESS.bus device vendor identifier. Empty if the
> +               Identification command is not supported.
> +
> +               - idModule
> +               ACCESS.bus device module identifier. Empty if the
> +               Identification command is not supported.
> +
> +               - idSerial
> +               32 bit device number. A fixed serial number if it's
> +               positive, a temporary serial number if negative and zero
> +               if the Identification command is not supported.
> +
> +               - modalias
> +               A combined identifier for driver selection. It has the fo=
rm:
> +               ddcci:<idProt>-<idType>-<idModel>-<idVendor>-<idModule>.
> +               All non-alphanumeric characters (including whitespace)
> +               in the model, vendor or module parts are replaced by
> +               underscores to prevent issues with software like systemd-=
udevd.
> diff --git a/Documentation/driver-api/ddcci.rst b/Documentation/driver-ap=
i/ddcci.rst
> new file mode 100644
> index 000000000000..2b7de1ac2656
> --- /dev/null
> +++ b/Documentation/driver-api/ddcci.rst
> @@ -0,0 +1,122 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +DDC/CI
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +1. Introduction
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +DDC/CI is a control protocol for monitor settings supported by most
> +monitors since about 2005. It is based on ACCESS.bus (an early USB prede=
cessor).
> +This could be used to create drivers that communicate with the DDCCI com=
ponent,
> +see ddcci-backlight for an example.
> +
> +2. sysfs interface
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +Each detected DDC/CI device gets a directory in /sys/bus/ddcci/devices.
> +The main device on a bus is named ddcci[I=C2=B2C bus number].
> +Internal dependent devices are named ddcci[I=C2=B2C bus number]i[hex add=
ress]
> +External dependent devices are named ddcci[I=C2=B2C bus number]e[hex add=
ress]
> +There the following files export information about the device:
> +
> +capabilities
> +The full ACCESS.bus capabilities string. It contains the protocol,
> +type and model of the device, a list of all supported command
> +codes, etc. See the ACCESS.bus spec for more information.
> +
> +- idProt
> +ACCESS.bus protocol supported by the device. Usually "monitor".
> +
> +- idType
> +ACCESS.bus device subtype. Usually "LCD" or "CRT".
> +
> +- idModel
> +ACCESS.bus device model identifier. Usually a shortened form of the
> +device model name.
> +
> +- idVendor
> +ACCESS.bus device vendor identifier. Empty if the Identification command
> +is not supported.
> +
> +- idModule
> +ACCESS.bus device module identifier. Empty if the Identification command
> +is not supported.
> +
> +- idSerial
> +32 bit device number. A fixed serial number if it's positive, a temporar=
y
> +serial number if negative and zero if the
> +Identification command is not supported.
> +
> +- modalias
> +A combined identifier for driver selection. It has the form:
> +ddcci:<idProt>-<idType>-<idModel>-<idVendor>-<idModule>.
> +All non-alphanumeric characters (including whitespace) in the model,
> +vendor or module parts are replaced by underscores to prevent issues
> +with software like systemd-udevd.
> +
> +3. Character device interface
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D
> +For each DDC/CI device a character device in
> +/dev/bus/ddcci/[I=C2=B2C bus number]/ is created,
> +127 devices are assigned in total.
> +
> +The main device on the bus is named display.
> +
> +Internal dependent devices are named i[hex address]
> +
> +External dependent devices are named e[hex address]
> +
> +These character devices can be used to issue commands to a DDC/CI device
> +more easily than over i2c-dev devices. They should be opened unbuffered.
> +To send a command just write the command byte and the arguments with a
> +single write() operation. The length byte and checksum are automatically
> +calculated.
> +
> +To read a response use read() with a buffer big enough for the expected =
answer.
> +
> +NOTE: The maximum length of a DDC/CI message is 32 bytes.
> +
> +4. ddcci-backlight (monitor backlight driver)
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +[This is not specific to the DDC/CI backlight driver, if you already dea=
lt with
> +backlight drivers, skip over this.]
> +
> +For each monitor that supports accessing the Backlight Level White
> +or the Luminance property, a backlight device of type "raw" named like t=
he
> +corresponding ddcci device is created. You can find them in /sys/class/b=
acklight/.
> +For convenience a symlink "ddcci_backlight" on the device associated wit=
h the
> +display connector in /sys/class/drm/ to the backlight device is created,=
 as
> +long as the graphics driver allows to make this association.
> +
> +5. Limitations
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +
> +-Dependent devices (sub devices using DDC/CI directly wired to the monit=
or,
> +like  Calibration devices, IR remotes, etc.) aren't automatically detect=
ed.
> +You can force detection of external dependent devices by writing
> +"ddcci-dependent [address]" into /sys/bus/i2c/i2c-?/new_device.
> +
> +There is no direct synchronization if you manually change the luminance
> +with the buttons on your monitor, as this can only be realized through p=
olling
> +and some monitors close their OSD every time a DDC/CI command is receive=
d.
> +
> +Monitor hotplugging is not detected. You need to detach/reattach the I=
=C2=B2C driver
> +or reload the module.
> +
> +6. Debugging
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +Both drivers use the dynamic debugging feature of the Linux kernel.
> +To get detailed debugging messages, set the dyndbg module parameter.
> +If you want to enable debugging permanently across reboots, create a fil=
e
> +/etc/modprobe.d/ddcci.conf containing lines like the following before lo=
ading the modules:
> +
> +options ddcci dyndbg
> +options ddcci-backlight dyndbg
> +
> +7. Origin
> +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> +This driver originally came from Christoph Grenz in DKMS form here:
> +https://gitlab.com/ddcci-driver-linux/ddcci-driver-linux
> +with multiple backups available on the wayback machine. It also
> +inlcudes a example program for the usage of this driver in
> +userland.
> --
> 2.25.1
>