Documentation/driver-api/serial/moxa-smartio.rst

   1 =============================================================
   2 MOXA Smartio/Industio Family Device Driver Installation Guide
   3 =============================================================
   4
   5 .. note::
   6
   7    This file is outdated. It needs some care in order to make it
   8    updated to Kernel 5.0 and upper
   9
  10 Copyright (C) 2008, Moxa Inc.
  11
  12 Date: 01/21/2008
  13
  14 .. Content
  15
  16    1. Introduction
  17    2. System Requirement
  18    3. Installation
  19       3.1 Hardware installation
  20       3.2 Driver files
  21       3.3 Device naming convention
  22       3.4 Module driver configuration
  23       3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x.
  24       3.6 Custom configuration
  25       3.7 Verify driver installation
  26    4. Utilities
  27    5. Setserial
  28    6. Troubleshooting
  29
  30 1. Introduction
  31 ^^^^^^^^^^^^^^^
  32
  33    The Smartio/Industio/UPCI family Linux driver supports following multiport
  34    boards.
  35
  36     - 2 ports multiport board
  37         CP-102U, CP-102UL, CP-102UF
  38         CP-132U-I, CP-132UL,
  39         CP-132, CP-132I, CP132S, CP-132IS,
  40         CI-132, CI-132I, CI-132IS,
  41         (C102H, C102HI, C102HIS, C102P, CP-102, CP-102S)
  42
  43     - 4 ports multiport board
  44         CP-104EL,
  45         CP-104UL, CP-104JU,
  46         CP-134U, CP-134U-I,
  47         C104H/PCI, C104HS/PCI,
  48         CP-114, CP-114I, CP-114S, CP-114IS, CP-114UL,
  49         C104H, C104HS,
  50         CI-104J, CI-104JS,
  51         CI-134, CI-134I, CI-134IS,
  52         (C114HI, CT-114I, C104P),
  53         POS-104UL,
  54         CB-114,
  55         CB-134I
  56
  57     - 8 ports multiport board
  58         CP-118EL, CP-168EL,
  59         CP-118U, CP-168U,
  60         C168H/PCI,
  61         C168H, C168HS,
  62         (C168P),
  63         CB-108
  64
  65    This driver and installation procedure have been developed upon Linux Kernel
  66    2.4.x and 2.6.x. This driver supports Intel x86 hardware platform. In order
  67    to maintain compatibility, this version has also been properly tested with
  68    RedHat, Mandrake, Fedora and S.u.S.E Linux. However, if compatibility problem
  69    occurs, please contact Moxa at support@moxa.com.tw.
  70
  71    In addition to device driver, useful utilities are also provided in this
  72    version. They are:
  73
  74     - msdiag
  75                  Diagnostic program for displaying installed Moxa
  76                  Smartio/Industio boards.
  77     - msmon
  78                  Monitor program to observe data count and line status signals.
  79     - msterm     A simple terminal program which is useful in testing serial
  80                  ports.
  81     - io-irq.exe
  82                  Configuration program to setup ISA boards. Please note that
  83                  this program can only be executed under DOS.
  84
  85    All the drivers and utilities are published in form of source code under
  86    GNU General Public License in this version. Please refer to GNU General
  87    Public License announcement in each source code file for more detail.
  88
  89    In Moxa's Web sites, you may always find latest driver at http://www.moxa.com/.
  90
  91    This version of driver can be installed as Loadable Module (Module driver)
  92    or built-in into kernel (Static driver). You may refer to following
  93    installation procedure for suitable one. Before you install the driver,
  94    please refer to hardware installation procedure in the User's Manual.
  95
  96    We assume the user should be familiar with following documents.
  97
  98    - Serial-HOWTO
  99    - Kernel-HOWTO
 100
 101 2. System Requirement
 102 ^^^^^^^^^^^^^^^^^^^^^
 103
 104    - Hardware platform: Intel x86 machine
 105    - Kernel version: 2.4.x or 2.6.x
 106    - gcc version 2.72 or later
 107    - Maximum 4 boards can be installed in combination
 108
 109 3. Installation
 110 ^^^^^^^^^^^^^^^
 111
 112 3.1 Hardware installation
 113 =========================
 114
 115    There are two types of buses, ISA and PCI, for Smartio/Industio
 116    family multiport board.
 117
 118 ISA board
 119 ---------
 120
 121    You'll have to configure CAP address, I/O address, Interrupt Vector
 122    as well as IRQ before installing this driver. Please refer to hardware
 123    installation procedure in User's Manual before proceed any further.
 124    Please make sure the JP1 is open after the ISA board is set properly.
 125
 126 PCI/UPCI board
 127 --------------
 128
 129    You may need to adjust IRQ usage in BIOS to avoid from IRQ conflict
 130    with other ISA devices. Please refer to hardware installation
 131    procedure in User's Manual in advance.
 132
 133 PCI IRQ Sharing
 134 ---------------
 135
 136    Each port within the same multiport board shares the same IRQ. Up to
 137    4 Moxa Smartio/Industio PCI Family multiport boards can be installed
 138    together on one system and they can share the same IRQ.
 139
 140
 141 3.2 Driver files
 142 ================
 143
 144    The driver file may be obtained from ftp, CD-ROM or floppy disk. The
 145    first step, anyway, is to copy driver file "mxser.tgz" into specified
 146    directory. e.g. /moxa. The execute commands as below::
 147
 148        # cd /
 149        # mkdir moxa
 150        # cd /moxa
 151        # tar xvf /dev/fd0
 152
 153 or::
 154
 155        # cd /
 156        # mkdir moxa
 157        # cd /moxa
 158        # cp /mnt/cdrom/<driver directory>/mxser.tgz .
 159        # tar xvfz mxser.tgz
 160
 161
 162 3.3 Device naming convention
 163 ============================
 164
 165    You may find all the driver and utilities files in /moxa/mxser.
 166    Following installation procedure depends on the model you'd like to
 167    run the driver. If you prefer module driver, please refer to 3.4.
 168    If static driver is required, please refer to 3.5.
 169
 170 Dialin and callout port
 171 -----------------------
 172
 173    This driver remains traditional serial device properties. There are
 174    two special file name for each serial port. One is dial-in port
 175    which is named "ttyMxx". For callout port, the naming convention
 176    is "cumxx".
 177
 178 Device naming when more than 2 boards installed
 179 -----------------------------------------------
 180
 181    Naming convention for each Smartio/Industio multiport board is
 182    pre-defined as below.
 183
 184    ============ ===============       ==============
 185    Board Num.    Dial-in Port         Callout port
 186    1st board    ttyM0  - ttyM7        cum0  - cum7
 187    2nd board    ttyM8  - ttyM15       cum8  - cum15
 188    3rd board    ttyM16 - ttyM23       cum16 - cum23
 189    4th board    ttyM24 - ttym31       cum24 - cum31
 190    ============ ===============       ==============
 191
 192 .. note::
 193
 194    Under Kernel 2.6 and upper, the cum Device is Obsolete. So use ttyM*
 195    device instead.
 196
 197 Board sequence
 198 --------------
 199
 200    This driver will activate ISA boards according to the parameter set
 201    in the driver. After all specified ISA board activated, PCI board
 202    will be installed in the system automatically driven.
 203    Therefore the board number is sorted by the CAP address of ISA boards.
 204    For PCI boards, their sequence will be after ISA boards and C168H/PCI
 205    has higher priority than C104H/PCI boards.
 206
 207 3.4 Module driver configuration
 208 ===============================
 209
 210    Module driver is easiest way to install. If you prefer static driver
 211    installation, please skip this paragraph.
 212
 213
 214    ------------- Prepare to use the MOXA driver --------------------
 215
 216 3.4.1 Create tty device with correct major number
 217 -------------------------------------------------
 218
 219    Before using MOXA driver, your system must have the tty devices
 220    which are created with driver's major number. We offer one shell
 221    script "msmknod" to simplify the procedure.
 222    This step is only needed to be executed once. But you still
 223    need to do this procedure when:
 224
 225    a. You change the driver's major number. Please refer the "3.7"
 226       section.
 227    b. Your total installed MOXA boards number is changed. Maybe you
 228       add/delete one MOXA board.
 229    c. You want to change the tty name. This needs to modify the
 230       shell script "msmknod"
 231
 232    The procedure is::
 233
 234          # cd /moxa/mxser/driver
 235          # ./msmknod
 236
 237    This shell script will require the major number for dial-in
 238    device and callout device to create tty device. You also need
 239    to specify the total installed MOXA board number. Default major
 240    numbers for dial-in device and callout device are 30, 35. If
 241    you need to change to other number, please refer section "3.7"
 242    for more detailed procedure.
 243    Msmknod will delete any special files occupying the same device
 244    naming.
 245
 246 3.4.2 Build the MOXA driver and utilities
 247 -----------------------------------------
 248
 249    Before using the MOXA driver and utilities, you need compile the
 250    all the source code. This step is only need to be executed once.
 251    But you still re-compile the source code if you modify the source
 252    code. For example, if you change the driver's major number (see
 253    "3.7" section), then you need to do this step again.
 254
 255    Find "Makefile" in /moxa/mxser, then run
 256
 257          # make clean; make install
 258
 259    ..note::
 260
 261          For Red Hat 9, Red Hat Enterprise Linux AS3/ES3/WS3 & Fedora Core1:
 262          # make clean; make installsp1
 263
 264          For Red Hat Enterprise Linux AS4/ES4/WS4:
 265          # make clean; make installsp2
 266
 267    The driver files "mxser.o" and utilities will be properly compiled
 268    and copied to system directories respectively.
 269
 270 ------------- Load MOXA driver--------------------
 271
 272 3.4.3 Load the MOXA driver
 273 --------------------------
 274
 275    ::
 276
 277          # modprobe mxser <argument>
 278
 279    will activate the module driver. You may run "lsmod" to check
 280    if "mxser" is activated. If the MOXA board is ISA board, the
 281    <argument> is needed. Please refer to section "3.4.5" for more
 282    information.
 283
 284 ------------- Load MOXA driver on boot --------------------
 285
 286 3.4.4 Load the mxser driver
 287 ---------------------------
 288
 289
 290    For the above description, you may manually execute
 291    "modprobe mxser" to activate this driver and run
 292    "rmmod mxser" to remove it.
 293
 294    However, it's better to have a boot time configuration to
 295    eliminate manual operation. Boot time configuration can be
 296    achieved by rc file. We offer one "rc.mxser" file to simplify
 297    the procedure under "moxa/mxser/driver".
 298
 299    But if you use ISA board, please modify the "modprobe ..." command
 300    to add the argument (see "3.4.5" section). After modifying the
 301    rc.mxser, please try to execute "/moxa/mxser/driver/rc.mxser"
 302    manually to make sure the modification is ok. If any error
 303    encountered, please try to modify again. If the modification is
 304    completed, follow the below step.
 305
 306    Run following command for setting rc files::
 307
 308          # cd /moxa/mxser/driver
 309          # cp ./rc.mxser /etc/rc.d
 310          # cd /etc/rc.d
 311
 312    Check "rc.serial" is existed or not. If "rc.serial" doesn't exist,
 313    create it by vi, run "chmod 755 rc.serial" to change the permission.
 314
 315    Add "/etc/rc.d/rc.mxser" in last line.
 316
 317    Reboot and check if moxa.o activated by "lsmod" command.
 318
 319 3.4.5. specify CAP address
 320 --------------------------
 321
 322    If you'd like to drive Smartio/Industio ISA boards in the system,
 323    you'll have to add parameter to specify CAP address of given
 324    board while activating "mxser.o". The format for parameters are
 325    as follows.::
 326
 327            modprobe mxser ioaddr=0x???,0x???,0x???,0x???
 328                                   |  |  |    |
 329                                   |  |  |    +- 4th ISA board
 330                                   |  |  +------ 3rd ISA board
 331                                   |  +------------ 2nd ISA board
 332                                   +-------------------1st ISA board
 333
 334 3.5 Static driver configuration for Linux kernel 2.4.x and 2.6.x
 335 ================================================================
 336
 337     Note:
 338           To use static driver, you must install the linux kernel
 339           source package.
 340
 341 3.5.1 Backup the built-in driver in the kernel
 342 ----------------------------------------------
 343
 344     ::
 345
 346        # cd /usr/src/linux/drivers/char
 347        # mv mxser.c mxser.c.old
 348
 349        For Red Hat 7.x user, you need to create link:
 350        # cd /usr/src
 351        # ln -s linux-2.4 linux
 352
 353 3.5.2 Create link
 354 -----------------
 355     ::
 356
 357           # cd /usr/src/linux/drivers/char
 358           # ln -s /moxa/mxser/driver/mxser.c mxser.c
 359
 360 3.5.3 Add CAP address list for ISA boards.
 361 ------------------------------------------
 362
 363     For PCI boards user, please skip this step.
 364
 365     In module mode, the CAP address for ISA board is given by
 366     parameter. In static driver configuration, you'll have to
 367     assign it within driver's source code. If you will not
 368     install any ISA boards, you may skip to next portion.
 369     The instructions to modify driver source code are as
 370     below.
 371
 372     a. run::
 373
 374         # cd /moxa/mxser/driver
 375         # vi mxser.c
 376
 377     b. Find the array mxserBoardCAP[] as below::
 378
 379           static int mxserBoardCAP[] = {0x00, 0x00, 0x00, 0x00};
 380
 381     c. Change the address within this array using vi. For
 382        example, to driver 2 ISA boards with CAP address
 383        0x280 and 0x180 as 1st and 2nd board. Just to change
 384        the source code as follows::
 385
 386           static int mxserBoardCAP[] = {0x280, 0x180, 0x00, 0x00};
 387
 388 3.5.4 Setup kernel configuration
 389 --------------------------------
 390
 391     Configure the kernel::
 392
 393       # cd /usr/src/linux
 394       # make menuconfig
 395
 396     You will go into a menu-driven system. Please select [Character
 397     devices][Non-standard serial port support], enable the [Moxa
 398     SmartIO support] driver with "[*]" for built-in (not "[M]"), then
 399     select [Exit] to exit this program.
 400
 401 3.5.5 Rebuild kernel
 402 --------------------
 403
 404     The following are for Linux kernel rebuilding, for your
 405     reference only.
 406
 407     For appropriate details, please refer to the Linux document:
 408
 409         a. Run the following commands::
 410
 411              cd /usr/src/linux
 412              make clean              # take a few minutes
 413              make dep                # take a few minutes
 414              make bzImage            # take probably 10-20 minutes
 415              make install            # copy boot image to correct position
 416
 417         f. Please make sure the boot kernel (vmlinuz) is in the
 418            correct position.
 419         g. If you use 'lilo' utility, you should check /etc/lilo.conf
 420            'image' item specified the path which is the 'vmlinuz' path,
 421            or you will load wrong (or old) boot kernel image (vmlinuz).
 422            After checking /etc/lilo.conf, please run "lilo".
 423
 424           Note that if the result of "make bzImage" is ERROR, then you have to
 425           go back to Linux configuration Setup. Type "make menuconfig" in
 426           directory /usr/src/linux.
 427
 428
 429 3.5.6 Make tty device and special file
 430 --------------------------------------
 431
 432     ::
 433        # cd /moxa/mxser/driver
 434        # ./msmknod
 435
 436 3.5.7 Make utility
 437 ------------------
 438
 439     ::
 440
 441           # cd /moxa/mxser/utility
 442           # make clean; make install
 443
 444 3.5.8 Reboot
 445 ------------
 446
 447
 448
 449 3.6 Custom configuration
 450 ========================
 451
 452     Although this driver already provides you default configuration, you
 453     still can change the device name and major number. The instruction to
 454     change these parameters are shown as below.
 455
 456 a. Change Device name
 457
 458     If you'd like to use other device names instead of default naming
 459     convention, all you have to do is to modify the internal code
 460     within the shell script "msmknod". First, you have to open "msmknod"
 461     by vi. Locate each line contains "ttyM" and "cum" and change them
 462     to the device name you desired. "msmknod" creates the device names
 463     you need next time executed.
 464
 465 b. Change Major number
 466
 467     If major number 30 and 35 had been occupied, you may have to select
 468     2 free major numbers for this driver. There are 3 steps to change
 469     major numbers.
 470
 471 3.6.1 Find free major numbers
 472 -----------------------------
 473
 474     In /proc/devices, you may find all the major numbers occupied
 475     in the system. Please select 2 major numbers that are available.
 476     e.g. 40, 45.
 477
 478 3.6.2 Create special files
 479 --------------------------
 480
 481    Run /moxa/mxser/driver/msmknod to create special files with
 482    specified major numbers.
 483
 484 3.6.3 Modify driver with new major number
 485 -----------------------------------------
 486
 487    Run vi to open /moxa/mxser/driver/mxser.c. Locate the line
 488    contains "MXSERMAJOR". Change the content as below::
 489
 490           #define         MXSERMAJOR              40
 491           #define         MXSERCUMAJOR            45
 492
 493     3.6.4 Run "make clean; make install" in /moxa/mxser/driver.
 494
 495 3.7 Verify driver installation
 496 ==============================
 497
 498     You may refer to /var/log/messages to check the latest status
 499     log reported by this driver whenever it's activated.
 500
 501 4. Utilities
 502 ^^^^^^^^^^^^
 503
 504    There are 3 utilities contained in this driver. They are msdiag, msmon and
 505    msterm. These 3 utilities are released in form of source code. They should
 506    be compiled into executable file and copied into /usr/bin.
 507
 508    Before using these utilities, please load driver (refer 3.4 & 3.5) and
 509    make sure you had run the "msmknod" utility.
 510
 511 msdiag - Diagnostic
 512 ===================
 513
 514    This utility provides the function to display what Moxa Smartio/Industio
 515    board found by driver in the system.
 516
 517 msmon - Port Monitoring
 518 =======================
 519
 520    This utility gives the user a quick view about all the MOXA ports'
 521    activities. One can easily learn each port's total received/transmitted
 522    (Rx/Tx) character count since the time when the monitoring is started.
 523
 524    Rx/Tx throughputs per second are also reported in interval basis (e.g.
 525    the last 5 seconds) and in average basis (since the time the monitoring
 526    is started). You can reset all ports' count by <HOME> key. <+> <->
 527    (plus/minus) keys to change the displaying time interval. Press <ENTER>
 528    on the port, that cursor stay, to view the port's communication
 529    parameters, signal status, and input/output queue.
 530
 531 msterm - Terminal Emulation
 532 ===========================
 533
 534    This utility provides data sending and receiving ability of all tty ports,
 535    especially for MOXA ports. It is quite useful for testing simple
 536    application, for example, sending AT command to a modem connected to the
 537    port or used as a terminal for login purpose. Note that this is only a
 538    dumb terminal emulation without handling full screen operation.
 539
 540 5. Setserial
 541 ^^^^^^^^^^^^
 542
 543    Supported Setserial parameters are listed as below.
 544
 545    ============== =========================================================
 546    uart           set UART type(16450-->disable FIFO, 16550A-->enable FIFO)
 547    close_delay    set the amount of time(in 1/100 of a second) that DTR
 548                   should be kept low while being closed.
 549    closing_wait   set the amount of time(in 1/100 of a second) that the
 550                   serial port should wait for data to be drained while
 551                   being closed, before the receiver is disable.
 552    spd_hi         Use  57.6kb  when  the application requests 38.4kb.
 553    spd_vhi        Use  115.2kb  when  the application requests 38.4kb.
 554    spd_shi        Use  230.4kb  when  the application requests 38.4kb.
 555    spd_warp       Use  460.8kb  when  the application requests 38.4kb.
 556    spd_normal     Use  38.4kb  when  the application requests 38.4kb.
 557    spd_cust       Use  the custom divisor to set the speed when  the
 558                   application requests 38.4kb.
 559    divisor        This option set the custom division.
 560    baud_base      This option set the base baud rate.
 561    ============== =========================================================
 562
 563 6. Troubleshooting
 564 ^^^^^^^^^^^^^^^^^^
 565
 566    The boot time error messages and solutions are stated as clearly as
 567    possible. If all the possible solutions fail, please contact our technical
 568    support team to get more help.
 569
 570
 571    Error msg:
 572               More than 4 Moxa Smartio/Industio family boards found. Fifth board
 573               and after are ignored.
 574
 575    Solution:
 576    To avoid this problem, please unplug fifth and after board, because Moxa
 577    driver supports up to 4 boards.
 578
 579    Error msg:
 580               Request_irq fail, IRQ(?) may be conflict with another device.
 581
 582    Solution:
 583    Other PCI or ISA devices occupy the assigned IRQ. If you are not sure
 584    which device causes the situation, please check /proc/interrupts to find
 585    free IRQ and simply change another free IRQ for Moxa board.
 586
 587    Error msg:
 588               Board #: C1xx Series(CAP=xxx) interrupt number invalid.
 589
 590    Solution:
 591    Each port within the same multiport board shares the same IRQ. Please set
 592    one IRQ (IRQ doesn't equal to zero) for one Moxa board.
 593
 594    Error msg:
 595               No interrupt vector be set for Moxa ISA board(CAP=xxx).
 596
 597    Solution:
 598    Moxa ISA board needs an interrupt vector.Please refer to user's manual
 599    "Hardware Installation" chapter to set interrupt vector.
 600
 601    Error msg:
 602               Couldn't install MOXA Smartio/Industio family driver!
 603
 604    Solution:
 605    Load Moxa driver fail, the major number may conflict with other devices.
 606    Please refer to previous section 3.7 to change a free major number for
 607    Moxa driver.
 608
 609    Error msg:
 610               Couldn't install MOXA Smartio/Industio family callout driver!
 611
 612    Solution:
 613    Load Moxa callout driver fail, the callout device major number may
 614    conflict with other devices. Please refer to previous section 3.7 to
 615    change a free callout device major number for Moxa driver.