218 lines
8.6 KiB
Groff
218 lines
8.6 KiB
Groff
.\" Copyright (c) 2014 Jeff Epler
|
|
.\"
|
|
.\" This is free documentation; you can redistribute it and/or
|
|
.\" modify it under the terms of the GNU General Public License as
|
|
.\" published by the Free Software Foundation; either version 2 of
|
|
.\" the License, or (at your option) any later version.
|
|
.\"
|
|
.\" The GNU General Public License's references to "object code"
|
|
.\" and "executables" are to be interpreted as the output of any
|
|
.\" document formatting or typesetting system, including
|
|
.\" intermediate and printed output.
|
|
.\"
|
|
.\" This manual is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, write to the Free
|
|
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
|
|
.\" USA.
|
|
.TH HM2_ETH "9" "2008-05-13" "LinuxCNC Documentation" "HAL Component"
|
|
.de TQ
|
|
.br
|
|
.ns
|
|
.TP \\$1
|
|
..
|
|
|
|
.SH NAME
|
|
|
|
hm2_eth \- LinuxCNC HAL driver for the Mesa Electronics Ethernet Anything IO boards, with HostMot2 firmware.
|
|
.SH SYNOPSIS
|
|
|
|
.HP
|
|
.B loadrt hm2_eth [config=\fI"str[,str...]"\fB] [board_ip=\fIip[,ip...]\fB] [board_mac=\fImac[,mac...]\fB]
|
|
.RS 4
|
|
.TP
|
|
\fBconfig\fR [default: ""]
|
|
HostMot2 config strings, described in the hostmot2(9) manpage.
|
|
.TP
|
|
\fBboard_ip\fR [default: ""]
|
|
The IP address of the board(s), separated by commas. As shipped, the board address is 192.168.1.121.
|
|
.SH 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, 7i96.
|
|
|
|
The board must have its hardware loaded on the board by the mesaflash(1) program.
|
|
|
|
hm2_eth is only available when linuxcnc is configured with "uspace" realtime.
|
|
|
|
.SH 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
|
|
.UR http://en.wikipedia.org/wiki/IPv4#Private_networks
|
|
Private IPv4 address space.
|
|
.UE
|
|
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.
|
|
|
|
.SS Configure network with static address
|
|
Add these lines to the file /etc/network/interfaces to configure eth1 with a
|
|
static address:
|
|
|
|
.EX
|
|
auto eth1
|
|
iface eth1 inet static
|
|
address 192.168.1.1
|
|
hardware\-irq\-coalesce\-rx\-usecs 0
|
|
.EE
|
|
|
|
.SH 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
|
|
.B packet\-error
|
|
pin is asserted in that cycle, the
|
|
.B 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
|
|
.B mux2(9)
|
|
component for each feedback signal, using
|
|
.B packet\-error
|
|
as the mux2
|
|
.B sel
|
|
input.
|
|
|
|
.SH PINS
|
|
In addition to the pins documented in
|
|
.BR hostmot2(9) ", " hm2_eth(9)
|
|
creates additional pins:
|
|
|
|
.TP
|
|
(bit, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet\-error
|
|
This pin is TRUE when the most recent cycle detected a read or write error,
|
|
and FALSE at other times.
|
|
.TP
|
|
(s32, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.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.
|
|
.TP
|
|
(bit, out) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet\-error\-exceeded
|
|
This pin is TRUE when the current error level is equal to the maximum,
|
|
and FALSE at other times.
|
|
|
|
.SH PARAMETERS
|
|
In addition to the parameters documented in
|
|
.BR hostmot2(9) ", " hm2_eth(9)
|
|
creates additional parameters:
|
|
|
|
.TP
|
|
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet\-error\-decrement
|
|
The amount deducted from \fIpacket\-error\-level\fR in a cycle without
|
|
detected read or write errors, without going below zero.
|
|
|
|
.TP
|
|
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.packet\-error\-increment
|
|
The amount added to \fIpacket\-error\-level\fR in a cycle without
|
|
detected read or write errors, without going above packet\-error\-limit.
|
|
|
|
.TP
|
|
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.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 \fIio\-error\fR pin
|
|
becomes TRUE and the condition must be manually reset.
|
|
|
|
.TP
|
|
(s32, rw) hm2_\fI<BoardType>\fR.\fI<BoardNum>\fR.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.
|
|
|
|
|
|
.SH NOTES
|
|
hm2_eth uses an iptables chain called "hm2\-eth\-rules\-output" to control access
|
|
to the 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 \fBsudo iptables \-F hm2\-eth\-rules\-output\fR;
|
|
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.
|
|
|
|
.SH 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
|
|
|
|
.EX
|
|
elbpcom 01D914000000
|
|
.EE
|
|
|
|
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.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR hostmot2 "(9), " elbpcom (1)
|
|
.SH LICENSE
|
|
|
|
GPL
|