=============================================================================
          MOXA CAN Family Device Driver Installation Guide
          for Linux Kernel 5.x
          Copyright (C) 2012, Moxa Inc.
=============================================================================
Date: 12/18/2025

Content

1. Introduction
2. System Requirements
3. Installation
   3.1 Hardware Installation
   3.2 Driver Files   
   3.3 Device Naming Convention
   3.4 Module Driver Configuration
4. CAN Interface Operation
   4.1 Displaying the CAN Interfaces
   4.2 Setting Bitrate
   4.3 Setting the CAN Interfaces Up or Down 
   4.4 Restarting from Bus-Off State
   4.5 The procfs Directory
5. Utilities and Test Procedure
   5.1 Utilities
   5.2 Test Procedure
   5.3 Examples
6. Troubleshooting
   6.1 Unable to restart the CAN interface

-----------------------------------------------------------------------------
1. Introduction

   The CAN family Linux driver supports the following CAN boards:

   - 2-port CAN boards:
     CP-602E-FPGA, CP-602U-FPGA, CB-602-FPGA, CP-602E-I, CP-602U-I, CB-602I

   This driver and installation procedure have been developed on Linux Kernel
   6.x. This driver supports Intel x86/x64 hardware platforms. In order 
   to maintain compatibility, this version has also been properly tested with 
   Ubuntu Linux. However, if compatibility problem occurs, please contact Moxa
   at support@moxa.com.

   All the drivers are published in the form of source code under the GNU General
   Public License in this version. Please refer to the GNU General Public License
   announcement in each source code file for more details.

   Visit www.moxa.com to download the latest driver. 

   This version of driver can be installed as loadable module (module driver).
   Before you install the driver, please refer to the hardware installation
   procedure in the User's Manual.

   The user should be familiar with the following documents:
   - Linux SocketCAN
   - Kernel-HOWTO

-----------------------------------------------------------------------------
2. System Requirements
   - Hardware platform: Intel x86/x64 machine
   - Kernel version: 5.x
   - GCC version 4.6.1 or later

-----------------------------------------------------------------------------
3. Installation

   3.1 Hardware Installation

       PCI IRQ Sharing
       -----------
       Each port within the same multiport board shares the same IRQ. Up to
       four Moxa CAN PCI family boards can be installed together on one system
       and share the same IRQ.


   3.2 Driver Files

       The driver file may be obtained from the CD-ROM or website. The first step
       is to copy the driver file "driv_linux_CAN_vx.x_build_yymmddhh.tgz"
       into the specified directory, e.g. /moxa. Follow the executed commands below.

       # cd /
       # mkdir moxa
       # cd /moxa
       # cp /mnt/cdrom/<driver directory>/driv_linux_CAN_vx.x_build_yymmddhh.tgz ./
       # tar -xvzf driv_linux_CAN_vx.x_build_yymmddhh.tgz

       Note: xx=version, yy=year, mm=month, dd=day, hh=hour 

   3.3 Device Naming Convention

       Device naming rule
       -----------------------------------------------
       The following is the naming convention for CAN boards as assigned by system:

       Board Num.    Interface Name 
       1st board     can0, can1
       2nd board     can2, can3
       3rd board     can4, can5
       4th board     can6, can7       

       You will find all the driver files in /moxa/mxcan. The following installation
       procedure depends on the model you'd like to run the driver.

       
   3.4 Module Driver Configuration

       ------------- Preparing to Use the MOXA Driver -------------------- 
 
       3.4.1 Building the MOXA Driver
          
             Before using the MOXA driver, you will need to compile all the source
             code. This step needs to be executed only once.
             However, if you modify the source code, you will need to recompile the
             source code, and perform this step again.
                    
             Find "Makefile" in /moxa/mxcan, then run

             # make;

       3.4.2 Installing the MOXA Driver
          
             To install the MOXA driver, you have to execute the command below
             in /moxa/mxcan directory. The driver will then be installed in the system
             directory.

             # make install

       ------------- Loading the MOXA Driver --------------------  

       3.4.3 To load the MOXA driver, execute the command below.  
             
             a. For CP-602E-I, CP-602U-I, CB-602I:
             # modprobe mxcandrv

             This command will activate the module driver. You may run "lsmod" to
             check if "mxcandrv" is activated.

             b. For CP-602E-FPGA, CP-602U-FPGA, CB-602-FPGA:
             # modprobe mxcanctrl
             # modprobe mxcandrv2

             This command will activate the module driver. You may run "lsmod" to
             check if "mxcanctrl" and "mxcandrv2" are activated.

             To simplify the processes above, we provided a single step to build, 
             install, and load the MOXA driver. You may execute the ./mxinstall in
             /moxa/mxcan to start using the product.

             # ./mxinstall

       ------------- Loading the MOXA Driver on Boot --------------------  

       3.4.4 From the above description, you may manually execute
             "modprobe mxcandrv" to activate this driver and run "rmmod mxcandrv"
             to remove it. However, it is better to have a boot time configuration
             to eliminate manual operation. Boot time configuration may differ
             with each distribution. The following steps may apply to common
             distributions: 
          
             # vi /etc/modules.conf 
              or
             # vi /etc/modules

             a. For CP-602E-I, CP-602U-I, CB-602I, append the following line to the 
                file.
             
                mxcandrv

                Reboot and check if mxcandrv has been activated by the "lsmod" command.

             b. For CP-602E-FPGA, CP-602U-FPGA, CB-602-FPGA, append the following 
                lines to the file.
             
                mxcanctrl
                mxcandrv2

                Reboot and check if mxcanctrl and mxcandrv2 have been activated by the 
                "lsmod" command.

       ------------- Unloading the MOXA Driver Manually -------------------- 

       3.4.5 Execute the command below to unload the MOXA driver manually

             a. For CP-602E-I, CP-602U-I, CB-602I:
                # modprobe -r mxcandrv

             b. For CP-602E-FPGA, CP-602U-FPGA, CB-602-FPGA:
                # modprobe -r mxcandrv2
                # modprobe -r mxcanctrl

             This command will deactivate the module driver. You may run "lsmod" to 
             check if "mxcandrv", "mxcandrv2" and "mxcanctrl" are deactivated or not. 
             If the driver is marked as a permanent driver, it means the kernel 
             prevented dynamic unload of modules.
             Please refer to kernel documents for detailed information.

       ------------- Cleaning the MOXA Driver -------------------- 

       3.4.6 Execute the command below to clean the files.

             # make clean

       ------------- Uninstalling the MOXA Driver and Utilities --------------------

       3.4.7 The MOXA driver and utilities will be removed from the system
             respectively after executing the command below in /moxa/mxcan.

             # make uninstall

             If the driver is marked as a permanent driver, reboot the system to
             remove the driver from memory.


-----------------------------------------------------------------------------
4. CAN Interface Operation

   4.1 Displaying the CAN Interfaces

       To display all network interfaces, including CAN interfaces:

           # ip link show

       If a CAN interface is not yet enabled, you may see an output similar to:

           canX: <NOARP,DOWN> mtu 16 qdisc noop state DOWN ...

   4.2 Setting Bitrate and CAN FD Configuration

       a. Setting Classic CAN Bitrate (e.g., 50,000 bit/s)

           # ip link set canX type can bitrate 50000

       b. Enabling CAN FD (including Data Phase Bitrate)

           # ip link set canX type can fd on bitrate 500000 dbitrate 2000000

       Parameter description:
       - bitrate  : Arbitration Phase bitrate
       - dbitrate : Data Phase bitrate (CAN FD only)
       - fd on/off: Enable or disable CAN FD mode

       If the underlying driver supports CAN FD, CAN FD frames (up to
       64 bytes) can be transmitted and received.

   4.3 Setting the CAN Interfaces Up or Down

       a. Bring the interface up (required for TX/RX operation):

           # ip link set canX up

       b. Bring the interface down (typically for changing settings):

           # ip link set canX down

   4.4 Restarting from Bus-Off State

       When excessive errors occur, the CAN controller may enter the
       BUS-OFF state.

       a. Automatically recover from BUS-OFF (value in milliseconds):

           # ip link set canX type can restart-ms 100

       b. Manually restart the interface:

           # ip link set canX type can restart

       Note: A manual restart will generate a CAN error frame. This is
       expected behavior.

   4.5 The procfs Directory

       SocketCAN provides internal information under `/proc/net/can`.
       These entries are created by the CAN core, not by individual drivers.

           # ls /proc/net/can

       Common files include:

       rcvlist_all - list of all sockets without filters
       rcvlist_eff - sockets subscribed to Extended Frame Format (EFF)
       rcvlist_sff - sockets subscribed to Standard Frame Format (SFF)
       rcvlist_err - sockets subscribed to CAN error frames
       rcvlist_fil - mask/value filter list
       rcvlist_inv - inverse-semantics filter list

       Additional files:

       stats       - SocketCAN core statistics
       reset_stats - manually reset SocketCAN core statistics
       version     - show the SocketCAN core version and CAN ABI version

       In Linux Kernel 6.x, these files are created automatically when the
       CAN core modules are loaded. Manual `modprobe can` is usually not
       required.


-----------------------------------------------------------------------------
5. Utilities and Test Procedure

       The `can-utils` package provides a commonly used set of SocketCAN
       user-space tools for testing CAN and CAN FD interfaces.

       Project repository (official):
           https://github.com/linux-can/can-utils

       To build `can-utils`, ensure that the required dependencies (including
       libsocketcan) are installed on your system. Most modern Linux
       distributions already include pre-built packages:

           Debian / Ubuntu:
               # apt install can-utils

           Fedora:
               # dnf install can-utils

       Common utilities include:

       cansend    - send Classic CAN or CAN FD frames
       candump    - display CAN/CAN FD frames in real time
       canfdtest  - FD-specific test tool (loopback and throughput tests)
       cangen     - generate CAN/CAN FD traffic at configurable rates
       canbusload - estimate CAN/CAN FD bus load
       can-calc-bit-timing - calculate timing parameters for supported controllers

   5.2 Test Procedure

       The following example demonstrates how to test a dual-port CAN / CAN FD card
       after the driver has been successfully loaded.

       ### Load the driver

           # modprobe mxcandrv   (or your device driver name)

       ### Configure bitrate or CAN FD mode

       Classic CAN example:
           # ip link set can0 type can bitrate 50000
           # ip link set can1 type can bitrate 50000

       CAN FD example:
           # ip link set can0 type can fd on bitrate 500000 dbitrate 2000000
           # ip link set can1 type can fd on bitrate 500000 dbitrate 2000000

       ### Bring both interfaces up

           # ip link set can0 up
           # ip link set can1 up

       ### Start receiving on can0

           # candump can0

       ### Loopback test (physically connect can0 ↔ can1), then in another terminal:

       Classic CAN frame:
           # cansend can1 123#010203

       CAN FD frame (example: 64-byte payload):
           # cansend can1 123##020000000102030405060708090A0B0C0D0E0F \
                            101112131415161718191A1B1C1D1E1F202122232425262728292A2B2C2D2E2F

       The receiving terminal (`candump can0`) will show output similar to:

           can0  123   [3]  01 02 03

       Or for CAN FD:

           can0  123   [64]  02 00 00 00 01 02 03 ... <remaining 58 bytes>

   5.3 Examples

       User may handle the CAN bus raw data by program. There are some examples
       in /moxa/mxcan/utility/examples. However the Moxa CAN bus driver is based on
       SocketCAN technology. User may refer to the Linux source document for
       detailed information. (linux/Documentation/networking/can.txt)      

-----------------------------------------------------------------------------
6. Troubleshooting

   6.1 Unable to restart the CAN interface

       If the CAN bus status is not in bus-off, the driver will not restart the
       interface. Check the bus state with the following command.

       # ip -detail link show can0

       3: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc pfifo_fast state UNKNOWN
          qlen 10 link/can
          can state BUS-OFF (berr-counter tx 0 rx 0) restart-ms 0
          ^^^^^^^^^^^^^^^^^
   
