staging: add Fieldbus Device subsystem. (f9a82c48) · Commits · e / devices / android_kernel_fairphone_FP5

drivers/staging/Kconfig

+2 −0

Original line number	Diff line number	Diff line
		@@ -120,4 +120,6 @@ source "drivers/staging/axis-fifo/Kconfig"

		source "drivers/staging/erofs/Kconfig"

		source "drivers/staging/fieldbus/Kconfig"

		endif # STAGING

drivers/staging/Makefile

+1 −0

Original line number	Diff line number	Diff line
		@@ -50,3 +50,4 @@ obj-$(CONFIG_SOC_MT7621) += mt7621-dts/
		obj-$(CONFIG_STAGING_GASKET_FRAMEWORK) += gasket/
		obj-$(CONFIG_XIL_AXIS_FIFO) += axis-fifo/
		obj-$(CONFIG_EROFS_FS) += erofs/
		obj-$(CONFIG_FIELDBUS_DEV) += fieldbus/

drivers/staging/fieldbus/Documentation/ABI/fieldbus-dev-cdev

0 → 100644

+31 −0

Original line number	Diff line number	Diff line
		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

drivers/staging/fieldbus/Documentation/ABI/sysfs-class-fieldbus-dev

0 → 100644

+62 −0

Original line number	Diff line number	Diff line
		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).

drivers/staging/fieldbus/Documentation/fieldbus_dev.txt

0 → 100644

+66 −0

Original line number	Diff line number	Diff line
		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.