Provided by: linuxcnc-uspace_2.9.0~pre1+git20230208.f1270d6ed7-1_amd64 bug

NAME

       hm2_eth  -  LinuxCNC HAL driver for the Mesa Electronics Ethernet Anything IO boards, with
       HostMot2 firmware.

SYNOPSIS

       loadrt hm2_eth [config="str[,str...]"] [board_ip=ip[,ip...]] [board_mac=mac[,mac...]]

           config [default: ""]
                  HostMot2 config strings, described in the hostmot2(9) manpage.

           board_ip [default: ""]
                  The IP address of the board(s), separated by commas.   As  shipped,  the  board
                  address is 192.168.1.121.

DESCRIPTION

       hm2_eth is a device driver that interfaces Mesa's ethernet based Anything I/O boards (with
       the HostMot2 firmware) to the LinuxCNC HAL.  The  supported  boards  are:  7I76E,  7I80DB,
       7I80HD, 7I92, 7I93, 7I94, 7I95, 7I96, 7I96S, 7I97, 7I98.  The board must have its firmware
       loaded on the board by the mesaflash(1) program.

       hm2_eth is only available when LinuxCNC is configured with "uspace" realtime.

INTERFACE CONFIGURATION

       hm2_eth should be used on a dedicated network interface, with only a cable between the  PC
       and the board.  Wireless and USB network interfaces are not suitable.

       These  instructions  assume your dedicated network interface is "eth1", 192.168.1/24 is an
       unused private  network,  that  the  hostmot2  board  is  using  the  default  address  of
       192.168.1.121,  that  you are using Debian 7 or similar, and that you do not otherwise use
       iptables.  If  any  of  these  are  false,  you  will  need  to  modify  the  instructions
       accordingly.   After  following  all  the  instructions,  reboot  so that the changes take
       effect.

       It is particularly important to check that the network 192.168.1/24  is  not  already  the
       private  network  used by your internet router, because this is a commonly-used value.  If
       you use another network, you will also need to reconfigure the hostmot2 card to use an  IP
       address  on  that  network  by  using the mesaflash(1) utility and change jumper settings.
       Typically, you will choose one  of  the  networks  in  the  Private  IPv4  address  space.
       ⟨http://en.wikipedia.org/wiki/IPv4#Private_networks⟩  One common alternative is PC address
       10.10.10.1, hostmot2 address 10.10.10.10.

       Use of the dedicated ethernet interface while LinuxCNC is running can cause  violation  of
       realtime  guarantees.   hm2_eth  will  automatically  mitigate  most  accidental causes of
       interference.

   Configure network with static address
       Add these lines to the file  /etc/network/interfaces  to  configure  eth1  with  a  static
       address:

       auto eth1
       iface eth1 inet static
           address 192.168.1.1
           hardware-irq-coalesce-rx-usecs 0

PACKET LOSS

       While  ethernet  is  fairly resistant to electrical noise, many systems will not have 100%
       perfect packet reception.  The hm2_eth driver has a limited  ability  to  deal  with  lost
       packets.   Packet  loss is detected by transmitting an expected read or write packet count
       with each request, and checking the value with each read response.  When a lost packet  is
       detected,  the  packet-error  pin is asserted in that cycle, the packet-error-level pin is
       increased, and if it reaches a threshold then a permanent low-level I/O error is signaled.

       However, not all hm2 special functions know how to properly  recover  from  lost  packets.
       For instance, the encoder special function does not properly manage the index feature when
       packets are lost.  The author believes that this can lead to  rare  failures  in  home-to-
       index, which can have severe consequences.

       On the other hand, pid-stepper systems will run properly for extended periods of time with
       packet loss on the order of .01%, as long as following  error  is  increased  enough  that
       having  stale  position  feedback  does  not  trigger a following error.  Altering the HAL
       configuration so that during transient packet loss the pid and motion  feedback  value  is
       equal  to  the  command  value,  instead  of  the stale feedback value, appears to improve
       tuning.  This can be accomplished with a mux2(9) component for each feedback signal, using
       packet-error as the mux2 sel input.

PINS

       In addition to the pins documented in hostmot2(9), hm2_eth(9) creates additional pins:

       (bit, out) hm2_<BoardType>.<BoardNum>.packet-error
              This  pin  is  TRUE  when the most recent cycle detected a read or write error, and
              FALSE at other times.

       (s32, out) hm2_<BoardType>.<BoardNum>.packet-error-level
              This pin shows the current error level, with higher numbers  indicating  a  greater
              number of recent detected errors.  The error level is always in the range from 0 to
              packet-error-limit, inclusive.

       (bit, out) hm2_<BoardType>.<BoardNum>.packet-error-exceeded
              This pin is TRUE when the current error level is equal to the maximum, and FALSE at
              other times.

PARAMETERS

       In  addition  to  the  parameters documented in hostmot2(9), hm2_eth(9) creates additional
       parameters:

       (s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-decrement
              The amount deducted from packet-error-level in a cycle  without  detected  read  or
              write errors, without going below zero.

       (s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-increment
              The  amount  added  to packet-error-level in a cycle without detected read or write
              errors, without going above packet-error-limit.

       (s32, rw) hm2_<BoardType>.<BoardNum>.packet-error-limit
              The level at which a detected read or write error is treated as a permanent  error.
              When  this  error  level  is reached, the board's io-error pin becomes TRUE and the
              condition must be manually reset.

       (s32, rw) hm2_<BoardType>.<BoardNum>.packet-read-timeout
              The length of time that must pass before a read request times out.  If the value is
              less  than  or  equal  to 0, it is interpreted as 80% of the thread period.  If the
              value is less than 100, it is interpreted as a percentage  of  the  thread  period.
              Otherwise, it is interpreted as a time in nanoseconds.  In any case, the timeout is
              never less than 100 microseconds.

              Setting this value too low can cause spurious read errors.  Setting it too high can
              cause realtime delay errors.

NOTES

       hm2_eth uses an iptables chain called "hm2-eth-rules-output.  That technology is common to
       control network access to (INPUT chain), through (FORWARD chain) or  from  (OUTPUT  chain)
       your  computer.   Someone  who has configured a firewall on Linux has encountered iptables
       and is familiar with that technology.  This chain  contains  addtional  rules  to  control
       network  interface while HAL is running.  The chain is created if it does not exist, and a
       jump to it is inserted at the beginning of the OUTPUT chain if it is  not  there  already.
       If  you  have  an  existing  iptables  setup,  you can insert a direct jump from OUTPUT to
       hm2-eth-rules-output in an order appropriate to your local network.

       At (normal) exit, hm2_eth will remove the rules.  After a crash, you  can  manually  clear
       the  rules  with  sudo  iptables  -F hm2-eth-rules-output; the rules are also removed by a
       reboot.

       "hardware-irq-coalesce-rx-usecs" decreases time  waiting  to  receive  a  packet  on  most
       systems,  but  on  at  least some Marvel-chipset NICs it is harmful.  If the line does not
       improve system performance, then remove it.  A reboot is required for the value to be  set
       back to its power-on default.  This requires the ethtool package to be installed.

BUGS

       Some  hostmot2  functions such uart are coded in a way that causes additional latency when
       used with hm2_eth.

       On the 7i92, the HAL pins for the LEDs are called  CR01..CR04,  but  the  silkscreens  are
       CR3..CR6.   Depending on the FPGA firmware, the LEDs may initially be under control of the
       ethernet engine.  This can be changed until power cycle with

       elbpcom 01D914000000

       Depending on firmware version, this driver may cause the hardware error LED to light  even
       though the driver and hardware are functioning normally.  This will reportedly be fixed in
       future bitfile updates from Mesa.

SEE ALSO

       hostmot2(9), elbpcom(1)

LICENSE

       GPL