<div dir="ltr"><div dir="ltr">Hi Gedare,<div><br></div><div>> What are the images?</div><div>There three images:</div><div><span style="color:rgb(80,0,80)">images/c_user/CAN-framework.jp</span><span style="color:rgb(80,0,80)">g -><b> Overview of CAN-Framework</b></span></div><div><span style="color:rgb(80,0,80)">images/c_user/CAN-rx-data-path</span><span style="color:rgb(80,0,80)">.jpg -> <b>Rx Data Path flow</b></span><br style="color:rgb(80,0,80)"><span style="color:rgb(80,0,80)">images/c_user/CAN-tx-data-path</span><span style="color:rgb(80,0,80)">.jpg</span> <span style="color:rgb(80,0,80)"> -> <b>Tx Data Path flow</b></span></div><div><br>> This is not exactly correct. It is actually recessive where | CANH -<br>> CANL | < t1 for some threshold t1,<br>> and dominant where | CANH - CANL | > t2. And there is a gap where the<br>> bus is not defined at t1 < | CANH - CANL| < t2<br>> This detail is not so important here, but if we're going to describe<br>> it then we need it to be correct.<span class="gmail-im" style="color:rgb(80,0,80)"><br>><br>> > +A 0 data bit encodes a dominant state, while a 1 data bit encodes a recessive<br>> > +state, supporting a wired-AND convention, which gives nodes with lower ID<br>> > +numbers priority on the bus.<br>><br></span>> I see this text has been copied from Wikipedia. This is not acceptable<br>> without proper attribution/reference. Please rewrite, remove, or<br>> reference cited material properly. Please identify if any of the below<br>> text is also copied from anywhere else.</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div>I will rewrite this text.</div><div><br></div></blockquote><div><span class="gmail-im"><font color="#500050">></font><br><font color="#500050">> > +</font><br><font color="#500050">> > +This document covers, the CAN framework and its usage by BSP CAN drivers and</font><br></span>> Remove the comma after covers</div><div><br></div><div>> typo: Initialize</div><div>> typo: Further</div><div><br></div></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div dir="ltr"><div>I will update these typo errors.</div><div><br></div></div></blockquote>Regards<div>Prashanth S</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, 15 Nov 2022 at 20:34, Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hi Prashant,<br>
<br>
What are the images?<br>
<br>
On Tue, Nov 15, 2022 at 7:49 AM Prashanth S <<a href="mailto:fishesprashanth@gmail.com" target="_blank">fishesprashanth@gmail.com</a>> wrote:<br>
><br>
> ---<br>
> bsp-howto/can.rst | 201 +++++++++++++++++++++++++++++<br>
> bsp-howto/index.rst | 1 +<br>
> images/c_user/CAN-framework.jpg | Bin 0 -> 146625 bytes<br>
> images/c_user/CAN-rx-data-path.jpg | Bin 0 -> 187438 bytes<br>
> images/c_user/CAN-tx-data-path.jpg | Bin 0 -> 128765 bytes<br>
> 5 files changed, 202 insertions(+)<br>
> create mode 100644 bsp-howto/can.rst<br>
> create mode 100644 images/c_user/CAN-framework.jpg<br>
> create mode 100644 images/c_user/CAN-rx-data-path.jpg<br>
> create mode 100644 images/c_user/CAN-tx-data-path.jpg<br>
><br>
> diff --git a/bsp-howto/can.rst b/bsp-howto/can.rst<br>
> new file mode 100644<br>
> index 0000000..36d6a04<br>
> --- /dev/null<br>
> +++ b/bsp-howto/can.rst<br>
> @@ -0,0 +1,201 @@<br>
> +.. SPDX-License-Identifier: CC-BY-SA-4.0<br>
> +<br>
> +.. Copyright (C) 2022 Prashanth S <<a href="mailto:fishesprashanth@gmail.com" target="_blank">fishesprashanth@gmail.com</a>><br>
> +<br>
> +CAN Library<br>
> +***********<br>
> +<br>
> +Introduction<br>
> +============<br>
> +<br>
> +The Controller Area Network is a robust multi-master serial communication<br>
> +protocol extensively used in automobiles for reliable data transfer. Two or more<br>
> +nodes are required on the CAN network to communicate. All nodes are connected to<br>
> +each other through a physically conventional two-wire bus. The wires are a<br>
> +twisted pair with a 120 Ω (nominal) characteristic impedance.<br>
> +<br>
> +This bus uses differential wired-AND signals. Two signals, CAN high (CANH) and<br>
> +CAN low (CANL) are either driven to a "dominant" state with CANH > CANL or not<br>
> +driven and pulled by passive resistors to a "recessive" state with CANH ≤ CANL.<br>
This is not exactly correct. It is actually recessive where | CANH -<br>
CANL | < t1 for some threshold t1,<br>
and dominant where | CANH - CANL | > t2. And there is a gap where the<br>
bus is not defined at t1 < | CANH - CANL| < t2<br>
This detail is not so important here, but if we're going to describe<br>
it then we need it to be correct.<br>
<br>
> +A 0 data bit encodes a dominant state, while a 1 data bit encodes a recessive<br>
> +state, supporting a wired-AND convention, which gives nodes with lower ID<br>
> +numbers priority on the bus.<br>
<br>
I see this text has been copied from Wikipedia. This is not acceptable<br>
without proper attribution/reference. Please rewrite, remove, or<br>
reference cited material properly. Please identify if any of the below<br>
text is also copied from anywhere else.<br>
<br>
> +<br>
> +This document covers, the CAN framework and its usage by BSP CAN drivers and<br>
Remove the comma after covers<br>
<br>
> +applications.<br>
> +<br>
> +The CAN framework allows the applications to be written in a portable manner,<br>
> +which implies that an application can access the CAN bus without knowing the<br>
> +details of the CAN hardware, the platform specific translations are taken care<br>
> +by the CAN framework (So the application can focus more on the CAN protocol<br>
> +specific implementation).<br>
> +<br>
> +The CAN framework aims to be compatible with classical CAN and CAN FD.<br>
> +<br>
> +CAN Framework<br>
> +-------------<br>
> +<br>
> +The CAN framework is located in the cpukit/dev/can directory.<br>
> +<br>
> +.. figure:: ../../../images/c_user/CAN-framework.jpg<br>
> + :width: 100%<br>
> + :align: center<br>
> + :alt: CAN Framework<br>
> +<br>
> +This Fig shows the control flow and data flow of application and BSP CAN driver<br>
> +with the CAN framework.<br>
> +<br>
> +Once the BSP CAN driver registers with the CAN framework, the interface for an<br>
> +application to access the CAN hardware will be created (``/dev/can{0, 1, *}``).<br>
> +Through this interface, applications can access the CAN hardware with the<br>
> +features provided by the CAN framework (buffer management (Tx and Rx buffers),<br>
> +multi-threaded access to the CAN hardware, synchronization and concurrency<br>
> +handling between threads)<br>
> +<br>
> +Registering with CAN Framework<br>
> +==============================<br>
> +<br>
> +Every BSP CAN driver should register itself with the CAN framework to use its<br>
> +services and allow access of CAN hardware to the application.<br>
> +<br>
> +The registration is done by calling ``can_bus_init`` followed by<br>
> +``can_bus_register`` with ``can_bus`` data structure as an argument. The BSP<br>
> +CAN driver should populate the ``can_bus`` data structure with appropriate data<br>
> +for a successful registration (``can_bus`` data structure can be allocated by<br>
> +BSP CAN driver and passed to ``can_bus_init`` for initialization or call<br>
> +``can_bus_alloc_and_init`` directly which allocates and initializes ``can_bus``<br>
> +data structure).<br>
> +<br>
> +.. code-block:: c<br>
> +<br>
> + can_bus *can_bus_alloc_and_init(size_t size);<br>
> + int can_bus_init(can_bus *bus);<br>
> +<br>
> + rtems_status_code can_bus_register(can_bus *bus, const char *bus_path);<br>
> +<br>
> +Successful registration creates a ``/dev/can{0, 1, *}`` device file for the<br>
> +application to communicate with the corresponding CAN hardware.<br>
> +<br>
> +.. code-block:: c<br>
> +<br>
> + struct can_bus *bus = can_bus_alloc_and_init(sizeof(struct can_bus));<br>
> +<br>
> + priv->bus = bus;<br>
> +<br>
> + snprintf(if_name, IF_NAME_SIZE_MAX, "/dev/can%d", i);<br>
> +<br>
> + /* BSP specific information */<br>
> + bus->priv = priv;<br>
> +<br>
> + /* Intialize can_dev_ops */<br>
typo: Initialize<br>
<br>
> + dcan_init_ops(priv);<br>
> +<br>
> + if (can_bus_register(bus, if_name) != 0) {<br>
> + CAN_ERR("beagle_can_init: bus register failed\n");<br>
> + free(priv);<br>
> + return;<br>
> + }<br>
> +<br>
> +This example shows the DCAN BSP driver registration with the CAN framework.<br>
> +<br>
> +Concurrency and buffer synchronization<br>
> +======================================<br>
> +<br>
> +The CAN framework uses a counting semaphore (one for Tx FIFO and one for Rx<br>
> +FIFO) and a mutex to handle concurrency and buffer synchronization. The count<br>
> +value depends on the number of FIFO<br>
> +buffers allocated.<br>
> +<br>
> +In the Tx path, at any time, the semaphore count denotes the number of empty Tx<br>
> +FIFO buffers available.<br>
> +<br>
> +In the Rx path, at any time, the semaphore count denotes the number of valid CAN<br>
> +messages in the Rx FIFO buffer available.<br>
> +<br>
> +Tx and Rx data flow<br>
> +===================<br>
> +<br>
> +The ``can_msg`` data structure defined in ``cpukit/include/dev/can/can-msg.h``<br>
> +represents a CAN message in application, CAN framework and BSP CAN driver.<br>
> +<br>
> +.. code-block:: c<br>
> +<br>
> + struct can_msg {<br>
> + uint32_t id;<br>
> + uint32_t timestamp;<br>
> + uint16_t flags;<br>
> + uint16_t len;<br>
> + uint8_t data[CAN_MSG_MAX_SIZE];<br>
> + };<br>
> +<br>
> +Applications use the interface ``/dev/can{0, 1, *)`` device file to communicate<br>
> +with the CAN hardware. Once the device file is created by the CAN framework,<br>
> +applications can do file operations (open, close, read, write, ioctl) on the<br>
> +device file. Every file operation on the device file is handled by the CAN framework.<br>
> +<br>
> +Tx data flow<br>
> +------------<br>
> +Once a ``write`` is made on ``/dev/can{0, 1, *}`` from the application to send a<br>
> +CAN message, it reaches the ``can_bus_write``. The ``can_bus_write`` checks for<br>
> +the availability of empty Tx FIFO buffer (by calling ``rtems_semaphore_obtain``).<br>
> +If an empty buffer is not available, based on the flags to the open call it sleeps<br>
> +or returns).<br>
> +<br>
> +If an empty Tx FIFO buffer is available, the CAN message is copied to the Tx FIFO<br>
> +buffer and checks whether CAN hardware is ready to accept a CAN message to transmit<br>
> +(by calling the function ``can_dev_ops->dev_tx_ready``). If the device is not<br>
> +ready to accept, the instance returns to the application with number of bytes<br>
> +copied.<br>
> +<br>
> +If the device is ready, ``can_xmit`` function is called, which picks up a buffer<br>
> +from Tx FIFO to transmit. Then ``can_dev_ops->dev_tx`` is called with<br>
> +``can_msg`` data structure as an argument (where the CAN hardware handles the<br>
> +``can_msg`` data structure to transmit). Once the CAN message is copied to the<br>
> +device FIFO to transmit, ``can_dev_ops->dev_tx`` returns back to ``can_xmit``<br>
> +invalidates the corresponding Tx FIFO buffer and wakes up an instance (by<br>
> +calling ``rtems_semaphore_release``) that is waiting for an empty CAN Tx FIFO<br>
> +buffer.<br>
> +<br>
> +The BSP CAN driver then sends the CAN message to the CAN bus. Once the CAN<br>
> +message transmission is complete the BSP CAN driver should call ``can_txdone``,<br>
> +which in turn calls ``can_xmit`` for further CAN message to send.<br>
> +<br>
> +.. caution::<br>
> + ``can_xmit`` function runs with interrupts disabled, this means the ``can_dev_ops->dev_tx``<br>
> + should return as soon as possible.<br>
> +<br>
> +This figure shows the Tx data path.<br>
> +<br>
> +.. figure:: ../../../images/c_user/CAN-tx-data-path.jpg<br>
> + :width: 100%<br>
> + :align: center<br>
> + :alt: CAN Tx data path<br>
> +<br>
> +Rx data flow<br>
> +------------<br>
> +Once a ``read`` is made on ``/dev/can{0, 1, *}`` from the application, the<br>
> +instance reaches the ``can_bus_read``. The ``can_bus_read`` function checks, if<br>
> +there are any CAN messages available in the Rx FIFO (this can be checked by calling<br>
> +``rtems_semaphore_obtain``). If available, the requested bytes of data are<br>
> +copied to user buffer and the corresponding Rx Fifo buffers are invalidated. If no<br>
> +Rx message is available, the instance goes to sleep or returns based on the<br>
> +flags to the open call.<br>
> +<br>
> +On the BSP CAN driver, Once a CAN message is received from the CAN bus, the<br>
> +message is given to the CAN Framework by calling ``can_receive`` function.<br>
> +<br>
> +This figure shows the Rx data path.<br>
> +<br>
> +.. figure:: ../../../images/c_user/CAN-rx-data-path.jpg<br>
> + :width: 100%<br>
> + :align: center<br>
> + :alt: CAN Rx data path<br>
> +<br>
> +.. seealso::<br>
> +<br>
> + For Reference, `DCAN BSP driver <<a href="https://github.com/RTEMS/rtems/commit/26d50bdfb601b9ef71ec2b30d2d9467c2437f443" rel="noreferrer" target="_blank">https://github.com/RTEMS/rtems/commit/26d50bdfb601b9ef71ec2b30d2d9467c2437f443</a>>`_ is implemented which uses CAN framework.<br>
> +<br>
> +.. admonition:: Note<br>
> +<br>
> + The existing implementation creates only two FIFO (each one for Tx and Rx).<br>
> + Futher implementation of creating Tx and Rx FIFO for each open call should be done.<br>
typo: Further<br>
<br>
> diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst<br>
> index d095fc7..4f5af01 100644<br>
> --- a/bsp-howto/index.rst<br>
> +++ b/bsp-howto/index.rst<br>
> @@ -32,6 +32,7 @@ RTEMS BSP and Driver Guide (|version|).<br>
> getentropy<br>
> i2c<br>
> spi<br>
> + can<br>
> real_time_clock<br>
> networking<br>
> frame_buffer<br>
> diff --git a/images/c_user/CAN-framework.jpg b/images/c_user/CAN-framework.jpg<br>
> new file mode 100644<br>
<br>
...<br>
</blockquote></div>