Hi Prashant,
What are the images?
On Tue, Nov 15, 2022 at 7:49 AM Prashanth S <fishesprasha...@gmail.com> 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 0000000..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 <fishesprasha...@gmail.com>
> +
> +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;
> +
> + snprintf(if_name, IF_NAME_SIZE_MAX, "/dev/can%d", i);
> +
> + /* BSP specific information */
> + bus->priv = priv;
> +
> + /* Intialize can_dev_ops */
typo: Initialize
> + dcan_init_ops(priv);
> +
> + if (can_bus_register(bus, if_name) != 0) {
> + CAN_ERR("beagle_can_init: bus register failed\n");
> + free(priv);
> + return;
> + }
> +
> +This example shows the DCAN BSP driver registration with the CAN framework.
> +
> +Concurrency and buffer synchronization
> +======================================
> +
> +The CAN framework uses a counting semaphore (one for Tx FIFO and one for Rx
> +FIFO) and a mutex to handle concurrency and buffer synchronization. The count
> +value depends on the number of FIFO
> +buffers allocated.
> +
> +In the Tx path, at any time, the semaphore count denotes the number of empty
> Tx
> +FIFO buffers available.
> +
> +In the Rx path, at any time, the semaphore count denotes the number of valid
> CAN
> +messages in the Rx FIFO buffer available.
> +
> +Tx and Rx data flow
> +===================
> +
> +The ``can_msg`` data structure defined in
> ``cpukit/include/dev/can/can-msg.h``
> +represents a CAN message in application, CAN framework and BSP CAN driver.
> +
> +.. code-block:: c
> +
> + struct can_msg {
> + uint32_t id;
> + uint32_t timestamp;
> + uint16_t flags;
> + uint16_t len;
> + uint8_t data[CAN_MSG_MAX_SIZE];
> + };
> +
> +Applications use the interface ``/dev/can{0, 1, *)`` device file to
> communicate
> +with the CAN hardware. Once the device file is created by the CAN framework,
> +applications can do file operations (open, close, read, write, ioctl) on the
> +device file. Every file operation on the device file is handled by the CAN
> framework.
> +
> +Tx data flow
> +------------
> +Once a ``write`` is made on ``/dev/can{0, 1, *}`` from the application to
> send a
> +CAN message, it reaches the ``can_bus_write``. The ``can_bus_write`` checks
> for
> +the availability of empty Tx FIFO buffer (by calling
> ``rtems_semaphore_obtain``).
> +If an empty buffer is not available, based on the flags to the open call it
> sleeps
> +or returns).
> +
> +If an empty Tx FIFO buffer is available, the CAN message is copied to the Tx
> FIFO
> +buffer and checks whether CAN hardware is ready to accept a CAN message to
> transmit
> +(by calling the function ``can_dev_ops->dev_tx_ready``). If the device is not
> +ready to accept, the instance returns to the application with number of bytes
> +copied.
> +
> +If the device is ready, ``can_xmit`` function is called, which picks up a
> buffer
> +from Tx FIFO to transmit. Then ``can_dev_ops->dev_tx`` is called with
> +``can_msg`` data structure as an argument (where the CAN hardware handles the
> +``can_msg`` data structure to transmit). Once the CAN message is copied to
> the
> +device FIFO to transmit, ``can_dev_ops->dev_tx`` returns back to ``can_xmit``
> +invalidates the corresponding Tx FIFO buffer and wakes up an instance (by
> +calling ``rtems_semaphore_release``) that is waiting for an empty CAN Tx FIFO
> +buffer.
> +
> +The BSP CAN driver then sends the CAN message to the CAN bus. Once the CAN
> +message transmission is complete the BSP CAN driver should call
> ``can_txdone``,
> +which in turn calls ``can_xmit`` for further CAN message to send.
> +
> +.. caution::
> + ``can_xmit`` function runs with interrupts disabled, this means the
> ``can_dev_ops->dev_tx``
> + should return as soon as possible.
> +
> +This figure shows the Tx data path.
> +
> +.. figure:: ../../../images/c_user/CAN-tx-data-path.jpg
> + :width: 100%
> + :align: center
> + :alt: CAN Tx data path
> +
> +Rx data flow
> +------------
> +Once a ``read`` is made on ``/dev/can{0, 1, *}`` from the application, the
> +instance reaches the ``can_bus_read``. The ``can_bus_read`` function
> checks, if
> +there are any CAN messages available in the Rx FIFO (this can be checked by
> calling
> +``rtems_semaphore_obtain``). If available, the requested bytes of data are
> +copied to user buffer and the corresponding Rx Fifo buffers are invalidated.
> If no
> +Rx message is available, the instance goes to sleep or returns based on the
> +flags to the open call.
> +
> +On the BSP CAN driver, Once a CAN message is received from the CAN bus, the
> +message is given to the CAN Framework by calling ``can_receive`` function.
> +
> +This figure shows the Rx data path.
> +
> +.. figure:: ../../../images/c_user/CAN-rx-data-path.jpg
> + :width: 100%
> + :align: center
> + :alt: CAN Rx data path
> +
> +.. seealso::
> +
> + For Reference, `DCAN BSP driver
> <https://github.com/RTEMS/rtems/commit/26d50bdfb601b9ef71ec2b30d2d9467c2437f443>`_
> is implemented which uses CAN framework.
> +
> +.. admonition:: Note
> +
> + The existing implementation creates only two FIFO (each one for Tx and
> Rx).
> + Futher implementation of creating Tx and Rx FIFO for each open call
> should be done.
typo: Further
> diff --git a/bsp-howto/index.rst b/bsp-howto/index.rst
> index d095fc7..4f5af01 100644
> --- a/bsp-howto/index.rst
> +++ b/bsp-howto/index.rst
> @@ -32,6 +32,7 @@ RTEMS BSP and Driver Guide (|version|).
> getentropy
> i2c
> spi
> + can
> real_time_clock
> networking
> frame_buffer
> diff --git a/images/c_user/CAN-framework.jpg b/images/c_user/CAN-framework.jpg
> new file mode 100644
...
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
