Merge tag 'driver-core-4.6-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core

What:		/sys/firmware/qemu_fw_cfg/

Date:		August 2015

Contact:	Gabriel Somlo <somlo@cmu.edu>

Description:

		Several different architectures supported by QEMU (x86, arm,

		sun4*, ppc/mac) are provisioned with a firmware configuration

		(fw_cfg) device, originally intended as a way for the host to

		provide configuration data to the guest firmware. Starting

		with QEMU v2.4, arbitrary fw_cfg file entries may be specified

		by the user on the command line, which makes fw_cfg additionally

		useful as an out-of-band, asynchronous mechanism for providing

		configuration data to the guest userspace.

		The authoritative guest-side hardware interface documentation

		to the fw_cfg device can be found in "docs/specs/fw_cfg.txt"

		in the QEMU source tree.

		=== SysFS fw_cfg Interface ===

		The fw_cfg sysfs interface described in this document is only

		intended to display discoverable blobs (i.e., those registered

		with the file directory), as there is no way to determine the

		presence or size of "legacy" blobs (with selector keys between

		0x0002 and 0x0018) programmatically.

		All fw_cfg information is shown under:

			/sys/firmware/qemu_fw_cfg/

		The only legacy blob displayed is the fw_cfg device revision:

			/sys/firmware/qemu_fw_cfg/rev

		--- Discoverable fw_cfg blobs by selector key ---

		All discoverable blobs listed in the fw_cfg file directory are

		displayed as entries named after their unique selector key

		value, e.g.:

			/sys/firmware/qemu_fw_cfg/by_key/32

			/sys/firmware/qemu_fw_cfg/by_key/33

			/sys/firmware/qemu_fw_cfg/by_key/34

			...

		Each such fw_cfg sysfs entry has the following values exported

		as attributes:

		name  	: The 56-byte nul-terminated ASCII string used as the

			  blob's 'file name' in the fw_cfg directory.

		size  	: The length of the blob, as given in the fw_cfg

			  directory.

		key	: The value of the blob's selector key as given in the

			  fw_cfg directory. This value is the same as used in

			  the parent directory name.

		raw	: The raw bytes of the blob, obtained by selecting the

			  entry via the control register, and reading a number

			  of bytes equal to the blob size from the data

			  register.

		--- Listing fw_cfg blobs by file name ---

		While the fw_cfg device does not impose any specific naming

		convention on the blobs registered in the file directory,

		QEMU developers have traditionally used path name semantics

		to give each blob a descriptive name. For example:

			"bootorder"

			"genroms/kvmvapic.bin"

			"etc/e820"

			"etc/boot-fail-wait"

			"etc/system-states"

			"etc/table-loader"

			"etc/acpi/rsdp"

			"etc/acpi/tables"

			"etc/smbios/smbios-tables"

			"etc/smbios/smbios-anchor"

			...

		In addition to the listing by unique selector key described

		above, the fw_cfg sysfs driver also attempts to build a tree

		of directories matching the path name components of fw_cfg

		blob names, ending in symlinks to the by_key entry for each

		"basename", as illustrated below (assume current directory is

		/sys/firmware):

		    qemu_fw_cfg/by_name/bootorder -> ../by_key/38

		    qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35

		    qemu_fw_cfg/by_name/etc/acpi/rsdp -> ../../../by_key/41

		    ...

		Construction of the directory tree and symlinks is done on a

		"best-effort" basis, as there is no guarantee that components

		of fw_cfg blob names are always "well behaved". I.e., there is

		the possibility that a symlink (basename) will conflict with

		a dirname component of another fw_cfg blob, in which case the

		creation of the offending /sys/firmware/qemu_fw_cfg/by_name

		entry will be skipped.

		The authoritative list of entries will continue to be found

		under the /sys/firmware/qemu_fw_cfg/by_key directory.

registers; their location is communicated to the guest's UEFI firmware in the

DTB that QEMU places at the bottom of the guest's DRAM.

The guest writes a selector value (a key) to the selector register, and then

can read the corresponding data (produced by QEMU) via the data register. If

the selected entry is writable, the guest can rewrite it through the data

register.

The authoritative guest-side hardware interface documentation to the fw_cfg

device can be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.

The selector register takes keys in big endian byte order.

The data register allows accesses with 8, 16, 32 and 64-bit width (only at

offset 0 of the register). Accesses larger than a byte are interpreted as

arrays, bundled together only for better performance. The bytes constituting

such a word, in increasing address order, correspond to the bytes that would

have been transferred by byte-wide accesses in chronological order.

The interface allows guest firmware to download various parameters and blobs

that affect how the firmware works and what tables it installs for the guest

OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and

initrd images for direct kernel booting, virtual machine UUID, SMP information,

virtual NUMA topology, and so on.

The authoritative registry of the valid selector values and their meanings is

the QEMU source code; the structure of the data blobs corresponding to the

individual key values is also defined in the QEMU source code.

The presence of the registers can be verified by selecting the "signature" blob

with key 0x0000, and reading four bytes from the data register. The returned

signature is "QEMU".

The outermost protocol (involving the write / read sequences of the control and

data registers) is expected to be versioned, and/or described by feature bits.

The interface revision / feature bitmap can be retrieved with key 0x0001. The

blob to be read from the data register has size 4, and it is to be interpreted

as a uint32_t value in little endian byte order. The current value

(corresponding to the above outer protocol) is zero.

The guest kernel is not expected to use these registers (although it is

certainly allowed to); the device tree bindings are documented here because

this is where device tree bindings reside in general.

Required properties:

point will be unregistered in reverse order. Note that there is a convenience

macro that passes THIS_MODULE as owner parameter:

	#define platform_register_driver(drivers, count)

	#define platform_register_drivers(drivers, count)

Device Enumeration

static void bus_release(struct kobject *kobj)

{

	struct subsys_private *priv =

		container_of(kobj, typeof(*priv), subsys.kobj);

	struct subsys_private *priv = to_subsys_private(kobj);

	struct bus_type *bus = priv->bus;

	kfree(priv);

					int (*compare)(const struct device *a,

							const struct device *b))

{

	struct list_head *pos;

	struct klist_node *n;

	struct device_private *dev_prv;

	struct device *b;

	list_for_each(pos, list) {

		n = container_of(pos, struct klist_node, n_node);

	list_for_each_entry(n, list, n_node) {

		dev_prv = to_device_private_bus(n);

		b = dev_prv->device;

		if (compare(a, b) <= 0) {

					  const struct device *b))

{

	LIST_HEAD(sorted_devices);

	struct list_head *pos, *tmp;

	struct klist_node *n;

	struct klist_node *n, *tmp;

	struct device_private *dev_prv;

	struct device *dev;

	struct klist *device_klist;

	device_klist = bus_get_device_klist(bus);

	spin_lock(&device_klist->k_lock);

	list_for_each_safe(pos, tmp, &device_klist->k_list) {

		n = container_of(pos, struct klist_node, n_node);

	list_for_each_entry_safe(n, tmp, &device_klist->k_list, n_node) {

		dev_prv = to_device_private_bus(n);

		dev = dev_prv->device;

		device_insertion_sort_klist(dev, &sorted_devices, compare);

		knode = klist_next(&iter->ki);

		if (!knode)

			return NULL;

		dev = container_of(knode, struct device_private, knode_bus)->device;

		dev = to_device_private_bus(knode)->device;

		if (!iter->type || iter->type == dev->type)

			return dev;

	}

	}

	if (match->num == match->alloc) {

		size_t new_size = match ? match->alloc + 16 : 15;

		size_t new_size = match->alloc + 16;

		int ret;

		ret = component_match_realloc(master, match, new_size);