Commit abf7dba7 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'char-misc-4.18-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc 

Pull char/misc driver updates from Greg KH:
 "Here is the "big" char and misc driver patches for 4.18-rc1.

  It's not a lot of stuff here, but there are some highlights:

   - coreboot driver updates

   - soundwire driver updates

   - android binder updates

   - fpga big sync, mostly documentation

   - lots of minor driver updates

  All of these have been in linux-next for a while with no reported
  issues"

* tag 'char-misc-4.18-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc: (81 commits)
  vmw_balloon: fixing double free when batching mode is off
  MAINTAINERS: Add driver-api/fpga path
  fpga: clarify that unregister functions also free
  documentation: fpga: move fpga-region.txt to driver-api
  documentation: fpga: add bridge document to driver-api
  documentation: fpga: move fpga-mgr.txt to driver-api
  Documentation: fpga: move fpga overview to driver-api
  fpga: region: kernel-doc fixes
  fpga: bridge: kernel-doc fixes
  fpga: mgr: kernel-doc fixes
  fpga: use SPDX
  fpga: region: change api, add fpga_region_create/free
  fpga: bridge: change api, don't use drvdata
  fpga: manager: change api, don't use drvdata
  fpga: region: don't use drvdata in common fpga code
  Drivers: hv: vmbus: Removed an unnecessary cast from void *
  ver_linux: Drop redundant calls to system() to test if file is readable
  ver_linux: Move stderr redirection from function parameter to function body
  misc: IBM Virtual Management Channel Driver (VMC)
  rpmsg: Correct support for MODULE_DEVICE_TABLE()
  ...
parents 07c4dd34 b23220fe

Documentation/ABI/stable/sysfs-bus-vmbus

+20 −20
Original line number Diff line number Diff line 
What:		/sys/bus/vmbus/devices/vmbus_*/id

What:		/sys/bus/vmbus/devices/<UUID>/id

Date:		Jul 2009

KernelVersion:	2.6.31

Contact:	K. Y. Srinivasan <kys@microsoft.com>

Description:	The VMBus child_relid of the device's primary channel

Users:		tools/hv/lsvmbus



What:		/sys/bus/vmbus/devices/vmbus_*/class_id

What:		/sys/bus/vmbus/devices/<UUID>/class_id

Date:		Jul 2009

KernelVersion:	2.6.31

Contact:	K. Y. Srinivasan <kys@microsoft.com>

Description:	The VMBus interface type GUID of the device

Users:		tools/hv/lsvmbus



What:		/sys/bus/vmbus/devices/vmbus_*/device_id

What:		/sys/bus/vmbus/devices/<UUID>/device_id

Date:		Jul 2009

KernelVersion:	2.6.31

Contact:	K. Y. Srinivasan <kys@microsoft.com>

Description:	The VMBus interface instance GUID of the device

Users:		tools/hv/lsvmbus



What:		/sys/bus/vmbus/devices/vmbus_*/channel_vp_mapping

What:		/sys/bus/vmbus/devices/<UUID>/channel_vp_mapping

Date:		Jul 2015

KernelVersion:	4.2.0

Contact:	K. Y. Srinivasan <kys@microsoft.com>
@@ -28,112 +28,112 @@ Description: The mapping of which primary/sub channels are bound to which 
		Format: <channel's child_relid:the bound cpu's number>

Users:		tools/hv/lsvmbus



What:		/sys/bus/vmbus/devices/vmbus_*/device

What:		/sys/bus/vmbus/devices/<UUID>/device

Date:		Dec. 2015

KernelVersion:	4.5

Contact:	K. Y. Srinivasan <kys@microsoft.com>

Description:	The 16 bit device ID of the device

Users:		tools/hv/lsvmbus and user level RDMA libraries



What:		/sys/bus/vmbus/devices/vmbus_*/vendor

What:		/sys/bus/vmbus/devices/<UUID>/vendor

Date:		Dec. 2015

KernelVersion:	4.5

Contact:	K. Y. Srinivasan <kys@microsoft.com>

Description:	The 16 bit vendor ID of the device

Users:		tools/hv/lsvmbus and user level RDMA libraries



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Directory for per-channel information

		NN is the VMBUS relid associtated with the channel.



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/cpu

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	VCPU (sub)channel is affinitized to

Users:		tools/hv/lsvmbus and other debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/cpu

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	VCPU (sub)channel is affinitized to

Users:		tools/hv/lsvmbus and other debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/in_mask

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/in_mask

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Host to guest channel interrupt mask

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/latency

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/latency

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Channel signaling latency

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/out_mask

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/out_mask

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Guest to host channel interrupt mask

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/pending

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/pending

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Channel interrupt pending state

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/read_avail

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/read_avail

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Bytes available to read

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/write_avail

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/write_avail

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Bytes available to write

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/events

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/events

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Number of times we have signaled the host

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/interrupts

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/interrupts

Date:		September. 2017

KernelVersion:	4.14

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Number of times we have taken an interrupt (incoming)

Users:		Debugging tools



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/subchannel_id

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/subchannel_id

Date:		January. 2018

KernelVersion:	4.16

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Subchannel ID associated with VMBUS channel

Users:		Debugging tools and userspace drivers



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/monitor_id

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/monitor_id

Date:		January. 2018

KernelVersion:	4.16

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Description:	Monitor bit associated with channel

Users:		Debugging tools and userspace drivers



What:		/sys/bus/vmbus/devices/vmbus_*/channels/NN/ring

What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/ring

Date:		January. 2018

KernelVersion:	4.16

Contact:	Stephen Hemminger <sthemmin@microsoft.com>

Documentation/devicetree/bindings/fpga/lattice-machxo2-spi.txt

0 → 100644
+29 −0
Original line number Diff line number Diff line 
Lattice MachXO2 Slave SPI FPGA Manager



Lattice MachXO2 FPGAs support a method of loading the bitstream over

'slave SPI' interface.



See 'MachXO2ProgrammingandConfigurationUsageGuide.pdf' on www.latticesemi.com



Required properties:

- compatible: should contain "lattice,machxo2-slave-spi"

- reg: spi chip select of the FPGA



Example for full FPGA configuration:



	fpga-region0 {

		compatible = "fpga-region";

		fpga-mgr = <&fpga_mgr_spi>;

		#address-cells = <0x1>;

		#size-cells = <0x1>;

	};



	spi1: spi@2000 {

        ...



		fpga_mgr_spi: fpga-mgr@0 {

			compatible = "lattice,machxo2-slave-spi";

			spi-max-frequency = <8000000>;

			reg = <0>;

		};

	};

Documentation/devicetree/bindings/nvmem/zii,rave-sp-eeprom.txt

0 → 100644
+40 −0
Original line number Diff line number Diff line 
Zodiac Inflight Innovations RAVE EEPROM Bindings



RAVE SP EEPROM device is a "MFD cell" device exposing physical EEPROM

attached to RAVE Supervisory Processor. It is expected that its Device

Tree node is specified as a child of the node corresponding to the

parent RAVE SP device (as documented in

Documentation/devicetree/bindings/mfd/zii,rave-sp.txt)



Required properties:



- compatible: Should be "zii,rave-sp-eeprom"



Optional properties:



- zii,eeprom-name: Unique EEPROM identifier describing its function in the

  system. Will be used as created NVMEM deivce's name.



Data cells:



Data cells are child nodes of eerpom node, bindings for which are

documented in Documentation/bindings/nvmem/nvmem.txt



Example:



	rave-sp {

		compatible = "zii,rave-sp-rdu1";

		current-speed = <38400>;



		eeprom@a4 {

			compatible = "zii,rave-sp-eeprom";

			reg = <0xa4 0x4000>;

			#address-cells = <1>;

			#size-cells = <1>;

			zii,eeprom-name = "main-eeprom";



			wdt_timeout: wdt-timeout@81 {

				reg = <0x81 2>;

			};

		};

	}

Documentation/driver-api/fpga/fpga-bridge.rst

0 → 100644
+49 −0
Original line number Diff line number Diff line 
FPGA Bridge

===========



API to implement a new FPGA bridge

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



.. kernel-doc:: include/linux/fpga/fpga-bridge.h

   :functions: fpga_bridge



.. kernel-doc:: include/linux/fpga/fpga-bridge.h

   :functions: fpga_bridge_ops



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_create



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_free



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_register



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_unregister



API to control an FPGA bridge

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



You probably won't need these directly.  FPGA regions should handle this.



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: of_fpga_bridge_get



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_get



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_put



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_get_to_list



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: of_fpga_bridge_get_to_list



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_enable



.. kernel-doc:: drivers/fpga/fpga-bridge.c

   :functions: fpga_bridge_disable

Documentation/fpga/fpga-mgr.txt→Documentation/driver-api/fpga/fpga-mgr.rst

+220 −0
Original line number Diff line number Diff line 
FPGA Manager Core



Alan Tull 2015

FPGA Manager

============



Overview

========

--------



The FPGA manager core exports a set of functions for programming an FPGA with

an image.  The API is manufacturer agnostic.  All manufacturer specifics are
@@ -21,64 +20,93 @@ fpga_image_info). This struct contains parameters such as pointers to the 
FPGA image as well as image-specific particulars such as whether the image was

built for full or partial reconfiguration.



API Functions:

==============

How to support a new FPGA device

--------------------------------



To program the FPGA:

--------------------

To add another FPGA manager, write a driver that implements a set of ops.  The

probe function calls fpga_mgr_register(), such as::



	int fpga_mgr_load(struct fpga_manager *mgr,

			  struct fpga_image_info *info);

	static const struct fpga_manager_ops socfpga_fpga_ops = {

		.write_init = socfpga_fpga_ops_configure_init,

		.write = socfpga_fpga_ops_configure_write,

		.write_complete = socfpga_fpga_ops_configure_complete,

		.state = socfpga_fpga_ops_state,

	};



Load the FPGA from an image which is indicated in the info.  If successful,

the FPGA ends up in operating mode.  Return 0 on success or a negative error

code.

	static int socfpga_fpga_probe(struct platform_device *pdev)

	{

		struct device *dev = &pdev->dev;

		struct socfpga_fpga_priv *priv;

		struct fpga_manager *mgr;

		int ret;



To allocate or free a struct fpga_image_info:

---------------------------------------------

		priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);

		if (!priv)

			return -ENOMEM;



	struct fpga_image_info *fpga_image_info_alloc(struct device *dev);

		/*

		 * do ioremaps, get interrupts, etc. and save

		 * them in priv

		 */



	void fpga_image_info_free(struct fpga_image_info *info);

		mgr = fpga_mgr_create(dev, "Altera SOCFPGA FPGA Manager",

				      &socfpga_fpga_ops, priv);

		if (!mgr)

			return -ENOMEM;



To get/put a reference to a FPGA manager:

-----------------------------------------

		platform_set_drvdata(pdev, mgr);



	struct fpga_manager *of_fpga_mgr_get(struct device_node *node);

	struct fpga_manager *fpga_mgr_get(struct device *dev);

	void fpga_mgr_put(struct fpga_manager *mgr);

		ret = fpga_mgr_register(mgr);

		if (ret)

			fpga_mgr_free(mgr);



Given a DT node or device, get a reference to a FPGA manager.  This pointer

can be saved until you are ready to program the FPGA.  fpga_mgr_put releases

the reference.

		return ret;

	}



	static int socfpga_fpga_remove(struct platform_device *pdev)

	{

		struct fpga_manager *mgr = platform_get_drvdata(pdev);



To get exclusive control of a FPGA manager:

-------------------------------------------

		fpga_mgr_unregister(mgr);



		return 0;

	}



	int fpga_mgr_lock(struct fpga_manager *mgr);

	void fpga_mgr_unlock(struct fpga_manager *mgr);



The user should call fpga_mgr_lock and verify that it returns 0 before

attempting to program the FPGA.  Likewise, the user should call

fpga_mgr_unlock when done programming the FPGA.

The ops will implement whatever device specific register writes are needed to

do the programming sequence for this particular FPGA.  These ops return 0 for

success or negative error codes otherwise.



The programming sequence is::

 1. .write_init

 2. .write or .write_sg (may be called once or multiple times)

 3. .write_complete



To register or unregister the low level FPGA-specific driver:

-------------------------------------------------------------

The .write_init function will prepare the FPGA to receive the image data.  The

buffer passed into .write_init will be atmost .initial_header_size bytes long,

if the whole bitstream is not immediately available then the core code will

buffer up at least this much before starting.



	int fpga_mgr_register(struct device *dev, const char *name,

			      const struct fpga_manager_ops *mops,

			      void *priv);

The .write function writes a buffer to the FPGA. The buffer may be contain the

whole FPGA image or may be a smaller chunk of an FPGA image.  In the latter

case, this function is called multiple times for successive chunks. This interface

is suitable for drivers which use PIO.



	void fpga_mgr_unregister(struct device *dev);

The .write_sg version behaves the same as .write except the input is a sg_table

scatter list. This interface is suitable for drivers which use DMA.



Use of these two functions is described below in "How To Support a new FPGA

device."

The .write_complete function is called after all the image has been written

to put the FPGA into operating mode.



The ops include a .state function which will read the hardware FPGA manager and

return a code of type enum fpga_mgr_states.  It doesn't result in a change in

hardware state.



How to write an image buffer to a supported FPGA

================================================

------------------------------------------------



Some sample code::



	#include <linux/fpga/fpga-mgr.h>



	struct fpga_manager *mgr;
@@ -132,68 +160,61 @@ fpga_mgr_put(mgr); 
	/* Deallocate the image info if you're done with it */

	fpga_image_info_free(info);



How to support a new FPGA device

================================

To add another FPGA manager, write a driver that implements a set of ops.  The

probe function calls fpga_mgr_register(), such as:

API for implementing a new FPGA Manager driver

----------------------------------------------



static const struct fpga_manager_ops socfpga_fpga_ops = {

       .write_init = socfpga_fpga_ops_configure_init,

       .write = socfpga_fpga_ops_configure_write,

       .write_complete = socfpga_fpga_ops_configure_complete,

       .state = socfpga_fpga_ops_state,

};

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_manager



static int socfpga_fpga_probe(struct platform_device *pdev)

{

	struct device *dev = &pdev->dev;

	struct socfpga_fpga_priv *priv;

	int ret;

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_manager_ops



	priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);

	if (!priv)

		return -ENOMEM;

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_create



	/* ... do ioremaps, get interrupts, etc. and save

	   them in priv... */

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_free



	return fpga_mgr_register(dev, "Altera SOCFPGA FPGA Manager",

				 &socfpga_fpga_ops, priv);

}

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_register



static int socfpga_fpga_remove(struct platform_device *pdev)

{

	fpga_mgr_unregister(&pdev->dev);

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_unregister



	return 0;

}

API for programming a FPGA

--------------------------



.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_image_info



The ops will implement whatever device specific register writes are needed to

do the programming sequence for this particular FPGA.  These ops return 0 for

success or negative error codes otherwise.

.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_mgr_states



The programming sequence is:

 1. .write_init

 2. .write or .write_sg (may be called once or multiple times)

 3. .write_complete

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_image_info_alloc



The .write_init function will prepare the FPGA to receive the image data.  The

buffer passed into .write_init will be atmost .initial_header_size bytes long,

if the whole bitstream is not immediately available then the core code will

buffer up at least this much before starting.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_image_info_free



The .write function writes a buffer to the FPGA. The buffer may be contain the

whole FPGA image or may be a smaller chunk of an FPGA image.  In the latter

case, this function is called multiple times for successive chunks. This interface

is suitable for drivers which use PIO.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: of_fpga_mgr_get



The .write_sg version behaves the same as .write except the input is a sg_table

scatter list. This interface is suitable for drivers which use DMA.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_get



The .write_complete function is called after all the image has been written

to put the FPGA into operating mode.

.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_put



The ops include a .state function which will read the hardware FPGA manager and

return a code of type enum fpga_mgr_states.  It doesn't result in a change in

hardware state.
 
.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_lock



.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_unlock



.. kernel-doc:: include/linux/fpga/fpga-mgr.h

   :functions: fpga_mgr_states



Note - use :c:func:`fpga_region_program_fpga()` instead of :c:func:`fpga_mgr_load()`



.. kernel-doc:: drivers/fpga/fpga-mgr.c

   :functions: fpga_mgr_load

CRA Git | Maintained and supported by SUSTech CRA and CCSE