drivers/staging/fieldbus/Documentation/fieldbus_dev.txt

                       Fieldbus-Device Subsystem
               ============================================

Part 0 - What is a Fieldbus Device ?
------------------------------------

Fieldbus is the name of a family of industrial computer network protocols used
for real-time distributed control, standardized as IEC 61158.

A complex automated industrial system -- such as manufacturing assembly line --
usually needs a distributed control system -- an organized hierarchy of
controller systems -- to function. In this hierarchy, there is usually a
Human Machine Interface (HMI) at the top, where an operator can monitor or
operate the system. This is typically linked to a middle layer of programmable
logic controllers (PLC) via a non-time-critical communications system
(e.g. Ethernet). At the bottom of the control chain is the fieldbus that links
the PLCs to the components that actually do the work, such as sensors,
actuators, electric motors, console lights, switches, valves and contactors.

(Source: Wikipedia)

A "Fieldbus Device" is such an actuator, motor, console light, switch, ...
controlled via the Fieldbus by a PLC aka "Fieldbus Controller".

Communication between PLC and device typically happens via process data memory,
separated into input and output areas. The Fieldbus then cyclically transfers
the PLC's output area to the device's input area, and vice versa.

Part I - Why do we need this subsystem?
---------------------------------------

Fieldbus device (client) adapters are commercially available. They allow data
exchange with a PLC aka "Fieldbus Controller" via process data memory.

They are typically used when a Linux device wants to expose itself as an
actuator, motor, console light, switch, etc. over the fieldbus.

The purpose of this subsystem is:
a) present a general, standardized, extensible API/ABI to userspace; and
b) present a convenient interface to drivers.

Part II - How can drivers use the subsystem?
--------------------------------------------

Any driver that wants to register as a Fieldbus Device should allocate and
populate a 'struct fieldbus_dev' (from include/linux/fieldbus_dev.h).
Registration then happens by calling fieldbus_dev_register().

Part III - How can userspace use the subsystem?
-----------------------------------------------

Fieldbus protocols and adapters are diverse and varied. However, they share
a limited few common behaviours and properties. This allows us to define
a simple interface consisting of a character device and a set of sysfs files:

See:
drivers/staging/fieldbus/Documentation/ABI/sysfs-class-fieldbus-dev
drivers/staging/fieldbus/Documentation/ABI/fieldbus-dev-cdev

Note that this simple interface does not provide a way to modify adapter
configuration settings. It is therefore useful only for adapters that get their
configuration settings some other way, e.g. non-volatile memory on the adapter,
through the network, ...

At a later phase, this simple interface can easily co-exist with a future
(netlink-based ?) configuration settings interface.