Document CAN message size handling (#288)

* Document CAN message size handling

Signed-off-by: Konrad Breitsprecher <Konrad.Breitsprecher@vector.com>

Author: KonradBreitsprecherBkd

docs/api/services/can.rst

@@ -67,8 +67,12 @@ CAN controllers will only communicate within the same network.
 Sending CAN Frames
 ~~~~~~~~~~~~~~~~~~
 
-Data is transferred in the form of a |CanFrame| and received as a |CanFrameEvent|. To send a |CanFrame|, it must be setup 
-with a CAN ID and the data to be transmitted. Furthermore, valid |CanFrameFlag| have to be set::
+Data is transferred in the form of a |CanFrame| and received as a |CanFrameEvent|. 
+To send a |CanFrame|, it must be set up with a CAN ID and the data to be transmitted. 
+Furthermore, valid |CanFrameFlag| must be set.
+The |CanFrame| struct allows any payload size via its dataField member, messages that exceed CAN/CAN FD limits are 
+passed through unchanged.
+The following snippet shows how to send a CAN FD frame::
 
   // Prepare a CAN message with id 0x17
   CanFrame canFrame;
@@ -91,14 +95,14 @@ To be notified of the success or failure of the transmission, a ``FrameTransmitH
   };
   canController->AddFrameTransmitHandler(frameTransmitHandler);
 
-An optional second parameter of |AddFrameTransmitHandler| allows to specify the status (|Transmitted|, ...) of the
+An optional second parameter of |AddFrameTransmitHandler| allows specifying the status (|Transmitted|, ...) of the
 |CanFrameTransmitEvent| to be received. By default, each status is enabled.
 
 .. admonition:: Note
 
   In a simple simulation without the network simulator, the |CanTransmitStatus| of the |CanFrameTransmitEvent| will
   always be |Transmitted|. If a detailed simulation is used, it is possible that the transmit queue overflows
-  causing the handler to be called with |TransmitQueueFull| signaling a transmission failure.
+  which causes the handler to be called with |TransmitQueueFull|, signaling a transmission failure.
 
 Receiving CAN Frame Events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -112,8 +116,9 @@ frame, a timestamp and the actual |CanFrame|. The handler is called whenever a |
   };
   canController->AddFrameHandler(frameHandler);
 
-An optional second parameter of |AddFrameHandler| allows to specify the direction (TX, RX, TX/RX) of the CAN frames to be
-received. By default, only frames of RX direction are handled.
+An optional second parameter of |AddFrameHandler| allows specifying the direction (TX, RX, TX/RX) of the CAN frames to 
+be received.
+By default, only frames of RX direction are handled.
 
 Receiving State Change Events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -137,16 +142,18 @@ Then, the controller must be started explicitly by calling |Start|. Now the cont
 Additional control commands are |Stop| and |Reset|.
 
 The following example configures a CAN controller with a baud rate of 10'000 baud for regular CAN messages and a baud 
-rate of 1'000'000 baud for CAN |_| FD messages and 1'000'000 baud for CAN |_| XL, respectively. Then, the controller is started::
+rate of 1'000'000 baud for CAN |_| FD messages and 1'000'000 baud for CAN |_| XL, respectively. Then, the controller
+is started::
 
     canController->SetBaudRate(10000, 1000000, 1000000);
     canController->Start();
 
 .. admonition:: Note
 
-   Both |SetBaudRate| and |Start| should not be called earlier than in the lifecycle service's
-   :cpp:func:`communication ready handler<SilKit::Core::synd::ILifecycleService::SetCommunicationReadyHandler()>`. Otherwise, it is not guaranteed 
-   that all participants are already connected, which can cause the call to have no effect.
+   Both |SetBaudRate| and |Start| should be called in the lifecycle service's 
+   :cpp:func:`communication ready handler<SilKit::Core::synd::ILifecycleService::SetCommunicationReadyHandler()>`.
+   Otherwise, it is not guaranteed that all participants are already connected, which can cause the call to have no 
+   effect.
 
 Managing the Event Handlers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -189,9 +196,11 @@ Enumerations and Typedefs
 Usage Examples
 --------------
 
-This section contains complete examples that show the usage of the CAN controller and the interaction of two or more 
-controllers. Although the CAN controllers would typically belong to different participants and reside in different
-processes, their interaction is shown sequentially to demonstrate cause and effect.
+This section contains complete examples that demonstrate the use of the CAN controller and the interaction between
+two or more controllers.
+
+Although the CAN controllers would typically belong to different participants and reside in different 
+processes, their interaction is shown sequentially here to demonstrate cause and effect.
 
 Assumptions:
 

docs/overview/overview.rst

@@ -26,7 +26,7 @@ It provides:
 
 * Implemented in C++ w/o platform dependencies
 
-* Interoperability between Windows, Linux, and other UNIX derivates​
+* Interoperability between Windows, Linux, and other UNIX derivatives​
 
 * Stable API and ABI as well as long-term network layer compatibility
 
@@ -50,14 +50,20 @@ Vehicle Networks
 The |ProductName| provides means to simulate |CANBuses|, Ethernet, FlexRay, and LIN networks.
 All networks except for FlexRay can be simulated with two different levels of detail: a simple, functional simulation or a detailed simulation.
 The simple simulation assumes no delay and unlimited bandwidth.
+
 The detailed simulation is enabled by using an additional |ProductName| |NetSim|, which considers these aspects as well.
 The |NetSim| is not part of |ProductName| itself.
 Because of its sensitivity regarding time, FlexRay is only supported in a detailed simulation.
 
 Vehicle networks are accessed through their corresponding services (e.g., a CAN controller).
 The service interfaces are the same for simple and detailed simulation.
 As a result, an application that works in the simple use case also works when switching to a detailed simulation using the |NetSim|.
-The section :ref:`sec:api-services` describes how to configure and use vehicle network services in detail.
+
+In general, |ProductName| deliberately avoids imposing restrictions on bus protocols.
+This enables user applications to freely determine the desired level of detail for vehicle network simulations.
+For example, a test participant can inject faulty frames without being blocked by |ProductName|.
+
+The section :ref:`sec:api-services` describes how to configure and use the vehicle network services in detail.
 
 Simulation Basics
 -----------------
@@ -78,8 +84,8 @@ Furthermore, |ProductName| participants can use a virtual simulation time that i
 While participants are first configured in the |ProductName| API by the developer, they can be reconfigured by the user by providing a YAML-based participant configuration file when starting the participant.
 A similar configuration file is available for the |ProductName| Registry as well.
 
-* For getting started operating/orchestrating a |ProductName| simulation, see the :doc:`User Guide <../for-users/users>`.
-* For getting started developing with the |ProductName|, see the :doc:`Developer Guide <../for-developers/developers>`.
+* To get started operating/orchestrating a |ProductName| simulation, see the :doc:`User Guide <../for-users/users>`.
+* To get started developing with the |ProductName|, see the :doc:`Developer Guide <../for-developers/developers>`.
 
 .. _sec:overview-ecosystem:
 
@@ -104,10 +110,10 @@ The |ProductName| ecosystem comprises the following turn-key solutions:
   can be used to attach a virtual CAN (Controller Area Network) interface (SocketCAN) to a Vector SIL Kit CAN bus.
 
 * The `SIL Kit Adapter for Generic Linux IO <https://github.com/vectorgrp/sil-kit-adapters-generic-linux-io>`_
-  allows to attach SIL Kit to a generic Linux IO device, such as character devices or GPIOs.
+  allows attaching SIL Kit to a generic Linux IO device, such as character devices or GPIOs.
 
 * The `SIL Kit FMU Importer <https://github.com/vectorgrp/sil-kit-fmu-importer>`_
-  allows to import Functional Mockup Units (FMUs) as SIL Kit participants.
+  can import Functional Mockup Units (FMUs) as SIL Kit participants.
 
 Related Applications
 ~~~~~~~~~~~~~~~~~~~~
@@ -127,12 +133,12 @@ Guiding Principles
 
 * **Local view:** Participants do not require knowledge about the overall system setup or other participants.
   Communication between participants is made possible by using a common bus network or topic name.
-* **Distributed simulation:** Communication between participants is based on a peer-to-peer connections.
+* **Distributed simulation:** Communication between participants is based on peer-to-peer connections.
   There is no central simulation participant that handles the distribution of messages or controls the virtual time.
 * **Stability:** |ProductName| has a stable network layer and provides API and ABI guarantees.
   This means that participants of different versions can partake in the same simulation.
   Further, the |ProductName| library can be updated to newer versions without having to adapt or recompile already existing |ProductName| applications.
-* **Reconfigurability:** Users should be able to provide a configuration file to the SIL Kit application to change the its behavior (e.g., configure logging or change the network a bus controller connects to).
+* **Reconfigurability:** Users should be able to provide a configuration file to the SIL Kit application to change its behavior (e.g., configure logging or change the network a bus controller connects to).
 
 .. _sec:overview-terminology:
 
@@ -149,7 +155,7 @@ Terminology
    - A participant is a communication node in the distributed simulation that provides access to the |ProductName| services.
  * - :ref:`Services<sec:api-services>`
    - Participants interact with each other through the means of services.
-     These can be communication services, e.g., a :doc:`CAN Controller</api/services/can>` and orchestration services, such as the the Lifecycle Service, Time Synchronization Service, and the Logging Service.
+     These can be communication services, e.g., a :doc:`CAN Controller</api/services/can>` and orchestration services, such as the Lifecycle Service, Time Synchronization Service, and the Logging Service.
  * - :doc:`Configuration<../configuration/configuration>`
    - The optional participant configuration file allows easy configuration of a participant and its interconnection within the simulation.
      It can be used to change a participant's behavior without recompiling its sources.
@@ -183,7 +189,7 @@ Terminology
 Further Reading
 ---------------
 
-More real-world examples involving time synchronization and simulated automotive networks, can be found in the :doc:`API sections<../api/api>`.
+More real-world examples involving time synchronization and simulated automotive networks can be found in the :doc:`API sections<../api/api>`.
 Also, studying the source code of the bundled :doc:`demo applications<../demos/demos>` is a good start.
 The simulation lifecycle and supported simulation time synchronization are discussed in :doc:`../simulation/simulation`.
 Additionally, :doc:`../configuration/configuration` describes how the participant configuration file can be used to change the behavior of participants.