Thank you for your work!

Although I'm happy with a lot of [MODEL]/[SKU] directories personally. However, if we want to merge this change into jakeday repo or even we ever want IPTS to be upstreamed, I think this is not yet the cleanest way.

If we want to merge into jakeday repo, I still think all the firmwares should be placed in a one directory.

I first thought we have to write a DMI matching code into IPTS driver to achieve this way.
However, as @StollD mentions, If we can find a way to get MSHW id, it will be much easier and more elegant.

Regarding firmware embedding if we want to build IPTS driver as a built-in driver.

This is not necessarily a issue only on Chromium OS.

If we build IPTS as a built-in driver, we might need firmwares also to be as built-in using kernel config CONFIG_EXTRA_FIRMWARE because a built-in driver attempts to load firmware too early and the root filesystem is not mounted yet [1]. Thus, firmware can't be loaded from a filesystem.

(However, if we want to build all the firmware into a kernel, we need to specify a lot of firmware files in CONFIG_EXTRA_FIRMWARE. This is not realistic, though)

References

• [1] [SOLVED] LFS - direct firmware load failed error -2

So I looked into this a bit more and I might have found a way to do this.

The problem is that the IPTS driver never interacts with the device that
provides the MSHW ID, so there is no direct way to query it from the driver
directly (since that runs on the MEI bus and not on ACPI).

However what I figured out: The ID for IPTS is defined by a device with the
ACPI path \\_SB.TSML. This device seems to exist on all surface models, and
does nothing except returning that MSHW ID as it's _HID.

Device (TSML)
{
	Method (_HID, 0, NotSerialized)  // _HID: Hardware ID
	{
		Return ("MSHW0079")
	}
}

(this is from a Surface Laptop DSDT I found online. I checked another other
DSDT (SB1), and my own one via. sysfs, and all of them report the same path)

So, what we could do is just search for an ACPI device with that specific path
(there is a helper utility in the kernel for that as far as I can tell), and
query it's _HID property. This would give us the MSHW ID, and we could prefix
the firmware path with that, instead of the model name / SKU.

This is a bit more hacky than the approach with model name and SKU, since it
depends on hardcoded ACPI paths, but it would result in a more generic firmware
structure (no need to duplicate the files for models who expose the same _HID).

For example it could look like this (still using subdirectories, since it makes
everything way more read- and understandable IMO):

/lib/firmware/intel/ipts
├── MSHW0076
│   ├── config.bin
│   ├── intel_desc.bin
│   ├── ipts_fw_config.bin
│   ├── vendor_desc.bin
│   └── vendor_kernel.bin
├── MSHW0078
│   ├── config.bin
│   ├── intel_desc.bin
│   ├── ipts_fw_config.bin
│   ├── vendor_desc.bin
│   └── vendor_kernel.bin
├── MSHW0079
│   ├── config.bin
│   ├── intel_desc.bin
│   ├── ipts_fw_config.bin
│   ├── vendor_desc.bin
│   └── vendor_kernel.bin
├── MSHW0101
│   ├── config.bin
│   ├── intel_desc.bin
│   ├── ipts_fw_config.bin
│   ├── vendor_desc.bin
│   └── vendor_kernel.bin
├── MSHW0102
│   ├── config.bin
│   ├── intel_desc.bin
│   ├── ipts_fw_config.bin
│   ├── vendor_desc.bin
│   └── vendor_kernel.bin
└── MSHW0137
    ├── config.bin
    ├── intel_desc.bin
    ├── ipts_fw_config.bin
    ├── vendor_desc.bin
    └── vendor_kernel.bin

6 directories, 30 files

(there is a helper utility in the kernel for that as far as I can tell)

It could be acpi_evaluate_* in drivers/acpi/utils.c

It could be acpi_evaluate_* in drivers/acpi/utils.c

I ended up using acpi_get_handle and acpi_get_object_info:

// This is a dummy device, but it reports a _HID that corresponds
// to the version of the IPTS firmware that is required.
#define IPTS_MSHW_ACPI_PATH       "\\_SB.TSML"
#define IPTS_FW_PATH_FMT          "intel/ipts/%s"
#define IPTS_FW_PATH_FMT_MSHW     "intel/ipts/%s/%s"
#define IPTS_FW_CONFIG_FILE       "ipts_fw_config.bin"

// [...]

int ipts_request_firmware(ipts_info_t *ipts, const struct firmware **fw,
	const char *name, struct device *device)
{
	char fw_path[MAX_IOCL_FILE_PATH_LEN];
	int ret = 0;

	acpi_handle handle;
	acpi_status status;
	struct acpi_device_info *info;

	status = acpi_get_handle(ACPI_ROOT_OBJECT, IPTS_MSHW_ACPI_PATH, &handle);
	if (ACPI_FAILURE(status)) {
		ipts_dbg(ipts, "Unable to find ACPI device %s: %d\n",
			IPTS_MSHW_ACPI_PATH, status);
		goto ipts_load_default_fw_path;
	}

	status = acpi_get_object_info(handle, &info);
	if (ACPI_FAILURE(status)) {
		ipts_dbg(ipts, "Unable to find ACPI info for device %s: %d\n",
			IPTS_MSHW_ACPI_PATH, status);
		goto ipts_load_default_fw_path;
	}

	snprintf(fw_path, MAX_IOCL_FILE_PATH_LEN, IPTS_FW_PATH_FMT_MSHW,
		info->hardware_id.string, name);
	ret = firmware_request_nowarn(fw, fw_path, device);
	if (!ret) {
		goto ipts_request_firmware_return;
	}

	ipts_dbg(ipts, "no firmware '%s' found, retrying with more generic path\n",
		fw_path);

ipts_load_default_fw_path:

	/* No firmware was found for DMI_PRODUCT_NAME, try without DMI parameters */
	snprintf(fw_path, MAX_IOCL_FILE_PATH_LEN, IPTS_FW_PATH_FMT, name);
	ret = request_firmware(fw, fw_path, device);

ipts_request_firmware_return:

	return ret;
}

If you want to try it I can push the updated patch to another branch on my repository.

Pushed the changes for using the MSHW ID, so you guys can take a look: StollD/linux-surface@25b4689

If you decide that this is more suited for merging into jakedays upstream, I
will update this PR accordingly (or just make a new one, idk).

I noticed current IPTS driver will try to work even if config.bin is missing (both when @StollD commit not applied and applied)

ipts mei::3e8d0870-271a-4208-8eb5-9acb9402ae04:0F: Direct firmware load for intel/ipts/config.bin failed with error -2
ipts mei::3e8d0870-271a-4208-8eb5-9acb9402ae04:0F: cannot read fw intel/ipts/config.bin
[...]
ipts mei::3e8d0870-271a-4208-8eb5-9acb9402ae04:0F: touch enabled 4
ipts mei::3e8d0870-271a-4208-8eb5-9acb9402ae04:0F: error : severity : 1, source : 1, code : 250:255:255:255
string Fatal Error
[...]

However, IPTS will not work properly. What do you think whether IPTS should be stopped if config.bin is missing? (The name config.bin is also hardcoded in ipts_fw_config.bin)

@kitakar5525 @StollD Sorry it's currently taking me a while to respond, have some University stuff to do. I haven't had the time to test this myself yet, but I have some potential issues with it and some questions:

• Including the firmware in the kernel is definitely not an option. First of all, due to size, and second due to the legal status. Technically, we don't have any rights for the firmware, so I think shipping them directly in the kernel is a no-no.
• With regards to loading the hard-coded files: Do we know the ipts_fw_config.bin layout? If so we could also change the names of those files by creating a custom ipts_fw_config.bin.
• With regards to the TSML ACPI device: That seems awfully Microsoft specific. The problem with that is that there are some non-Surface devices out there that use IPTS (e.g. HP Spectre X2). With the solution above, we'd assume that TSML is always for touch (even on non-Surface devices) and I'm not sure that we want to make this assumption. Nevertheless I think the MSHW ID should be part of the firmware loading process (as it is on Windows).
• With regards to building IPTS-ME as builtin driver and the firmware loading failure, I guess that could be fixed by returning -EPROBE_DEFER, if we can somehow detect that case.

From the Windows Device Manager, it looks like TSML has it's own driver (Surface Touch Servicing ML). Now this could only be something solely for updating the firmware, but it could also be something like a driver that provides the IPTS driver with the firmware. Unfortunately something like this probably gets a bit complex to implement and I couldn't find a DSDT for a non-Surface device with IPTS to see if that theory works out there, too. DMI-matching with a whitelist and then checking TSML depending on that would also work, but then we could also directly hard-code the firmware names or paths via DMI.

So as a quick recap, I think we should create a driver that loads against the MSHW IDs and supplies the firmware to the IPTS MEI driver. This way, other devices using IPTS could have their own driver. In my opinion, this would nicely separate the ME driver from the touch controller specifics. Problem is that this will break things, so we should probably add some module parameters to directly set the firmware files/directories.

@qzed Thank you for your input!

What would you think about adding and exporting an function in the IPTS ME part, that allows a model specific driver (e.g. ipts_surface, matching against MSHW IDs), to register a custom function for loading firmware through a function pointer?

So basically, ipts_surface would load, cache the MSHW ID, and tell the IPTS ME part about a function that loads firmware from intel/ipts/MSHW0xyz, analog to ipts_request_firmware in the current implementation. When the IPTS ME driver requests a firmware file, it would first check the registered external function, and if that doesn't exist or didn't find anything, it would fall back to loading firmware from intel/ipts.

That way it would still be compatible with existing installations, and other devices using IPTS can add their model detection through a device specific module.

Some questions regarding this idea though:

• Should the code actually use function pointers? An alternative would be to pass strings and interpret them as the name of subdirectories in IPTS ME, but function pointers would allow for more flexibility.
• Should there be a way to actually register multiple handlers? I am inclined towards no, because it simplifies the code (no arrays required), and the modules are only loaded on matching hardware anyways.

I will look into implementing this tomorrow, but I don't really have experience with developing kernel code, so if you have reservations against the idea, or additional input, please tell me.

I think registering a callback function pointer seem like a good idea. Again, I haven't looked at the firmware-loading code in detail but I think one should be enough.

When the IPTS ME driver requests a firmware file, it would first check the registered external function, and if that doesn't exist or didn't find anything, it would fall back to loading firmware from intel/ipts.

This will cause a bit of a problem though: We need to decide on an order in which things are getting registered and set-up. Since we would have two independent drivers, we also can't rely on their order loading, i.e. you'd have to make sure that the order is correct, for example by returning -EPROBE_DEFER when something isn't ready in one of the drivers yet to load it some time later. This all leads to the fallback problem: If we say the surface_ipts firmware registers a callback, then it has to wait for at least the interface via which this is set to be ready. If this is provided by the ME driver, than the ME driver has to load first. But then the ME driver actually needs to wait for the firmware provider to register the callback before proceeding to initialize the ME device. So with the fallback, we would run into the problem that we can't decide if we should wait for a firmware driver to load or if we should fall back on the default paths. Even if we would decide on another order (i.e. firmware provider has to load first) the same issue persists.

Ok, I implemented a first version of this and it seems to work fine. I added an API to IPTS ME that allows to set a function pointer for loading firmware, and wrote an ipts_surface module, that probes against the known MSHW IDs and registers itself through the API added to IPTS ME. I called this kind of driver "companion driver" for the lack of a better name.

Currently, when IPTS ME probes for the ME device, it will check if a firmware handler was already registered, and if not return -EPROBE_DEFER. If there is no companion driver that can load, it will return that forever, unless the kernel stops it at some point. If desired I could add a counter that kills it after, idk, 10 attempts.

After the link to the companion driver was established, it will redirect all firmware requests to it first. If the companion driver wasn't able to find a firmware, it will try to load it from intel/ipts directly. This should solve the problem @qzed described, because the fallback can only work if a companion driver was sucessfully registered (and IPTS ME will wait for that).

I hope this solution is fine for you. I will do some more tests but for the moment everything seems stable on my surface. At the same time it still has support for the old firmware layout, given that a matching companion driver is included. But since we have control over that, it shouldn't cause problems for end-users.

Regarding other devices who might want to use our IPTS driver: I think I could write a companion driver that isn't automatically loaded. When there is a device that wants to use IPTS without a companion driver, the generic driver could be forced to load through /etc/modprobe.d or so. It's firmware handler would do nothing, so that every firmware request will fall back to intel/ipts. It's only purpose would be to stop IPTS ME from waiting for a companion driver and defering probing while doing so. It is a hacky solution, but might be simple enough to get things started for other devices.

Regarding other devices who might want to use our IPTS driver: I think I could write a companion driver that isn't automatically loaded. When there is a device that wants to use IPTS without a companion driver, the generic driver could be forced to load through /etc/modprobe.d or so. It's firmware handler would do nothing, so that every firmware request will fall back to intel/ipts. It's only purpose would be to stop IPTS ME from waiting for a companion driver and defering probing while doing so. It is a hacky solution, but might be simple enough to get things started for other devices.

I think if we already have fallbacks in the MEI driver, we should rather solve that part via a module parameter that then forces the MEI driver to directly fall back to intel/ipts (I think you can just directly do the same thing you did with the stub driver inside the module itself, just check the parameter at probe time and install a dummy handler function).

A small note as I haven't looked at the code yet: You should make sure that setting and clearing the handler function is synchronized properly (e.g. via mutex) and the function cannot be overwritten by a second driver, i.e. if it is non-null and we're trying to set it, return something like -EBUSY. On that note, the firmware-supply-driver also has to remove the handler function again before it can be removed. This in turn, I think, needs some more thought: If the firmware is already loaded, the only issue is reloading it, which I believe is only done during reset and suspend. We thus may want to consider adding a device link in the firmware-supply-driver to ensure the driver is only removed after the MEI driver is removed. On the other hand (the probably safer, but again more involved solution), we could also stop IPTS and unload everything firmware-wise when the handler-function is removed while keeping the MEI driver probed (basically doing nothing at that point, other than waiting for firmware to be supplied to it). That would require to change the implementation checking if the handler-function is present (and the driver in general) to something like:

• When probing the MEI driver and the handler function is already present: start IPTS.
• When probing the MEI driver and the handler function is not present: do nothing, but do not defer.
• When registering the handler function and the MEI driver is already present, start IPTS.
• When removing the handler function: stop IPTS
• When removing the module: remove the handler function, if present (and via that stop IPTS)

This, of course, requires a bunch of well planned synchronization (something like states, e.g. waiting_for_fw, initializing, running, stopping).

I also think it might be a good idea to have options to override the file paths directly (like if all paths are overridden, don't wait for the firmware-supply-driver to load), but that can also be implemented later.

The rest sounds good to me! Thanks for looking into this!

I think if we already have fallbacks in the MEI driver, we should rather solve that part via a module parameter that then forces the MEI driver to directly fall back to intel/ipts (I think you can just directly do the same thing you did with the stub driver inside the module itself, just check the parameter at probe time and install a dummy handler function).

Done, you can make IPTS ignore the missing handler by adding intel_ipts.ignore_companion to the kernel commandline. Tested by blacklisting ipts_surface and booting twice, once without the commandline option (IPTS doesn't load), and once with it (IPTS loads and uses intel/ipts).

You can also disable the fallback loading (so if the companion driver fails to find firmware, IPTS won't start), by adding intel_ipts.ignore_fw_fallback to the kernel commandline. But I am not sure how useful that option is, so we can probably remove it. I just added it for testing.

You should make sure that setting and clearing the handler function is synchronized properly (e.g. via mutex)

Done (I think)

and the function cannot be overwritten by a second driver, i.e. if it is non-null and we're trying to set it, return something like -EBUSY

On that note, the firmware-supply-driver also has to remove the handler function again before it can be removed.

Done too, it actually already did that yesterday.

Regarding issues when suspending: Suspending and reloading the firmware works fine for me. I think the only real issue is if someone manually unloads ipts_surface with modprobe -r, or if it somehow crashes. If IPTS gets unloaded, ipts_surface will get removed automatically, because it depends on symbols exported by IPTS

We thus may want to consider adding a device link in the firmware-supply-driver to ensure the driver is only removed after the MEI driver is removed.

I will look into that.

Code is here: https://github.com/StollD/linux-surface/tree/ipts-wip
The commit history is throwaway and I will fix it when everything is done. Same for the 4.19 patches.

I've rebased v5.2 on master due to some changes there, unfortunately this has created some conflicts. I'll try to look at your code in the next couple of days, but I think a new PR is appropriate when it's ready. Let's keep this one open for discussion until then.

New and improved PR: #7

Closing this one.