[etherlab-dev] Announcement: Userspace EtherCAT master

[Frank Heckenbach]

Hi,

this is the announcement of my userspace master code, according to
my plans explained in
http://lists.etherlab.org/pipermail/etherlab-dev/2014/000437.html

Download, installation and usage instructions can be found on my web
site at http://fh-soft.de/src/ethercat-userspace.html

I hope you don't mind me sending my announcement to this list.
But it also contains some patches that may be interesting for the
original IgH master code (see below). Further discusssion which is
not related to the IgH master code should be continued by private
mail.

The whole porting was almost easier than I had anticipated. I could
follow my roadmap (as detailed in the mail above) 100%. Almost the
only unexpected problem (aside from some minor issues mostly found
by compiler warnings, see e30-cleanup.patch) was that I had to
increase EC_IO_TIMEOUT from 500 to 2000 (microseconds). And even
that shouldn't have been unexpected since this is exactly the timing
I had planned and tested for anyway (for PDOs); I just hadn't been
aware of this hard timeout for SDOs. So increasing it was no
problem.

With our application at 500Hz we did not observe any packet loss
(including timeouts) over the course of several hours. On a faster
development machine (8*i7), we could even increase the frequency to
2kHz without packet loss during a test of several minutes, and 4kHz
with only sporadic packet loss. (But this won't be our production
machine, unfortunately. ;) This was all done on a standard Debian
wheezy kernel, without CONFIG_PREEMPT set, but of course using soft
realtime and CPU affinity.

As planned, I replaced the cdev ioctl with a simple TCP protocol
that encapsulates the former ioctl data. This makes it possible
(in fact almost trivial) to access it from a remote host. Therefore
I added a new option "--host" to the "ethercat" tool.

One could do the same to lib easily, but I didn't do it yet, since
the value of running an application remotely seems questionable.
(In fact I don't use lib myself, and with the userspace master,
there might be little purpose to it at all, since the main
application runs in userspace already, with less communication
overhead. lib would be useful to run several applications on the
same master simultaneously. Whether or not that's useful to someone,
I kept lib because it was almost trivial to do.)

I built the code as a deb package, because Debian is the system I
use, and because the preferred way for source deb packages is to
have unmodified original sources plus a set of patches which are
applied during the build process. This matches exactly what I had
done before anyway. However, this doesn't mean the code will only
work on Debian; my web site contains build instructions for other
Linux systems.

So all changes I made to the sources are contained in the
debian/patches directory of
http://fh-soft.de/deb/ethercat-userspace_1.5.0-1.debian.tar.gz
(The remaining files in this archive, as well as
ethercat-userspace_1.5.0-1.dsc, are rather standard deb packaging
stuff, not needed unless you want to build deb packages.
ethercat-userspace_1.5.0.orig.tar.bz2 is exactly the original IgH
EtherCAT-Master 1.5.0 release as downloaded from
http://etherlab.org/download/ethercat/ethercat-1.5.0.tar.bz2
just renamed as required by deb package requirements).

The first few patches (starting with "e") should be generally useful
for the kernel master code as well, and you can apply them whether
or not you care about the userspace master:

- e02-*.patch .. e29-*.patch

  These are exactly my previous patches (from the attachment in
  http://lists.etherlab.org/pipermail/etherlab-dev/2014/000404.html),
  though renamed from NN-ethercat-1.5-DESC.patch to eNN-DESC.patch

- e30-cleanup.patch

  Some bug fixes (e.g. type errors) and cleanup (e.g. removal of
  unused variables) that I encountered while building on a 64 bit
  system and with higher warning options. It seems Knud's patches
  contain some of the same; well, that's the price of forked
  development.

- e31-open-master.patch

  Make the ecrt_open_master() function also available for the (so
  far kernel) master application (not only for the lib). It's useful
  to access the master to wait for the bus scan to complete and the
  SDO dictionaries to be fetched, before calling
  ecrt_request_master() which already starts the operation thread.

  Before, I had used an external script which used the ethercat tool
  to do the waiting, but it was already a bit awkward, and would
  become even more so when the application runs with the user space
  master. I see no reason not to make this function available, so I
  did it instead of writing a cumbersome workaround.

- e32-request-master-check-device.patch

  In ecrt_request_master(), verify that the master actually has a
  device attached, just like ecrt_open_master() does.

- e33-errno.patch

  struct ec_sdo_request contains a field called errno which is a bit
  unfortunate since system headers may define errno as a macro (for
  thread support). Of course, this doesn't matter in kernel code
  which doesn't use those headers, but I'd still suggest to change
  it. I simply renamed it to "errno_" here. Of course, any other
  name would be fine, too.

- e34-manpage.patch

  Add a man page (as required by deb packages) for the ethercat
  tool, auto-generated with the "help2man" tool. Add a "--version"
  option (required by help2man) to the tool.

  Note: Applying this patch will add a dependency on help2man which
  is widely available. But if this seems like a problem, it could be
  checked for by configure (there are examples to do this out
  there).

- e35-pkg-config.patch

  Add a .pc file for libethercat, so it can be used with pkg-config.

  Note: pkg-config is not required for building (the file is
  generated with simple variable subtitutions), and using it for the
  installed library is entirely optional, so applying this patch
  doesn't add any dependencies.

The following patches contain changes specifially for userspace
master support, though they don't actually change the behaviour yet.
If you care about userspace support, you could apply them without
breaking the kernel master (though they provide no benefit to it
either):

- u01-ioctl.patch

  Split the ioctl calls from lib and tool into three groups
  (ioctl_noarg (no argument), ioctl_value (just a single integer
  argument), and ioctl_typed (integer argument and some data
  structure)), as will be required by the emulation below.

  This is a boring patch that just replaces ioctl() with 3 other
  names and in the end #defines them all back to ioctl(), so it
  doesn't change the behaviour yet.

- u02-emulation.patch

  Emulation for the kernel headers used by the master code. These
  are partly dummy headers, partly copied from actual kernel headers
  (where there are no actual kernel dependencides, especially
  list.h) and partly replacement functions written for this purpose.

  This patch just adds some files in a new directory
  emulation/linux/ which is not referenced from anywhere, so it
  doesn't change the behaviour yet.

- u03-master-in-userspace.patch

  This patch contains the actual changes necessary for the userspace
  master (in master/ and devices/generic.c). As stated in my
  announcement, I tried to put most of them in the emulation (see
  previous patch), but a few changes were still necessary.

  It also adds the new ecrt_init() and ecrt_done() functions as well
  as ethercat_master.c (see "Usage" for all of them) and, in cdev.c,
  a thread (per master) to provide a TCP based emulation for the
  ioctl calls.

  The patch also contains changes to lib/ and tool/ to use the
  emulation to access the master. (The actual emulation code is in
  master/ioctl.h, together with the master-side code for easier
  maintenance.)

  All relevant changes are #ifdef'ed EC_MASTER_IN_USERSPACE which is
  not defined anywhere, so it doesn't change the behaviour yet.

The last patch finally changes the behaviour:

- build-userspace.patch

  This patch only contains changes to Makefiles and configure to
  avoid building kernel code, as well as examples/ and script/,
  and instead build the userspace master, using -Iemulation/ and
  defining EC_MASTER_IN_USERSPACE as required.

  Someone who is better versed in autotools than I am might even be
  able to arrange things so both versions can be built together.
  This would require building the master twice, of course, but also
  lib/ and tool/ (once with ioctl and once with the TCP emulation),
  or else add a runtime switch to them so the same code will work
  with both versions of the master (which actually shouldn't be so
  hard). Though I don't know if anyone has any use for this -- you
  probably want to use either the kernel or the userspace master,
  not both at the same time ...

Regards,
Frank

-- 
Dipl.-Math. Frank Heckenbach <f.heckenbach at fh-soft.de>
Stubenlohstr. 6, 91052 Erlangen, Germany, +49-9131-21359
Systems Programming, Software Development, IT Consulting