Re: [PATCH] c-user: CAN framework docs
On Tue, Nov 15, 2022 at 11:14 PM Prashanth S wrote: > > Hi Gedare, > > > What are the images? > There three images: > images/c_user/CAN-framework.jpg-> Overview of CAN-Framework > images/c_user/CAN-rx-data-path.jpg -> Rx Data Path flow > images/c_user/CAN-tx-data-path.jpg -> Tx Data Path flow > We don't have many images in the docs. And as I recall we had a discussion about image formats in docs awhile back. I don't remember the details, but I think it is preferred to provide images generated from a text-based format where possible. From rtems-docs.git/README.txt, we have Images can be created from source using PlantUML and Ditaa. Please have a look to see if you can do that instead. > > This is not exactly correct. It is actually recessive where | CANH - > > CANL | < t1 for some threshold t1, > > and dominant where | CANH - CANL | > t2. And there is a gap where the > > bus is not defined at t1 < | CANH - CANL| < t2 > > This detail is not so important here, but if we're going to describe > > it then we need it to be correct. > > > > > +A 0 data bit encodes a dominant state, while a 1 data bit encodes a > > > recessive > > > +state, supporting a wired-AND convention, which gives nodes with lower ID > > > +numbers priority on the bus. > > > > I see this text has been copied from Wikipedia. This is not acceptable > > without proper attribution/reference. Please rewrite, remove, or > > reference cited material properly. Please identify if any of the below > > text is also copied from anywhere else. > > I will rewrite this text. > > > > > > + > > > +This document covers, the CAN framework and its usage by BSP CAN drivers > > > and > > Remove the comma after covers > > > typo: Initialize > > typo: Further > > I will update these typo errors. > > Regards > Prashanth S > > On Tue, 15 Nov 2022 at 20:34, Gedare Bloom wrote: >> >> Hi Prashant, >> >> What are the images? >> >> On Tue, Nov 15, 2022 at 7:49 AM Prashanth S >> wrote: >> > >> > --- >> > bsp-howto/can.rst | 201 + >> > bsp-howto/index.rst| 1 + >> > images/c_user/CAN-framework.jpg| Bin 0 -> 146625 bytes >> > images/c_user/CAN-rx-data-path.jpg | Bin 0 -> 187438 bytes >> > images/c_user/CAN-tx-data-path.jpg | Bin 0 -> 128765 bytes >> > 5 files changed, 202 insertions(+) >> > create mode 100644 bsp-howto/can.rst >> > create mode 100644 images/c_user/CAN-framework.jpg >> > create mode 100644 images/c_user/CAN-rx-data-path.jpg >> > create mode 100644 images/c_user/CAN-tx-data-path.jpg >> > >> > diff --git a/bsp-howto/can.rst b/bsp-howto/can.rst >> > new file mode 100644 >> > index 000..36d6a04 >> > --- /dev/null >> > +++ b/bsp-howto/can.rst >> > @@ -0,0 +1,201 @@ >> > +.. SPDX-License-Identifier: CC-BY-SA-4.0 >> > + >> > +.. Copyright (C) 2022 Prashanth S >> > + >> > +CAN Library >> > +*** >> > + >> > +Introduction >> > + >> > + >> > +The Controller Area Network is a robust multi-master serial communication >> > +protocol extensively used in automobiles for reliable data transfer. Two >> > or more >> > +nodes are required on the CAN network to communicate. All nodes are >> > connected to >> > +each other through a physically conventional two-wire bus. The wires are a >> > +twisted pair with a 120 Ω (nominal) characteristic impedance. >> > + >> > +This bus uses differential wired-AND signals. Two signals, CAN high >> > (CANH) and >> > +CAN low (CANL) are either driven to a "dominant" state with CANH > CANL >> > or not >> > +driven and pulled by passive resistors to a "recessive" state with CANH ≤ >> > CANL. >> This is not exactly correct. It is actually recessive where | CANH - >> CANL | < t1 for some threshold t1, >> and dominant where | CANH - CANL | > t2. And there is a gap where the >> bus is not defined at t1 < | CANH - CANL| < t2 >> This detail is not so important here, but if we're going to describe >> it then we need it to be correct. >> >> > +A 0 data bit encodes a dominant state, while a 1 data bit encodes a >> > recessive >> > +state, supporting a wired-AND convention, which gives nodes with lower ID >> > +numbers priority on the bus. >> >> I see this text has been copied from Wikipedia. This is not acceptable >> without proper attribution/reference. Please rewrite, remove, or >> reference cited material properly. Please identify if any of the below >> text is also copied from anywhere else. >> >> > + >> > +This document covers, the CAN framework and its usage by BSP CAN drivers >> > and >> Remove the comma after covers >> >> > +applications. >> > + >> > +The CAN framework allows the applications to be written in a portable >> > manner, >> > +which implies that an application can access the CAN bus without knowing >> > the >> > +details of the CAN hardware, the platform specific translations are taken >> > care >> > +by the CAN framework (So the application can focus more on the CAN >> > protocol >> > +specific implementation).
Re: [PATCH] c-user: CAN framework docs
Hi Gedare,
> What are the images?
There three images:
images/c_user/CAN-framework.jpg->* Overview of CAN-Framework*
images/c_user/CAN-rx-data-path.jpg -> *Rx Data Path flow*
images/c_user/CAN-tx-data-path.jpg -> *Tx Data Path flow*
> This is not exactly correct. It is actually recessive where | CANH -
> CANL | < t1 for some threshold t1,
> and dominant where | CANH - CANL | > t2. And there is a gap where the
> bus is not defined at t1 < | CANH - CANL| < t2
> This detail is not so important here, but if we're going to describe
> it then we need it to be correct.
>
> > +A 0 data bit encodes a dominant state, while a 1 data bit encodes a
recessive
> > +state, supporting a wired-AND convention, which gives nodes with lower
ID
> > +numbers priority on the bus.
>
> I see this text has been copied from Wikipedia. This is not acceptable
> without proper attribution/reference. Please rewrite, remove, or
> reference cited material properly. Please identify if any of the below
> text is also copied from anywhere else.
I will rewrite this text.
>
> > +
> > +This document covers, the CAN framework and its usage by BSP CAN
drivers and
> Remove the comma after covers
> typo: Initialize
> typo: Further
I will update these typo errors.
Regards
Prashanth S
On Tue, 15 Nov 2022 at 20:34, Gedare Bloom wrote:
> Hi Prashant,
>
> What are the images?
>
> On Tue, Nov 15, 2022 at 7:49 AM Prashanth S
> wrote:
> >
> > ---
> > bsp-howto/can.rst | 201 +
> > bsp-howto/index.rst| 1 +
> > images/c_user/CAN-framework.jpg| Bin 0 -> 146625 bytes
> > images/c_user/CAN-rx-data-path.jpg | Bin 0 -> 187438 bytes
> > images/c_user/CAN-tx-data-path.jpg | Bin 0 -> 128765 bytes
> > 5 files changed, 202 insertions(+)
> > create mode 100644 bsp-howto/can.rst
> > create mode 100644 images/c_user/CAN-framework.jpg
> > create mode 100644 images/c_user/CAN-rx-data-path.jpg
> > create mode 100644 images/c_user/CAN-tx-data-path.jpg
> >
> > diff --git a/bsp-howto/can.rst b/bsp-howto/can.rst
> > new file mode 100644
> > index 000..36d6a04
> > --- /dev/null
> > +++ b/bsp-howto/can.rst
> > @@ -0,0 +1,201 @@
> > +.. SPDX-License-Identifier: CC-BY-SA-4.0
> > +
> > +.. Copyright (C) 2022 Prashanth S
> > +
> > +CAN Library
> > +***
> > +
> > +Introduction
> > +
> > +
> > +The Controller Area Network is a robust multi-master serial
> communication
> > +protocol extensively used in automobiles for reliable data transfer.
> Two or more
> > +nodes are required on the CAN network to communicate. All nodes are
> connected to
> > +each other through a physically conventional two-wire bus. The wires
> are a
> > +twisted pair with a 120 Ω (nominal) characteristic impedance.
> > +
> > +This bus uses differential wired-AND signals. Two signals, CAN high
> (CANH) and
> > +CAN low (CANL) are either driven to a "dominant" state with CANH > CANL
> or not
> > +driven and pulled by passive resistors to a "recessive" state with CANH
> ≤ CANL.
> This is not exactly correct. It is actually recessive where | CANH -
> CANL | < t1 for some threshold t1,
> and dominant where | CANH - CANL | > t2. And there is a gap where the
> bus is not defined at t1 < | CANH - CANL| < t2
> This detail is not so important here, but if we're going to describe
> it then we need it to be correct.
>
> > +A 0 data bit encodes a dominant state, while a 1 data bit encodes a
> recessive
> > +state, supporting a wired-AND convention, which gives nodes with lower
> ID
> > +numbers priority on the bus.
>
> I see this text has been copied from Wikipedia. This is not acceptable
> without proper attribution/reference. Please rewrite, remove, or
> reference cited material properly. Please identify if any of the below
> text is also copied from anywhere else.
>
> > +
> > +This document covers, the CAN framework and its usage by BSP CAN
> drivers and
> Remove the comma after covers
>
> > +applications.
> > +
> > +The CAN framework allows the applications to be written in a portable
> manner,
> > +which implies that an application can access the CAN bus without
> knowing the
> > +details of the CAN hardware, the platform specific translations are
> taken care
> > +by the CAN framework (So the application can focus more on the CAN
> protocol
> > +specific implementation).
> > +
> > +The CAN framework aims to be compatible with classical CAN and CAN FD.
> > +
> > +CAN Framework
> > +-
> > +
> > +The CAN framework is located in the cpukit/dev/can directory.
> > +
> > +.. figure:: ../../../images/c_user/CAN-framework.jpg
> > + :width: 100%
> > + :align: center
> > + :alt: CAN Framework
> > +
> > +This Fig shows the control flow and data flow of application and BSP
> CAN driver
> > +with the CAN framework.
> > +
> > +Once the BSP CAN driver registers with the CAN framework, the interface
> for an
> > +application to access the CAN hardware will be created (``/dev/can{0,
> 1,
Re: [PATCH] c-user: CAN framework docs
Hi Prashant,
What are the images?
On Tue, Nov 15, 2022 at 7:49 AM Prashanth S wrote:
>
> ---
> bsp-howto/can.rst | 201 +
> bsp-howto/index.rst| 1 +
> images/c_user/CAN-framework.jpg| Bin 0 -> 146625 bytes
> images/c_user/CAN-rx-data-path.jpg | Bin 0 -> 187438 bytes
> images/c_user/CAN-tx-data-path.jpg | Bin 0 -> 128765 bytes
> 5 files changed, 202 insertions(+)
> create mode 100644 bsp-howto/can.rst
> create mode 100644 images/c_user/CAN-framework.jpg
> create mode 100644 images/c_user/CAN-rx-data-path.jpg
> create mode 100644 images/c_user/CAN-tx-data-path.jpg
>
> diff --git a/bsp-howto/can.rst b/bsp-howto/can.rst
> new file mode 100644
> index 000..36d6a04
> --- /dev/null
> +++ b/bsp-howto/can.rst
> @@ -0,0 +1,201 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +.. Copyright (C) 2022 Prashanth S
> +
> +CAN Library
> +***
> +
> +Introduction
> +
> +
> +The Controller Area Network is a robust multi-master serial communication
> +protocol extensively used in automobiles for reliable data transfer. Two or
> more
> +nodes are required on the CAN network to communicate. All nodes are
> connected to
> +each other through a physically conventional two-wire bus. The wires are a
> +twisted pair with a 120 Ω (nominal) characteristic impedance.
> +
> +This bus uses differential wired-AND signals. Two signals, CAN high (CANH)
> and
> +CAN low (CANL) are either driven to a "dominant" state with CANH > CANL or
> not
> +driven and pulled by passive resistors to a "recessive" state with CANH ≤
> CANL.
This is not exactly correct. It is actually recessive where | CANH -
CANL | < t1 for some threshold t1,
and dominant where | CANH - CANL | > t2. And there is a gap where the
bus is not defined at t1 < | CANH - CANL| < t2
This detail is not so important here, but if we're going to describe
it then we need it to be correct.
> +A 0 data bit encodes a dominant state, while a 1 data bit encodes a recessive
> +state, supporting a wired-AND convention, which gives nodes with lower ID
> +numbers priority on the bus.
I see this text has been copied from Wikipedia. This is not acceptable
without proper attribution/reference. Please rewrite, remove, or
reference cited material properly. Please identify if any of the below
text is also copied from anywhere else.
> +
> +This document covers, the CAN framework and its usage by BSP CAN drivers and
Remove the comma after covers
> +applications.
> +
> +The CAN framework allows the applications to be written in a portable manner,
> +which implies that an application can access the CAN bus without knowing the
> +details of the CAN hardware, the platform specific translations are taken
> care
> +by the CAN framework (So the application can focus more on the CAN protocol
> +specific implementation).
> +
> +The CAN framework aims to be compatible with classical CAN and CAN FD.
> +
> +CAN Framework
> +-
> +
> +The CAN framework is located in the cpukit/dev/can directory.
> +
> +.. figure:: ../../../images/c_user/CAN-framework.jpg
> + :width: 100%
> + :align: center
> + :alt: CAN Framework
> +
> +This Fig shows the control flow and data flow of application and BSP CAN
> driver
> +with the CAN framework.
> +
> +Once the BSP CAN driver registers with the CAN framework, the interface for
> an
> +application to access the CAN hardware will be created (``/dev/can{0, 1,
> *}``).
> +Through this interface, applications can access the CAN hardware with the
> +features provided by the CAN framework (buffer management (Tx and Rx
> buffers),
> +multi-threaded access to the CAN hardware, synchronization and concurrency
> +handling between threads)
> +
> +Registering with CAN Framework
> +==
> +
> +Every BSP CAN driver should register itself with the CAN framework to use its
> +services and allow access of CAN hardware to the application.
> +
> +The registration is done by calling ``can_bus_init`` followed by
> +``can_bus_register`` with ``can_bus`` data structure as an argument. The BSP
> +CAN driver should populate the ``can_bus`` data structure with appropriate
> data
> +for a successful registration (``can_bus`` data structure can be allocated by
> +BSP CAN driver and passed to ``can_bus_init`` for initialization or call
> +``can_bus_alloc_and_init`` directly which allocates and initializes
> ``can_bus``
> +data structure).
> +
> +.. code-block:: c
> +
> +can_bus *can_bus_alloc_and_init(size_t size);
> +int can_bus_init(can_bus *bus);
> +
> +rtems_status_code can_bus_register(can_bus *bus, const char *bus_path);
> +
> +Successful registration creates a ``/dev/can{0, 1, *}`` device file for the
> +application to communicate with the corresponding CAN hardware.
> +
> +.. code-block:: c
> +
> +struct can_bus *bus = can_bus_alloc_and_init(sizeof(struct can_bus));
> +
> +priv->bus = bus;
> +
> +
