xr17-lnx2.6.32-and-newer-pak_ver2.6/readme

=============================================================================

        MaxLinear PCIe Multiport Device Driver Ver 2.6 Installation Guide
         for Linux Kernel 2.6.32 and newer (Tested on various kernels from 2.6.32 to 4.15.x)
			Copyright (C) 2019, MaxLinear.
=============================================================================

Note: Exar is now part of MaxLinear. All description below will be referred as MaxLinear/Exar.

Revision History
----------------
Changes from Ver 2.5 to 2.6
- Ensure LCR bit-7 = 0 when accessing RHR/THR/IER/ISR to avoid incorrect register write.
- Remove warning messages when building with gcc 7.4.0 (Ubuntu 18.04).

Changes from Ver 2.4 to 2.5
- Improve baud the accuracy on 12Mbps.
- Add option to  select for RS485 control between DTR# and RTS# pin. 
- Add timer function patch for Kernel 4.15 and later support

Changes from Ver 2.3 to 2.4
- Add INT0 read for "nobody cares" interrupt issue

Releasing 2.2c as version 2.3 (no changes from 2.2c)

Changes from Ver 2.2b to 2.2c
- Macro XR_17v35x_UART_RHR was not defined. Issue fixed.

Changes from Ver 2.2a to 2.2b
- RS-485 was not getting disabled correctly. Issue Fixed. 
 
Changes from Ver 2.2 to 2.2a
- For receiving data, replaced memcpy_fromio() routine with serial_in(). This was done because the former was dropping data on receive. 

Changes from Ver 2.1 to 2.2
- Added support for non standard baud rates
- Configure MPIO's as inputs.
- Added a parameter to enable disable internal loopback
- Fixed bug related to Fractional buad rate generator.
- RS485 disabled by default. 
- To enable RS485 configure the parameter ENABLE_RS485

Changes from Ver 2.0 to 2.1
- Added support for Software flow control and Auto Hardware flow control
- Enabled Auto RS 485
- Modified logic for  Fractional baud rate generator
- Added Support for XR17D15x devices

Changes from Ver 1.5 to 2.0 (version 1.6 - 1.9 are unofficial versions, never posted on website):
- Fixed issue when un-registering ports (rmmod) that prevented re-registering all of the ports (insmod)
- Added logic in interrupt service to ensure that LCR bit-7 = 0 before reading ISR/IIR
- Added support for 4X Sampling Mode, 8X Sampling Mode, 9-bit (Multidrop) Mode, RS-485 Mode
- Added support for 2.6.32 to 3.17.x (and possibly newer)

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

   The PCIe Multiport serial driver Ver 2.2, supports the following multiport
   boards.

      - XR17V258 PCI Multiport (8 Channels) Boards
      - XR17V254 PCI Multiport (4 Channels) Boards
      - XR17V252 PCI Multiport (2 Channels) Boards
	- XR17V358 & XR17V4354 PCIe Multiport (8 Channels) Boards
      - XR17V354 PCIe Multiport (4 Channels) Boards
      - XR17V352 PCIe Multiport (2 Channels) Boards
      - XR17V4358 & XR17V8354 PCIe Multiport (12 Channels) Boards
      - XR17V8358 PCIe Multiport (16 Channels) Boards

   This driver and installation procedure have been tested on various
   kernel versions from 2.6.32 to 3.17.x.

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

   This version of driver can be installed as Loadable Module (Module driver)
   or built-in into kernel (Static driver). You may refer to following
   installation procedure for suitable one. Before you install the driver,
   please refer to hardware installation procedure in the User's Manual.

   We assume the user should be familiar with following documents.
   - Serial-HOWTO
   - Kernel-HOWTO

-----------------------------------------------------------------------------
2. System Requirement
   - Hardware platform: Intel x86
   - Kernel version: 2.6.32 or newer
   - Maximum of 256 ports can be installed in any PCIe board combination
   - This driver has been tested on various kernel versions from 2.6.32 to 3.17.x.  
     It is strongly recommended that the user do a complete install of all components
     to ensure that this driver works correctly.

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

   3.1 Hardware installation
      
      You may need to adjust IRQ usage in BIOS to avoid IRQ conflict with legacy ISA devices. 

   3.2 Driver Installation
	  For all the newer kernels the support for MaxLinear/Exar PCI/PCIe UARTs is already integrated in the generic 
	  serial drivers that comes with the kernel source. If you want to use the XR17V35x/XR17D15x PCIe/PCI 
	  UARTs to only send/receive data then you may use the generic serial driver available in the linux 
	  kernel. When using generic driver the XR17V35x device will be listed as "ttyS" instead of "ttyXR" 
	  under /dev/ folder. In order to determine which "ttyS" are assigned to XR17V35x you can open file 
	  "/proc/tty/driver/serial" the PCI/PCIe UARTs will be listed as MMIO devices.
	  However, if you intend to use the Enhanced features of the device(i.e. Auto RTS/CTS, Auto RS485 etc)
	  or enable disable MPIO, in that case you will need the custom driver. Follow the steps below for using
	  the custom driver, in this example we will be using XR17V358: 
	  (MaxLinear/Exar AN-225 Application Note can be referred for installing custom driver)

	  A.) You will need to unbind the serial driver. Follow the steps below to unbind the serial driver. 

		root$ lspci -vd 13a8:*
		03:00.0 Serial controller: Exar Corp. Device 0358 (rev 03) (prog-if 02 [16550])
		Flags: fast devsel, IRQ 30
		Memory at f3ffc000 (32-bit, non-prefetchable) [size=16K]
		Capabilities: [50] MSI: Enable- Count=1/1 Maskable- 64bit+
		Capabilities: [78] Power Management version 3
		Capabilities: [80] Express Endpoint, MSI 01
		Capabilities: [100] Virtual Channel
		Kernel driver in use: serial

		As you can see in the last line above that the kernel is using generic "serial" module. 
		Note: For newer kernel (i.e.: 4.11 and later), "exar_serial" may be seen. 
		      If so, use "exar_serial" instead of "serial" for the following unbind commands

		root$ ls /sys/bus/pci/drivers/serial/
		0000:03:00.0 bind new_id remove_id uevent unbind
		root$ echo -n "0000:03:00.0" > /sys/bus/pci/drivers/serial/unbind

		This will unbind the generic serial driver from XR17V35x device. Now you can compile and install 
		the customer driver. After successful installation the device should be listed in /dev folder as 
		"ttyXR" as mentioned in the README.
	
	  B.) Module driver configuration
       
		1. Find "Makefile" in driver source file path, then run
			  # make
		  
		   After the driver file "xr17v35x.ko" is properly compiled, then run
			  # insmod xr17v35x.ko
				or				
			  # insmod ./xr17v35x.ko

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

		2. This module registers MaxLinear/Exar ports as "/dev/ttyXR0", "/dev/ttyXR1", etc. You may use "minicom" or
		   its custom serial application to test the ports
   
		3. You may refer to /var/log/messages or /var/log/kern.log to check the latest status log reported 
		   by this driver whenever activated to verify driver installation.

	  C.) Driver files and device naming convention

		This driver creates traditional serial device names, "/dev/ttyXR0" onwards.

        Device naming when multiple boards are installed
        -----------------------------------------------
        Naming convention for each multiport board is pre-defined as below, assuming 2 XR17V358 boards, 
		1 XR17V354 board and 1 XR17V352 board.

        Board Num.	 Port Name
        1st board (358)	ttyXR0  - ttyXR7
        2nd board (358)	ttyXR8  - ttyXR15
        3rd board (354)	ttyXR16 - ttyXR19
        4th board (352)	ttyXR24 - ttyXR25
 
4. Troubleshooting

   The boot time error mesages and solutions are stated as clearly as
   possible. If all the possible solutions fail, please contact our technical
   support team (uarttechsupport@exar.com) to get more help.