diff options
Diffstat (limited to 'drivers/staging/fieldbus/Documentation')
3 files changed, 159 insertions, 0 deletions
diff --git a/drivers/staging/fieldbus/Documentation/ABI/fieldbus-dev-cdev b/drivers/staging/fieldbus/Documentation/ABI/fieldbus-dev-cdev new file mode 100644 index 000000000000..45f631ea32a6 --- /dev/null +++ b/drivers/staging/fieldbus/Documentation/ABI/fieldbus-dev-cdev @@ -0,0 +1,31 @@ +What: /dev/fieldbus_devX +Date: December 2018 +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + The cdev interface to drivers for Fieldbus Device Memory + (aka. Process Memory). + + The following file operations are supported: + + open(2) + Create an I/O context associated with the file descriptor. + + read(2) + Read from Process Memory's "read area". + Clears POLLERR | POLLPRI from the file descriptor. + + write(2) + Write to Process Memory's "write area". + + poll(2), select(2), epoll_wait(2) etc. + When a "Process Memory Read Area Changed" event occurs, + POLLERR | POLLPRI will be set on the file descriptor. + Note that POLLIN | POLLOUT events are always set, because the + process memory area is always readable and writable. + + close(2) + Free up the I/O context that was associated + with the file descriptor. + +Users: TBD diff --git a/drivers/staging/fieldbus/Documentation/ABI/sysfs-class-fieldbus-dev b/drivers/staging/fieldbus/Documentation/ABI/sysfs-class-fieldbus-dev new file mode 100644 index 000000000000..439f14d33c3b --- /dev/null +++ b/drivers/staging/fieldbus/Documentation/ABI/sysfs-class-fieldbus-dev @@ -0,0 +1,62 @@ +What: /sys/class/fieldbus_dev/fieldbus_devX/card_name +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + Human-readable name of the Fieldbus Device. + +What: /sys/class/fieldbus_dev/fieldbus_devX/fieldbus_type +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + The type of fieldbus implemented by this device. + Possible values: + 'unknown' + 'profinet' + +What: /sys/class/fieldbus_dev/fieldbus_devX/fieldbus_id +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + The unique fieldbus id associated with this device. + The exact format of this id is fieldbus type dependent, e.g. + a mac address for profinet. + +What: /sys/class/fieldbus_dev/fieldbus_devX/read_area_size +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + The size, in bytes, of the Process Memory read area. + Note: this area is accessible by reading from the associated + character device (/dev/fieldbus_devX). + +What: /sys/class/fieldbus_dev/fieldbus_devX/write_area_size +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + The size, in bytes, of the Process Memory write area. + Note: this area is accessible by writing to the associated + character device (/dev/fieldbus_devX) + +What: /sys/class/fieldbus_dev/fieldbus_devX/online +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + Whether the fieldbus is online or offline. + Possible values: + '1' meaning 'online' + '0' meaning 'offline' + Note: an uevent is generated when this property changes. + +What: /sys/class/fieldbus_dev/fieldbus_devX/enabled +KernelVersion: 5.1 (staging) +Contact: Sven Van Asbroeck <TheSven73@gmail.com> +Description: + Whether the device is enabled (power on) or + disabled (power off). + Possible values: + '1' meaning enabled + '0' meaning disabled + Normally a r/o property, but optionally r/w: + Writing '1' enables the device (power on) with default + settings. + Writing '0' disables the card (power off). diff --git a/drivers/staging/fieldbus/Documentation/fieldbus_dev.txt b/drivers/staging/fieldbus/Documentation/fieldbus_dev.txt new file mode 100644 index 000000000000..56af3f650fa3 --- /dev/null +++ b/drivers/staging/fieldbus/Documentation/fieldbus_dev.txt @@ -0,0 +1,66 @@ + 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: +Documentation/ABI/testing/sysfs-class-fieldbus-dev +Documentation/ABI/testing/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. |