Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
MIME-Version: 1.0
References: <20200926135514.26189-1-luka.kovacic@sartura.hr>
 <20200926135514.26189-6-luka.kovacic@sartura.hr> <20200926202521.100d17f8@nic.cz>
In-Reply-To: <20200926202521.100d17f8@nic.cz>
From:   Luka Kovacic <luka.kovacic@sartura.hr>
Date:   Sun, 27 Sep 2020 17:49:02 +0200
Message-ID: <CADZsf3YmbELw6mw2wT2tkkx03zf1y_jM2vrBDH1_HqXc--AHew@mail.gmail.com>
Subject: Re: [PATCH v2 5/7] Documentation/ABI: Add iei-wt61p803-puzzle driver
 sysfs interface documentation
To:     Marek Behun <marek.behun@nic.cz>
Cc:     Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        linux-hwmon@vger.kernel.org,
        linux-arm Mailing List <linux-arm-kernel@lists.infradead.org>,
        Linux LED Subsystem <linux-leds@vger.kernel.org>,
        Lee Jones <lee.jones@linaro.org>, Pavel Machek <pavel@ucw.cz>,
        Dan Murphy <dmurphy@ti.com>, Rob Herring <robh+dt@kernel.org>,
        Jean Delvare <jdelvare@suse.com>,
        Guenter Roeck <linux@roeck-us.net>,
        Andrew Lunn <andrew@lunn.ch>,
        Jason Cooper <jason@lakedaemon.net>,
        Gregory Clement <gregory.clement@bootlin.com>,
        Luka Perkov <luka.perkov@sartura.hr>,
        Robert Marko <robert.marko@sartura.hr>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

I agree, I'll move this over to testing.

These values are stored in the microcontroller EEPROM and can be modified.
Some test units might be shipped with unpopulated MAC address and S/N values
so I exposed this functionality to enable the user to use some
internal value there.

Kind regards,
Luka

On Sat, Sep 26, 2020 at 8:25 PM Marek Behun <marek.behun@nic.cz> wrote:
>
> On Sat, 26 Sep 2020 15:55:12 +0200
> Luka Kovacic <luka.kovacic@sartura.hr> wrote:
>
> > Add the iei-wt61p803-puzzle driver sysfs interface documentation to allow
> > monitoring and control of the microcontroller from user space.
> >
> > Signed-off-by: Luka Kovacic <luka.kovacic@sartura.hr>
> > Cc: Luka Perkov <luka.perkov@sartura.hr>
> > Cc: Robert Marko <robert.marko@sartura.hr>
> > ---
> >  .../stable/sysfs-driver-iei-wt61p803-puzzle   | 65 +++++++++++++++++++
> >  1 file changed, 65 insertions(+)
> >  create mode 100644 Documentation/ABI/stable/sysfs-driver-iei-wt61p803-puzzle
> >
> > diff --git a/Documentation/ABI/stable/sysfs-driver-iei-wt61p803-puzzle b/Documentation/ABI/stable/sysfs-driver-iei-wt61p803-puzzle
> > new file mode 100644
> > index 000000000000..36fca70d66ef
> > --- /dev/null
> > +++ b/Documentation/ABI/stable/sysfs-driver-iei-wt61p803-puzzle
>
> I think this should go to testing, not stable. It should go to stable
> only after it is stable for some time.
>
> > @@ -0,0 +1,65 @@
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/mac_address_*
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the internal iEi WT61P803 PUZZLE MCU MAC address values.
> > +             These are factory assigned and can be changed.
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/serial_number
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the internal iEi WT61P803 PUZZLE MCU serial number.
> > +             This value is factory assigned and can be changed.
> > +
>
> Please use (RO) and (RW) prefixes before the Description, instead of
> writing "This value is read only", i.e.:
>   Description: (RO) Internal ... serial number.
>
> JFI: Why can these values be changed? Shouldn't they be burned into OTP?
>
> Marek
>
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/version
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the internal iEi WT61P803 PUZZLE MCU version.
> > +             This value is read only.
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/protocol_version
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the internal iEi WT61P803 PUZZLE MCU protocol version.
> > +             This value is read only.
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/power_loss_recovery
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the iEi WT61P803 PUZZLE MCU power loss recovery value.
> > +             This value is read write.
> > +             Value mapping: 0 - Always-On, 1 - Always-Off, 2 - Always-AC, 3 - Always-WA
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/bootloader_mode
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read whether the MCU is in bootloader mode.
> > +             This value is read only.
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/power_status
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the iEi WT61P803 PUZZLE MCU power status. Power status indicates
> > +             the power on method.
> > +             This value is read only.
> > +             Value mapping (bitwise list):
> > +             0x80 - Null
> > +             0x40 - Firmware flag
> > +             0x20 - Power loss detection flag (powered off)
> > +             0x10 - Power loss detection flag (AC mode)
> > +             0x08 - Button power on
> > +             0x04 - WOL power on
> > +             0x02 - RTC alarm power on
> > +             0x01 - AC recover power on
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/build_info
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the iEi WT61P803 PUZZLE MCU firmware build date.
> > +             This value is read only.
> > +             Format: yyyy/mm/dd hh:mm
> > +
> > +What:                /sys/bus/serial/devices/.../iei_wt61p803_puzzle_core/ac_recovery_status
> > +Date:                September 2020
> > +Contact:     Luka Kovacic <luka.kovacic@sartura.hr>
> > +Description: Read the iEi WT61P803 PUZZLE MCU AC recovery status.
> > +             This value is read only.
>