Second version of OCERA casestudies. This version fixes many errors, enhances the...

[canping.git] / doc / canping.xml

<?xml version="1.0" encoding="ISO-8859-2"?>
<!-- <?xml version="1.0" encoding="ISO-8859-2"?> -->
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -->
<!-- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ -->
<!-- <!ENTITY % canping_path "."> -->
<!-- <!ENTITY % canping_entities SYSTEM "canping.ent"> -->
<!-- %canping_entities; -->
<!-- ]> -->
<chapter>
  <title>CANping &ndash; a simple LinCAN testing application</title>

  <section>
    <title>Introduction</title>

    <para>This chapter describes a simple application called
    <productname>canping</productname>. Its primary goal was to test the
    LinCAN driver but it also nicely illustrates how to use LinCAN driver in
    real applications. In addition, it shows some maliciousness of the LinCAN
    driver.</para>

    <para>Canping is a multithread application, which sends and receives
    messages in parallel and thus can be used for stress testing of the LinCAN
    driver. For basic usage, two running instances of canping, each one on a
    different host, are needed. One instance sends messages and waits for
    replies and the other instance waits for the sent messages and sends
    replays with an ID incremented by one. Canping can also be run twice on
    one host provided that we are either using a virtual CAN device or there
    are multiple CAN cards/chips in the host.</para>
  </section>

  <section>
    <title>CANping manual</title>

    <refentry>
      <refnamediv>
        <refname>canping</refname>

        <refpurpose>Multi-thread LinCAN testing utility</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
        <cmdsynopsis>
          <command>canping</command>

          <group>
            <arg choice="req">-m <replaceable>num</replaceable></arg>

            <arg choice="req">-s <replaceable>num</replaceable></arg>
          </group>

          <arg>-c <replaceable>count</replaceable></arg>

          <arg>-d <replaceable>device</replaceable></arg>

          <arg>-h</arg>

          <arg>-i <replaceable>id</replaceable></arg>

          <arg>-l <replaceable>length</replaceable></arg>

          <arg>-o</arg>

          <arg>-t <replaceable>timeout</replaceable></arg>

          <arg>-y <replaceable>count</replaceable></arg>
        </cmdsynopsis>
      </refsynopsisdiv>

      <refsect1>
        <title>Options</title>

        <variablelist>
          <varlistentry>
            <term><option>-m <replaceable>num</replaceable></option></term>

            <listitem>
              <para>Start in the master mode and run
              <replaceable>num</replaceable> master threads in
              parallel.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-s <replaceable>num</replaceable></option></term>

            <listitem>
              <para>Start in the slave mode and run
              <replaceable>num</replaceable> slave threads in parallel.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-c <replaceable>count</replaceable></option></term>

            <listitem>
              <para>Every master thread will send only
              <replaceable>count</replaceable> messages and then finishes.
              Without this option messages are sent forever and CANping can be
              terminated by a signal e.g. by pressing a <keycombo>
                  <keysym>Ctrl+C</keysym>
                </keycombo> key.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-d <replaceable>device</replaceable></option></term>

            <listitem>
              <para>CAN device to be used. Default is
              <filename>/dev/can0</filename>.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-i <replaceable>id</replaceable></option></term>

            <listitem>
              <para>Select ID of the lowest generated or responded message.
              Default is 1000. CANping in the master mode will generate
              messages with IDs <replaceable>id</replaceable>,
              <replaceable>id</replaceable>+2,
              <replaceable>id</replaceable>+4, etc. Each master thread will
              generate different ID. The slave threads will listen to these
              IDs and will answer with an ID increased by one.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-l <replaceable>len</replaceable></option></term>

            <listitem>
              <para>Specify a length of the messages. Default is 8 and
              possible values are from 0 to 8.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-t <replaceable>sec</replaceable></option></term>

            <listitem>
              <para>A timeout in seconds; this option specifies how long the
              master thread will wait for the response message from a slave.
              If the response won't arrive in <replaceable>SEC</replaceable>
              seconds, the message is considered as loosed.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-v</option></term>

            <listitem>
              <para>Increase verbosity. Without this option only summary
              statistics are displayed just before the program finishes. One
              -v means to display a global status (number of sent messages and
              timeouts) during program execution. Two -v options display a
              simple message for every packet in the format <emphasis
              role="bold">ID:time</emphasis> where time is measured in
              microseconds. Three -v options display more verbose information
              about each packet.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-w <replaceable>msec</replaceable></option></term>

            <listitem>
              <para>Wait time in milliseconds before the master thread sends a
              next message. Default value is 1000 ms.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><option>-y</option></term>

            <listitem>
              <para>Synchronize the master threads before sending the first
              message. When CANping is stared with the high number of master
              threads, usually the first created thread will begin by sending
              the messages before the last thread is created. Sometimes it may
              be useful that every thread will wait before sending anything to
              the other threads. Only when all threads are created and
              prepared for sending, sending can start.</para>
            </listitem>
          </varlistentry>
        </variablelist>
      </refsect1>

      <refsect1>
        <title>Exit codes</title>

        <para>The <productname>canping</productname> exit code depends on how
        the program finishes. This feature can be used for (semi)automatic
        testing of <productname>LinCAN</productname> driver. Exit codes are
        listed in the table bellow.</para>

        <informaltable frame="none" pgwide="0">
          <tgroup cols="2">
            <colspec align="center" colwidth="1cm" />

            <tbody>
              <row>
                <entry>0</entry>

                <entry>OK</entry>
              </row>

              <row>
                <entry>1</entry>

                <entry>Bad command line parameter</entry>
              </row>

              <row>
                <entry>2</entry>

                <entry>Problem with opening LinCAN driver</entry>
              </row>

              <row>
                <entry>3</entry>

                <entry>Problem with filter</entry>
              </row>

              <row>
                <entry>4</entry>

                <entry>Insufficient memory</entry>
              </row>

              <row>
                <entry>5</entry>

                <entry>Read syscall error</entry>
              </row>

              <row>
                <entry>6</entry>

                <entry>Write syscall error</entry>
              </row>

              <row>
                <entry>7</entry>

                <entry>Select syscall error</entry>
              </row>

              <row>
                <entry>8</entry>

                <entry>Flush (ioctl syscall) error</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </refsect1>

      <refsect1>
        <title>Examples</title>

        <para>On one computer one runs slave with 10 threads:</para>

        <screen><prompt>root@pc104:~%</prompt> canping -d /dev/can1 -s 10</screen>

        <para>and on another computer master is run with 10 threads
        too:</para>

        <screen><prompt>sojka@glab:~%</prompt> canping -d /dev/can4 -m 10 -v -c 100 -w 10
Total count: 1000, Timeouts: 0
Summary statistics:
Id 1000: count = 100 mean = 8005.16 stddev = 691.01 min = 2022 max = 11133 [us] loss = 0% (0) 
Id 1002: count = 100 mean = 8013.10 stddev = 641.19 min = 4013 max = 12885 [us] loss = 0% (0) 
Id 1004: count = 100 mean = 8035.99 stddev = 575.36 min = 5996 max = 13081 [us] loss = 0% (0) 
Id 1006: count = 100 mean = 8062.38 stddev = 626.46 min = 7005 max = 14061 [us] loss = 0% (0)
Id 1008: count = 100 mean = 8082.63 stddev = 740.59 min = 5963 max = 15020 [us] loss = 0% (0)
Id 1010: count = 100 mean = 8089.04 stddev = 831.64 min = 7018 max = 15970 [us] loss  = 0% (0)
Id 1012: count = 100 mean = 8105.02 stddev = 952.95 min = 7011 max = 16970 [us] loss = 0% (0) 
Id 1014: count = 100 mean = 8129.57 stddev = 1037.39 min = 7020 max = 17906 [us] loss = 0% (0) 
Id 1016: count = 100 mean = 8144.46 stddev = 1154.17 min = 7019 max = 18870 [us] loss = 0% (0) 
Id 1018: count = 100 mean = 8157.85 stddev = 1259.84 min = 5994 max = 19842 [us] loss = 0% (0)</screen>

        <para>At the end of program execution, there are statistics for each
        packet type (ID). These contain mean round trip times (RTT), standard
        deviations of RTT, minimal and maximal RTT and packet losses
        (percentage and absolute).</para>
      </refsect1>
    </refentry>
  </section>

  <section>
    <title>Implementation details</title>

    <para>The structure of <productname>canping</productname> is as follows.
    After the initialization and parsing of command line options (function
    <function>parse_optins()</function>), communicating threads are started.
    The code of these threads is made up by
    <function>master_thread()</function> and
    <function>slave_thread()</function> functions which are described in the
    following section.</para>

    <para>After these threads are finished (either after pressing
    <keycap>Ctrl-C</keycap> or due to <parameter>-c</parameter> switch),
    summary statistics are written to stdout and the application
    finishes.</para>

    <section>
      <title>Usage of the LinCAN driver</title>

      <para>This section will cover <function>master_thread()</function>
      function. Code of <function>slave_thread()</function> is very similar to
      <function>master_thread()</function>, so it will not be covered here.
      These functions represent typical usage of the LinCAN driver in
      applications and if you are looking for examples how to use the LinCAN
      driver, this is probably the most important section for you.</para>

      <para>The <function>master_thread()</function> function is responsible
      for opening the driver, sending message with a particular ID and waiting
      for response message. Sending and receiving messages is done
      periodically in a loop.</para>

      <section>
        <title>Opening the Driver</title>

        <para>At the beginning of every access to the LinCAN driver, the
        driver has to be opened. This is done by calling
        <function>open()</function>.<programlisting>canfd = open(option_device, O_RDWR)</programlisting></para>

        <para>The value of the <varname>option_device</varname> variable
        specifies the name of CAN device e.g. <filename>/dev/can0</filename>
        and the second parameter contains additional flags. We are using a
        <constant>O_RDWR</constant> flag which means that we want to use the
        driver for both reading and writing (messages). You can also use the
        <constant>O_NOBLOCK</constant> flag in addition. For further details
        regarding this flag see the LinCAN documentation.</para>

        <para>If the opening operation succeeds, the <varname>canfd</varname>
        variable contains a valid file descriptor, which is used for further
        communication with the driver. In the case of an error, we use
        <function>perror()</function> function to print the reason of the
        error and then we exit the program with appropriate exit code<footnote>
            <para>The exit code can be used by an automatic regression tests
            to detect the reason of failure.</para>
          </footnote>.</para>
      </section>

      <section>
        <title>Setting Filters</title>

        <para>After the device is open, the second step is to create a filter
        for message receiving. The filter assures this thread only receives
        messages it is waiting for.</para>

        <programlisting>/* setup filtering of received messages */
memset(&amp;canfilt, 0, sizeof(canfilt));
canfilt.mask = 0xfffffff;
canfilt.id = pong_id; /* pong responces with increased id */
ret = ioctl(canfd, CANQUE_FILTER, &amp;canfilt);
</programlisting>

        <para>The filter is created by filling the <type>canfilt_t</type>
        structure and submitting it to the <constant>CANQUE_FILTER</constant>
        ioctl. Filters allow us to filter messages by various criterions. We
        use only filtering by an ID. The <varname>mask</varname> member tells
        which bits of message ID are relevant for filtering and the member
        <varname>id</varname> contains desired ID bit values. Since we need
        only to receive messages with one ID <varname>mask</varname> is set to
        all ones and <varname>id</varname> contains the ID.</para>

        <para>After the filter is set up it is necessary to flush driver
        queues. The reason for this is that in the time between driver opening
        and filter setup, there can be some received messages in the queue,
        which doesn't match the filter criteria. Flushing the queue is done by
        calling <constant>CANQUE_FLUSH</constant> ioctl.</para>

        <programlisting>ret = ioctl(canfd, CANQUE_FLUSH, NULL);
</programlisting>
      </section>

      <section>
        <title>Reading and Writing</title>

        <para>As soon as these operations are done, everything is ready for
        message sending and reception. The message is sent by calling the
        <function>write()</function> function with <type>canmsg_t</type>
        structure as the second parameter. The <type>canmsg_t</type> structure
        should be filled according to the message we wish to send. This
        comprises of a message ID, message data bytes, the length of message
        etc. The structure for the ping message is filled by the following
        commands:</para>

        <programlisting>pingmsg.flags=0;
pingmsg.id=ping_id;
pingmsg.length = option_length;
for (i=0; i &lt; option_length; i++) pingmsg.data[i] = i;
</programlisting>

        <para>Later, the message is sent by:</para>

        <programlisting>ret = write(canfd, &amp;pingmsg, sizeof(pingmsg));</programlisting>

        <para>After the message is sent, the program starts waiting for the
        response message. The <function>select()</function> system call is
        used for this purpose because it allows us to wait with timeout. If
        there is a received message, we can read it from the driver by calling
        <function>read()</function> function.</para>

        <para>Before doing that, it is important to zero
        <varname>flags</varname> field of <type>canmsg_t</type> structure.
        This is due to a feature of the driver. Pavel Pí¹a describes this as
        follows:</para>

        <blockquote>
          <para>Adding "<function>msg.flags=0;</function>" before
          "<function>read()</function>" call is required, because random value
          could trigger RTR read patch in the driver. This obsolete driver
          read mode should be moved to its own IOCTL in future.</para>
        </blockquote>

        <programlisting>/* Read the message */
pongmsg.flags=0;
ret = read(canfd, &amp;pongmsg, sizeof(pongmsg));</programlisting>
      </section>

      <section>
        <title>Closing</title>

        <para>At the end, when it is not needed to work with the driver, it
        should be closed in order to remove all driver resources associated
        with our application. The driver is closed simply by calling
        <function>close()</function>.</para>

        <programlisting>close(canfd);</programlisting>
      </section>
    </section>

    <section>
      <title>Other parts of the application</title>

      <section>
        <title>Lists</title>

        <para>For managing the list of executing threads and their statistics
        a list implementation from Pavel Pí¹a's <productname>uLan
        utils</productname> (ulut) package was used. This framework allows us
        very simple and efficient list handling.</para>

        <para>First, list head should be declared:<programlisting>typedef struct threads {
        ul_list_head_t head;
} threads_t;
</programlisting>Since we don't need any additional data, our list head has
        only one field of the type <type>ul_list_head_t</type>. Next we
        declare a list element:<programlisting>typedef struct thread_data {
        pthread_t tid;
        long int canid;

        int count;
        double mean;            /* mean value of responses */
        double moment2nd;       /* used to compute variance of
                                 * responses */
        int min, max;           /* min/max response times */
        int timeout;            /* number of timeouts */

        ul_list_node_t node;
} thread_data_t;
</programlisting>This structure is used for storing data for every executed
        thread. In the next step we declare functions for list manipulation.
        These functions are created automatically by the
        <function>UL_LIST_CUST_DEC</function> macro.<programlisting>UL_LIST_CUST_DEC(thread_list, threads_t, thread_data_t, head, node);</programlisting>This
        declares some functions whose names start with the
        <constant>thread_list_</constant> prefix. We use two of these, namely
        <function>thread_list_init_head()</function> for list initialization
        and <function>thread_list_ins_tail()</function> for adding elements to
        the list.</para>

        <para>We also use a macro <function>ul_list_for_each()</function>
        (declared in <filename>ul_list.h</filename>) which traverses through
        all the list elements in a loop.</para>
      </section>

      <section>
        <title>Waiting for the thread completion</title>

        <para>After the main thread starts all the communication threads, it
        is necessary to wait for their completion. This is done in
        <function>wait_for_threads()</function>. In the simplest case, waiting
        runs in a while loop and in every iteration is is waited for one
        thread using a <varname>finish_sem</varname> semaphore. After the
        <varname>thread_count</varname> iterations, we are sure all the
        threads finished. Whenever any thread finishes, it increments this
        semaphore by calling <function>sem_post()</function> and this is why
        we can wait for a particular number of threads to finish.</para>

        <para>The simplest case of waiting code looks as
        follows:<programlisting>while (thread_count &gt; 0) {
        ret = sem_wait(&amp;finish_sem);
        if (ret == 0) thread_count--;
}
</programlisting>In the <productname>canping</productname> application we use
        more difficult code because of printing of progress messages during
        waiting.</para>

        <para>Finally, when all the threads are finished, we print summary
        statistics for each thread and free list elements:<programlisting>ul_list_for_each_cut(thread_list, &amp;master_threads, td) {
        print_stats(td);
        free(td);
}
</programlisting></para>
      </section>

      <section>
        <title>Signal handling</title>

        <para>In order to exit <productname>canping</productname> by pressing
        <keycap>Ctrl-C</keycap> (<constant>SIGINT</constant>) or by sending
        other signal such as <constant>SIGTERM</constant> it is necessary to
        write and register a signal handler. The handler is registered
        by:<programlisting>siginterrupt(SIGINT, 1);
signal(SIGINT, term_handler);
siginterrupt(SIGTERM, 1);
signal(SIGTERM, term_handler);
</programlisting>This registers the <function>term_handler</function> function
        as the handler for the <constant>SIGINT</constant> and
        <constant>SIGTERM</constant> signals. The call to the
        <function>siginterrupt()</function> function tells the OS that an
        arrived signal should interrupt currently executed system
        call<footnote>
            <para>The behaviour of signals is different in Linux 2.4 and Linux
            2.6 with NPTL. The call to <function>siginterrupt()</function> is
            necessary in order to get the same behaviour for both 2.4 and
            2.6.</para>
          </footnote>. This is necessary because the master and slave threads
        executes <function>select()</function> or <function>read()</function>
        system call, which cause waiting for external event, which can never
        happen and we want the program to exit even if there is no
        event.</para>

        <para>The signal handler looks as follows:<programlisting>#define NOT_INTERRUPTED_SYSCALL (errno != EINTR &amp;&amp; errno != ERESTART)
#define IS_FINISH_FLAG() (finish_flag)

void term_handler(int signum)
{
        if (!IS_FINISH_FLAG()) {
                finish_flag = 1;
                kill_all_threads(signum);
        }
}
</programlisting>Whenever the main thread receives a signal it sets
        <varname>finish_flag</varname> to prevent recursive call to the
        handler and then sends the same signal to all other threads. The other
        threads receive the signal and execute the handler. Because the
        <varname>finish_flag</varname> is set the handler does nothing. The
        only result of the signal is interruption of currently executed system
        call. As a consequence, the thread exits the send-receive loop and
        executes exit code.</para>

        <para>You can notice the macro <varname>IS_FINISH_FLAG</varname>. This
        macro is defined only for debugging purposes so don't be confused by
        it.</para>
      </section>
    </section>
  </section>

  <section>
    <title>Assignment</title>

    <orderedlist>
      <listitem>
        <para>Create a simple chat application that will send messages over
        the CAN bus. The application will read the characters typed on
        keyboard and send them to the bus. In addition, it will receive CAN
        messages from other nodes on the bus and print then on screen.</para>
      </listitem>

      <listitem>
        <para>Extend the chat application by displaying messages in color
        depending on the ID of sender. For color and screen management use for
        example the <productname>ncurses</productname> library (<ulink
        url="http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/">http://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/</ulink>).</para>
      </listitem>
    </orderedlist>
  </section>
</chapter>