From: "Kubalewski, Arkadiusz" <arkadiusz.kubalewski@intel.com>
To: Paolo Abeni <pabeni@redhat.com>,
Vadim Fedorenko <vfedorenko@novek.ru>,
Jakub Kicinski <kuba@kernel.org>, Jiri Pirko <jiri@resnulli.us>,
"Jonathan Lemon" <jonathan.lemon@gmail.com>
Cc: "netdev@vger.kernel.org" <netdev@vger.kernel.org>,
Vadim Fedorenko <vadfed@fb.com>,
"linux-arm-kernel@lists.infradead.org"
<linux-arm-kernel@lists.infradead.org>,
"linux-clk@vger.kernel.org" <linux-clk@vger.kernel.org>
Subject: RE: [RFC PATCH v4 3/4] dpll: documentation on DPLL subsystem interface
Date: Thu, 12 Jan 2023 13:45:00 +0000 [thread overview]
Message-ID: <DM6PR11MB4657FF831CE0EBA0E878EF399BFD9@DM6PR11MB4657.namprd11.prod.outlook.com> (raw)
In-Reply-To: <60c011eb99c1859d4ee7191d4cbc20d11548f327.camel@redhat.com>
>From: Paolo Abeni <pabeni@redhat.com>
>Sent: Monday, December 19, 2022 10:13 AM
>
>Hello,
>
>I have a just a few minor notes WRT the documentation - which was a
>very useful entry point for me to help understanding the subsystem.
Hi Paolo, many thanks for your feedback!
>
>On Wed, 2022-11-30 at 00:37 +0300, Vadim Fedorenko wrote:
>> From: Vadim Fedorenko <vadfed@fb.com>
>>
>> Add documentation explaining common netlink interface to configure DPLL
>> devices and monitoring events. Common way to implement DPLL device in
>> a driver is also covered.
>>
>> Co-developed-by: Arkadiusz Kubalewski <arkadiusz.kubalewski@intel.com>
>> Signed-off-by: Arkadiusz Kubalewski <arkadiusz.kubalewski@intel.com>
>> Signed-off-by: Vadim Fedorenko <vadfed@fb.com>
>> ---
>> Documentation/networking/dpll.rst | 271 +++++++++++++++++++++++++++++
>> Documentation/networking/index.rst | 1 +
>> 2 files changed, 272 insertions(+)
>> create mode 100644 Documentation/networking/dpll.rst
>>
>> diff --git a/Documentation/networking/dpll.rst
>b/Documentation/networking/dpll.rst
>> new file mode 100644
>> index 000000000000..58401e2b70a7
>> --- /dev/null
>> +++ b/Documentation/networking/dpll.rst
>> @@ -0,0 +1,271 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +===============================
>> +The Linux kernel DPLL subsystem
>> +===============================
>> +
>> +
>> +The main purpose of DPLL subsystem is to provide general interface
>> +to configure devices that use any kind of Digital PLL and could use
>> +different sources of signal to synchronize to as well as different
>> +types of outputs.
>> +The main interface is NETLINK_GENERIC based protocol with an event
>> +monitoring multicast group defined.
>> +
>> +
>> +Pin object
>> +==========
>> +A pin is amorphic object which represents either input and output, it
>> +could be internal component of the device, as well as externaly
>> +connected.
>> +The number of pins per dpll vary, but usually multiple pins shall be
>> +provided for a single dpll device.
>> +Direction of a pin and it's capabilities are provided to the user in
>> +response for netlink dump request messages.
>> +Pin can be shared by multiple dpll devices. Where configuration on one
>> +pin can alter multiple dplls (i.e. DPLL_PIN_SGINAL_TYPE, DPLL_PIN_TYPE,
>
>Likely typo above: DPLL_PIN_SIGNAL_TYPE
True, shall be fixed in next version.
>
>> +DPLL_PIN_STATE), or just one pin-dpll pair (i.e. DPLL_PIN_PRIO).
>> +Pin can be also a MUX type, where one or more pins are attached to
>> +a parent pin. The parent pin is the one directly connected to the dpll,
>> +which may be used by dplls in DPLL_MODE_AUTOMATIC selection mode, where
>> +only pins directly connected to the dpll are capable of automatic
>> +source pin selection. In such case, pins are dumped with
>> +DPLLA_PIN_PARENT_IDX, and are able to be selected by the userspace with
>> +netlink request.
>> +
>> +Configuration commands group
>> +============================
>> +
>> +Configuration commands are used to get or dump information about
>> +registered DPLL devices (and pins), as well as set configuration of
>> +device or pins. As DPLL device could not be abstract and reflects real
>> +hardware, there is no way to add new DPLL device via netlink from user
>> +space and each device should be registered by it's driver.
>
>Side note: in the long run we could end-up with a virtual/dummy dpll
>driver for self-tests and/or reference's implementation sake.
>
True, seems a good idea.
>> +
>> +List of command with possible attributes
>> +========================================
>> +
>> +All constants identifying command types use ``DPLL_CMD_`` prefix and
>> +suffix according to command purpose. All attributes use ``DPLLA_``
>> +prefix and suffix according to attribute purpose:
>> +
>> + ============================ =======================================
>> + ``DEVICE_GET`` userspace to get device info
>> + ``ID`` attr internal dpll device index
>> + ``NAME`` attr dpll device name
>> + ``MODE`` attr selection mode
>> + ``MODE_SUPPORTED`` attr available selection modes
>> + ``SOURCE_PIN_IDX`` attr index of currently selected source
>> + ``LOCK_STATUS`` attr internal frequency-lock status
>> + ``TEMP`` attr device temperature information
>> + ``NETIFINDEX`` attr dpll owner Linux netdevice index
>
>should we include also the cookie (or wuhatever will be used for
>persistent device identification) into the readable attributes list?
>
In next version cookie is replaced with clock_id and will be also available
for the userspace.
>> + ``DEVICE_SET`` userspace to set dpll device
>> + configuration
>> + ``ID`` attr internal dpll device index
>> + ``MODE`` attr selection mode to configure
>> + ``PIN_IDX`` attr index of source pin to select as
>> + active source
>
>It looks like the descrition for the above attribute ('PIN_IDX') and
>'SOURCE_PIN_IDX' has been swapped.
Good catch, for ``DEVICE_SET`` command, proper attribute is 'SOURCE_PIN_IDX',
will fix that.
>
>> + ``PIN_SET`` userspace to set pins configuration
>> + ``ID`` attr internal dpll device index
>> + ``PIN_IDX`` attr index of a pin to configure
>> + ``PIN_TYPE`` attr type configuration value for
>> + selected pin
>> + ``PIN_SIGNAL_TYPE`` attr signal type configuration value
>> + for selected pin
>> + ``PIN_CUSTOM_FREQ`` attr signal custom frequency to be set
>> + ``PIN_STATE`` attr pin state to be set
>> + ``PIN_PRIO`` attr pin priority to be set
>> +
>> +Netlink dump requests
>> +=====================
>> +The ``DEVICE_GET`` command is capable of dump type netlink requests.
>> +In such case the userspace shall provide ``DUMP_FILTER`` attribute
>> +value to filter the response as required.
>> +If filter is not provided only name and id of available dpll(s) is
>> +provided. If the request also contains ``ID`` attribute, only selected
>> +dpll device shall be dumped.
>
>Should we explicitly document even the required permissions?
Sure, going to add a word about required netlink permission.
>
>> +
>> +Possible response message attributes for netlink requests depending on
>> +the value of ``DPLLA_DUMP_FILTER`` attribute:
>> +
>> + =============================== ====================================
>> + ``DPLL_DUMP_FILTER_PINS`` value of ``DUMP_FILTER`` attribute
>> + ``PIN`` attr nested type contain single pin
>> + attributes
>> + ``PIN_IDX`` attr index of dumped pin
>> + ``PIN_DESCRIPTION`` description of a pin provided by
>> + driver
>> + ``PIN_TYPE`` attr value of pin type
>> + ``PIN_TYPE_SUPPORTED`` attr value of supported pin type
>> + ``PIN_SIGNAL_TYPE`` attr value of pin signal type
>> + ``PIN_SIGNAL_TYPE_SUPPORTED`` attr value of supported pin signal
>> + type
>> + ``PIN_CUSTOM_FREQ`` attr value of pin custom frequency
>> + ``PIN_STATE`` attr value of pin state
>> + ``PIN_STATE_SUPPORTED`` attr value of supported pin state
>> + ``PIN_PRIO`` attr value of pin prio
>> + ``PIN_PARENT_IDX`` attr value of pin patent index
>> + ``PIN_NETIFINDEX`` attr value of netdevice assocaiated
>> + with the pin
>> + ``DPLL_DUMP_FILTER_STATUS`` value of ``DUMP_FILTER`` attribute
>> + ``ID`` attr internal dpll device index
>> + ``NAME`` attr dpll device name
>> + ``MODE`` attr selection mode
>> + ``MODE_SUPPORTED`` attr available selection modes
>> + ``SOURCE_PIN_IDX`` attr index of currently selected
>> + source
>> + ``LOCK_STATUS`` attr internal frequency-lock status
>> + ``TEMP`` attr device temperature information
>> + ``NETIFINDEX`` attr dpll owner Linux netdevice index
>> +
>> +
>> +The pre-defined enums
>> +=====================
>> +
>> +All the enums use the ``DPLL_`` prefix.
>> +
>> +Values for ``PIN_TYPE`` and ``PIN_TYPE_SUPPORTED`` attributes:
>> +
>> + ============================ ========================================
>> + ``PIN_TYPE_MUX`` MUX type pin, connected pins shall
>> + have their own types
>> + ``PIN_TYPE_EXT`` External pin
>> + ``PIN_TYPE_SYNCE_ETH_PORT`` SyncE on Ethernet port
>> + ``PIN_TYPE_INT_OSCILLATOR`` Internal Oscillator (i.e. Holdover
>> + with Atomic Clock as a Source)
>> + ``PIN_TYPE_GNSS`` GNSS 1PPS source
>> +
>> +Values for ``PIN_SIGNAL_TYPE`` and ``PIN_SIGNAL_TYPE_SUPPORTED``
>> +attributes:
>> +
>> + =============================== ===================================
>> + ``PIN_SIGNAL_TYPE_1_PPS`` 1 Hz frequency
>> + ``PIN_SIGNAL_TYPE_10_MHZ`` 10 MHz frequency
>> + ``PIN_SIGNAL_TYPE_CUSTOM_FREQ`` Frequency value provided in attr
>> + ``PIN_CUSTOM_FREQ``
>> +
>> +Values for ``LOCK_STATUS`` attribute:
>> +
>> + ============================= ======================================
>> + ``LOCK_STATUS_UNLOCKED`` DPLL is in freerun, not locked to any
>> + source pin
>> + ``LOCK_STATUS_CALIBRATING`` DPLL device calibrates to lock to the
>> + source pin signal
>> + ``LOCK_STATUS_LOCKED`` DPLL device is locked to the source
>> + pin frequency
>> + ``LOCK_STATUS_HOLDOVER`` DPLL device lost a lock, using its
>> + frequency holdover capabilities
>> +
>> +Values for ``PIN_STATE`` and ``PIN_STATE_SUPPORTED`` attributes:
>> +
>> +============================= ============================
>> + ``PIN_STATE_CONNECTED`` Pin connected to a dpll
>> + ``PIN_STATE_DISCONNECTED`` Pin disconnected from dpll
>> + ``PIN_STATE_SOURCE`` Source pin
>> + ``PIN_STATE_OUTPUT`` Output pin
>> +
>> +Possible DPLL source selection mode values:
>> +
>> + =================== ================================================
>> + ``MODE_FORCED`` source pin is force-selected by
>> + ``DPLL_CMD_DEVICE_SET`` with given value of
>> + ``DPLLA_SOURCE_PIN_IDX`` attribute
>> + ``MODE_AUTOMATIC`` source pin ise auto selected according to
>
>typo above 'ise' -> 'is'
>
Sure, will fix.
Thanks again!
BR,
Arkadiusz
>
>Cheers,
>
>Paolo
next prev parent reply other threads:[~2023-01-12 13:45 UTC|newest]
Thread overview: 87+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-29 21:37 [RFC PATCH v4 0/4] Create common DPLL/clock configuration API Vadim Fedorenko
2022-11-29 21:37 ` [RFC PATCH v4 1/4] dpll: add dpll_attr/dpll_pin_attr helper classes Vadim Fedorenko
2022-11-29 21:37 ` [RFC PATCH v4 2/4] dpll: Add DPLL framework base functions Vadim Fedorenko
2022-11-30 15:21 ` Jiri Pirko
2022-11-30 16:23 ` Jiri Pirko
2022-12-23 16:45 ` Kubalewski, Arkadiusz
2023-01-02 12:28 ` Jiri Pirko
2022-11-30 16:37 ` Jiri Pirko
2022-12-02 11:27 ` Kubalewski, Arkadiusz
2022-12-02 12:39 ` Jiri Pirko
2022-12-02 14:54 ` Kubalewski, Arkadiusz
2022-12-02 16:15 ` Jiri Pirko
[not found] ` <20221202212206.3619bd5f@kernel.org>
2022-12-05 10:32 ` Jiri Pirko
2022-12-06 0:19 ` Jakub Kicinski
2022-12-06 8:50 ` Jiri Pirko
2022-12-06 17:27 ` Jakub Kicinski
2022-12-07 13:10 ` Jiri Pirko
2022-12-07 16:59 ` Jakub Kicinski
2022-12-08 8:14 ` Jiri Pirko
2022-12-08 16:19 ` Jakub Kicinski
2022-12-08 16:33 ` Jiri Pirko
2022-12-08 17:05 ` Jakub Kicinski
2022-12-09 9:29 ` Jiri Pirko
2022-12-09 16:19 ` Jakub Kicinski
2022-12-12 13:36 ` Jiri Pirko
2022-12-13 18:08 ` Kubalewski, Arkadiusz
2022-12-14 7:32 ` Jiri Pirko
2022-11-29 21:37 ` [RFC PATCH v4 3/4] dpll: documentation on DPLL subsystem interface Vadim Fedorenko
2022-12-19 9:13 ` Paolo Abeni
2023-01-12 13:45 ` Kubalewski, Arkadiusz [this message]
2022-11-29 21:37 ` [RFC PATCH v4 4/4] ptp_ocp: implement DPLL ops Vadim Fedorenko
2022-11-30 12:41 ` Jiri Pirko
2022-12-02 11:27 ` Kubalewski, Arkadiusz
2022-12-02 12:48 ` Jiri Pirko
2022-12-02 14:39 ` Kubalewski, Arkadiusz
2022-12-02 16:20 ` Jiri Pirko
2022-12-08 0:35 ` Kubalewski, Arkadiusz
2022-12-08 8:19 ` Jiri Pirko
2022-12-07 2:33 ` Jakub Kicinski
2022-12-07 13:19 ` Jiri Pirko
[not found] ` <20221207090524.3f562eeb@kernel.org>
2022-12-08 11:22 ` Jiri Pirko
2022-12-09 0:36 ` Jakub Kicinski
2022-12-09 9:32 ` Jiri Pirko
2022-11-30 12:32 ` [RFC PATCH v4 0/4] Create common DPLL/clock configuration API Jiri Pirko
2022-12-02 11:27 ` Kubalewski, Arkadiusz
2022-12-02 16:12 ` Jiri Pirko
2022-12-07 2:47 ` Jakub Kicinski
2022-12-07 14:09 ` netdev.dump
2022-12-07 23:21 ` Jakub Kicinski
2022-12-08 11:28 ` Jiri Pirko
2022-12-09 0:39 ` Jakub Kicinski
2022-12-09 0:56 ` Kubalewski, Arkadiusz
2022-12-08 18:08 ` Maciek Machnikowski
2022-12-09 11:07 ` Jiri Pirko
2022-12-09 14:09 ` Maciek Machnikowski
2022-12-09 16:31 ` Jakub Kicinski
2022-12-09 17:11 ` Maciek Machnikowski
2022-12-12 13:58 ` Jiri Pirko
2023-01-09 14:43 ` Kubalewski, Arkadiusz
2023-01-09 16:30 ` Jiri Pirko
2023-01-10 10:54 ` Kubalewski, Arkadiusz
2023-01-10 14:28 ` Jiri Pirko
[not found] ` <645a5bfd-0092-2f39-0ff2-3ffb27ccf8fe@machnikowski.net>
2023-01-11 14:17 ` Kubalewski, Arkadiusz
2023-01-11 14:40 ` Maciek Machnikowski
2023-01-11 15:30 ` Kubalewski, Arkadiusz
2023-01-11 15:54 ` Maciek Machnikowski
2023-01-11 16:27 ` Kubalewski, Arkadiusz
2023-01-10 20:05 ` Jakub Kicinski
2023-01-11 8:19 ` Jiri Pirko
2023-01-11 14:16 ` Kubalewski, Arkadiusz
2023-01-11 15:04 ` Jiri Pirko
2023-01-11 15:30 ` Kubalewski, Arkadiusz
2023-01-11 16:14 ` Jiri Pirko
2023-01-12 12:15 ` Kubalewski, Arkadiusz
2023-01-12 14:43 ` Jiri Pirko
2022-12-09 0:46 ` Kubalewski, Arkadiusz
2022-12-07 14:51 ` Jiri Pirko
[not found] ` <20221207091946.3115742f@kernel.org>
2022-12-08 12:02 ` Jiri Pirko
2022-12-09 0:54 ` Jakub Kicinski
2022-12-08 18:23 ` Kubalewski, Arkadiusz
2022-12-08 0:27 ` Kubalewski, Arkadiusz
2022-12-08 11:58 ` Jiri Pirko
2022-12-08 23:05 ` Kubalewski, Arkadiusz
2022-12-09 10:01 ` Jiri Pirko
2023-01-12 12:23 ` Kubalewski, Arkadiusz
2023-01-12 14:50 ` Jiri Pirko
2023-01-12 19:09 ` Jakub Kicinski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=DM6PR11MB4657FF831CE0EBA0E878EF399BFD9@DM6PR11MB4657.namprd11.prod.outlook.com \
--to=arkadiusz.kubalewski@intel.com \
--cc=jiri@resnulli.us \
--cc=jonathan.lemon@gmail.com \
--cc=kuba@kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-clk@vger.kernel.org \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
--cc=vadfed@fb.com \
--cc=vfedorenko@novek.ru \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).