Message-ID: <20201022112540.GB30566@duo.ucw.cz>
Date:   Thu, 22 Oct 2020 13:25:40 +0200
From:   Pavel Machek <pavel@....cz>
To:     Pavel Pisa <pisa@....felk.cvut.cz>
Cc:     linux-can@...r.kernel.org, devicetree@...r.kernel.org,
        Marc Kleine-Budde <mkl@...gutronix.de>,
        Oliver Hartkopp <socketcan@...tkopp.net>,
        Wolfgang Grandegger <wg@...ndegger.com>,
        David Miller <davem@...emloft.net>,
        Rob Herring <robh+dt@...nel.org>, mark.rutland@....com,
        Carsten Emde <c.emde@...dl.org>, armbru@...hat.com,
        netdev@...r.kernel.org, linux-kernel@...r.kernel.org,
        Marin Jerabek <martin.jerabek01@...il.com>,
        Ondrej Ille <ondrej.ille@...il.com>,
        Jiri Novak <jnovak@....cvut.cz>,
        Jaroslav Beran <jara.beran@...il.com>,
        Petr Porazil <porazil@...ron.com>,
        Drew Fustini <pdp7pdp7@...il.com>
Subject: Re: [PATCH v6 6/6] docs: ctucanfd: CTU CAN FD open-source IP core
 documentation.

On Thu 2020-10-22 10:36:21, Pavel Pisa wrote:
> CTU CAN FD IP core documentation based on Martin Jeřábek's diploma theses
> Open-source and Open-hardware CAN FD Protocol Support
> https://dspace.cvut.cz/handle/10467/80366
> .

> ---
>  .../ctu/FSM_TXT_Buffer_user.png               | Bin 0 -> 174807 bytes

Maybe picture should stay on website, somewhere. It is rather big for
kernel sources.

> +About SocketCAN
> +---------------
> +
> +SocketCAN is a standard common interface for CAN devices in the Linux
> +kernel. As the name suggests, the bus is accessed via sockets, similarly
> +to common network devices. The reasoning behind this is in depth
> +described in `Linux SocketCAN <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/networking/can.rst>`_.
> +In short, it offers a
> +natural way to implement and work with higher layer protocols over CAN,
> +in the same way as, e.g., UDP/IP over Ethernet.

Drop? Or at least link directly to the file in kernel tree?

> +Device probe
> +~~~~~~~~~~~~
> +
> +Before going into detail about the structure of a CAN bus device driver,
> +let's reiterate how the kernel gets to know about the device at all.
> +Some buses, like PCI or PCIe, support device enumeration. That is, when
> +the system boots, it discovers all the devices on the bus and reads
> +their configuration. The kernel identifies the device via its vendor ID
> +and device ID, and if there is a driver registered for this identifier
> +combination, its probe method is invoked to populate the driver's
> +instance for the given hardware. A similar situation goes with USB, only
> +it allows for device hot-plug.
> +
> +The situation is different for peripherals which are directly embedded
> +in the SoC and connected to an internal system bus (AXI, APB, Avalon,
> +and others). These buses do not support enumeration, and thus the kernel
> +has to learn about the devices from elsewhere. This is exactly what the
> +Device Tree was made for.

Dunno. Is it suitable? This is supposed to be ctu-can documentation,
not "how hardware works" docs.

> +Platform device driver
> +^^^^^^^^^^^^^^^^^^^^^^
> +
> +In the case of Zynq, the core is connected via the AXI system bus, which
> +does not have enumeration support, and the device must be specified in
> +Device Tree. This kind of devices is called *platform device* in the
> +kernel and is handled by a *platform device driver*\  [1]_.
> +
> +A platform device driver provides the following things:
> +
> +-  A *probe* function
> +
> +-  A *remove* function
> +
> +-  A table of *compatible* devices that the driver can handle
> +
> +The *probe* function is called exactly once when the device appears (or
> +the driver is loaded, whichever happens later). If there are more
> +devices handled by the same driver, the *probe* function is called for
> +each one of them. Its role is to allocate and initialize resources
> +required for handling the device, as well as set up low-level functions
> +for the platform-independent layer, e.g., *read_reg* and *write_reg*.
> +After that, the driver registers the device to a higher layer, in our
> +case as a *network device*.
> +
> +The *remove* function is called when the device disappears, or the
> +driver is about to be unloaded. It serves to free the resources
> +allocated in *probe* and to unregister the device from higher layers.
> +
> +Finally, the table of *compatible* devices states which devices the
> +driver can handle. The Device Tree entry ``compatible`` is matched
> +against the tables of all *platform drivers*.

And this is "how to write a kernel driver" documentation. Like, why
not, but maybe it does not need to be in kernel tree, and certainly
should be separate from real "what is ctucan and how to use it" docs.

Best regards,
								Pavel
-- 
http://www.livejournal.com/~pavelmachek

Download attachment "signature.asc" of type "application/pgp-signature" (196 bytes)

Powered by blists - more mailing lists