// SPDX-License-Identifier: GPL-2.0+ /* * Surface Serial Hub (SSH) driver for communication with the Surface/System * Aggregator Module (SSAM/SAM). * * Provides access to a SAM-over-SSH connected EC via a controller device. * Handles communication via requests as well as enabling, disabling, and * relaying of events. * * Copyright (C) 2019-2022 Maximilian Luz <luzmaximilian@gmail.com>
*/
/* -- Static controller reference. ------------------------------------------ */
/* * Main controller reference. The corresponding lock must be held while * accessing (reading/writing) the reference.
*/ staticstruct ssam_controller *__ssam_controller; static DEFINE_SPINLOCK(__ssam_controller_lock);
/** * ssam_get_controller() - Get reference to SSAM controller. * * Returns a reference to the SSAM controller of the system or %NULL if there * is none, it hasn't been set up yet, or it has already been unregistered. * This function automatically increments the reference count of the * controller, thus the calling party must ensure that ssam_controller_put() * is called when it doesn't need the controller any more.
*/ struct ssam_controller *ssam_get_controller(void)
{ struct ssam_controller *ctrl;
spin_lock(&__ssam_controller_lock);
ctrl = __ssam_controller; if (!ctrl) goto out;
if (WARN_ON(!kref_get_unless_zero(&ctrl->kref)))
ctrl = NULL;
/** * ssam_try_set_controller() - Try to set the main controller reference. * @ctrl: The controller to which the reference should point. * * Set the main controller reference to the given pointer if the reference * hasn't been set already. * * Return: Returns zero on success or %-EEXIST if the reference has already * been set.
*/ staticint ssam_try_set_controller(struct ssam_controller *ctrl)
{ int status = 0;
spin_lock(&__ssam_controller_lock); if (!__ssam_controller)
__ssam_controller = ctrl; else
status = -EEXIST;
spin_unlock(&__ssam_controller_lock);
return status;
}
/** * ssam_clear_controller() - Remove/clear the main controller reference. * * Clears the main controller reference, i.e. sets it to %NULL. This function * should be called before the controller is shut down.
*/ staticvoid ssam_clear_controller(void)
{
spin_lock(&__ssam_controller_lock);
__ssam_controller = NULL;
spin_unlock(&__ssam_controller_lock);
}
/** * ssam_client_link() - Link an arbitrary client device to the controller. * @c: The controller to link to. * @client: The client device. * * Link an arbitrary client device to the controller by creating a device link * between it as consumer and the controller device as provider. This function * can be used for non-SSAM devices (or SSAM devices not registered as child * under the controller) to guarantee that the controller is valid for as long * as the driver of the client device is bound, and that proper suspend and * resume ordering is guaranteed. * * The device link does not have to be destructed manually. It is removed * automatically once the driver of the client device unbinds. * * Return: Returns zero on success, %-ENODEV if the controller is not ready or * going to be removed soon, or %-ENOMEM if the device link could not be * created for other reasons.
*/ int ssam_client_link(struct ssam_controller *c, struct device *client)
{ const u32 flags = DL_FLAG_PM_RUNTIME | DL_FLAG_AUTOREMOVE_CONSUMER; struct device_link *link; struct device *ctrldev;
ssam_controller_statelock(c);
if (c->state != SSAM_CONTROLLER_STARTED) {
ssam_controller_stateunlock(c); return -ENODEV;
}
ctrldev = ssam_controller_device(c); if (!ctrldev) {
ssam_controller_stateunlock(c); return -ENODEV;
}
link = device_link_add(client, ctrldev, flags); if (!link) {
ssam_controller_stateunlock(c); return -ENOMEM;
}
/* * Return -ENODEV if supplier driver is on its way to be removed. In * this case, the controller won't be around for much longer and the * device link is not going to save us any more, as unbinding is * already in progress.
*/ if (READ_ONCE(link->status) == DL_STATE_SUPPLIER_UNBIND) {
ssam_controller_stateunlock(c); return -ENODEV;
}
/** * ssam_client_bind() - Bind an arbitrary client device to the controller. * @client: The client device. * * Link an arbitrary client device to the controller by creating a device link * between it as consumer and the main controller device as provider. This * function can be used for non-SSAM devices to guarantee that the controller * returned by this function is valid for as long as the driver of the client * device is bound, and that proper suspend and resume ordering is guaranteed. * * This function does essentially the same as ssam_client_link(), except that * it first fetches the main controller reference, then creates the link, and * finally returns this reference. Note that this function does not increment * the reference counter of the controller, as, due to the link, the * controller lifetime is assured as long as the driver of the client device * is bound. * * It is not valid to use the controller reference obtained by this method * outside of the driver bound to the client device at the time of calling * this function, without first incrementing the reference count of the * controller via ssam_controller_get(). Even after doing this, care must be * taken that requests are only submitted and notifiers are only * (un-)registered when the controller is active and not suspended. In other * words: The device link only lives as long as the client driver is bound and * any guarantees enforced by this link (e.g. active controller state) can * only be relied upon as long as this link exists and may need to be enforced * in other ways afterwards. * * The created device link does not have to be destructed manually. It is * removed automatically once the driver of the client device unbinds. * * Return: Returns the controller on success, an error pointer with %-ENODEV * if the controller is not present, not ready or going to be removed soon, or * %-ENOMEM if the device link could not be created for other reasons.
*/ struct ssam_controller *ssam_client_bind(struct device *client)
{ struct ssam_controller *c; int status;
c = ssam_get_controller(); if (!c) return ERR_PTR(-ENODEV);
status = ssam_client_link(c, client);
/* * Note that we can drop our controller reference in both success and * failure cases: On success, we have bound the controller lifetime * inherently to the client driver lifetime, i.e. it the controller is * now guaranteed to outlive the client driver. On failure, we're not * going to use the controller any more.
*/
ssam_controller_put(c);
return status >= 0 ? c : ERR_PTR(status);
}
EXPORT_SYMBOL_GPL(ssam_client_bind);
/* * Try to disable notifiers, signal display-off and D0-exit, ignore any * errors. * * Note: It has not been established yet if this is actually * necessary/useful for shutdown.
*/
status = ssam_notifier_disable_registered(c); if (status) {
ssam_err(c, "pm: failed to disable notifiers for shutdown: %d\n",
status);
}
status = ssam_ctrl_notif_display_off(c); if (status)
ssam_err(c, "pm: display-off notification failed: %d\n", status);
status = ssam_ctrl_notif_d0_exit(c); if (status)
ssam_err(c, "pm: D0-exit notification failed: %d\n", status);
}
/* * Try to signal display-off, This will quiesce events. * * Note: Signaling display-off/display-on should normally be done from * some sort of display state notifier. As that is not available, * signal it here.
*/
status = ssam_ctrl_notif_display_off(c); if (status)
ssam_err(c, "pm: display-off notification failed: %d\n", status);
/* * Try to signal display-on. This will restore events. * * Note: Signaling display-off/display-on should normally be done from * some sort of display state notifier. As that is not available, * signal it here.
*/
status = ssam_ctrl_notif_display_on(c); if (status)
ssam_err(c, "pm: display-on notification failed: %d\n", status);
}
/* * Try to disable IRQ wakeup (if specified) and signal D0-entry. In * case of errors, log them and try to restore normal operation state * as far as possible. * * Note: Signaling display-off/display-on should normally be done from * some sort of display state notifier. As that is not available, * signal it here.
*/
ssam_irq_disarm_wakeup(c);
status = ssam_ctrl_notif_d0_entry(c); if (status)
ssam_err(c, "pm: D0-entry notification failed: %d\n", status);
/* * During hibernation image creation, we only have to ensure that the * EC doesn't send us any events. This is done via the display-off * and D0-exit notifications. Note that this sets up the wakeup IRQ * on the EC side, however, we have disabled it by default on our side * and won't enable it here. * * See ssam_serial_hub_poweroff() for more details on the hibernation * process.
*/
status = ssam_ctrl_notif_d0_exit(c); if (status) {
ssam_err(c, "pm: D0-exit notification failed: %d\n", status);
ssam_ctrl_notif_display_on(c); return status;
}
/* * When entering hibernation and powering off the system, the EC, at * least on some models, may disable events. Without us taking care of * that, this leads to events not being enabled/restored when the * system resumes from hibernation, resulting SAM-HID subsystem devices * (i.e. keyboard, touchpad) not working, AC-plug/AC-unplug events being * gone, etc. * * To avoid these issues, we disable all registered events here (this is * likely not actually required) and restore them during the drivers PM * restore callback. * * Wakeup from the EC interrupt is not supported during hibernation, * so don't arm the IRQ here.
*/
status = ssam_notifier_disable_registered(c); if (status) {
ssam_err(c, "pm: failed to disable notifiers for hibernation: %d\n",
status); return status;
}
status = ssam_ctrl_notif_d0_exit(c); if (status) {
ssam_err(c, "pm: D0-exit notification failed: %d\n", status);
ssam_notifier_restore_registered(c); return status;
}
/* * Ignore but log errors, try to restore state as much as possible in * case of failures. See ssam_serial_hub_poweroff() for more details on * the hibernation process.
*/
WARN_ON(ssam_controller_resume(c));
status = ssam_ctrl_notif_d0_entry(c); if (status)
ssam_err(c, "pm: D0-entry notification failed: %d\n", status);
/* Initialize controller. */
status = ssam_controller_init(ctrl, serdev); if (status) {
dev_err_probe(dev, status, "failed to initialize ssam controller\n"); goto err_ctrl_init;
}
ssam_controller_lock(ctrl);
/* Set up serdev device. */
serdev_device_set_drvdata(serdev, ctrl);
serdev_device_set_client_ops(serdev, &ssam_serdev_ops);
status = serdev_device_open(serdev); if (status) {
dev_err_probe(dev, status, "failed to open serdev device\n"); goto err_devopen;
}
status = ssam_serdev_setup(ssh, serdev); if (status) {
status = dev_err_probe(dev, status, "failed to setup serdev\n"); goto err_devinit;
}
/* Start controller. */
status = ssam_controller_start(ctrl); if (status) goto err_devinit;
ssam_controller_unlock(ctrl);
/* * Initial SAM requests: Log version and notify default/init power * states.
*/
status = ssam_log_firmware_version(ctrl); if (status) {
dev_err_probe(dev, status, "failed to get firmware version\n"); goto err_initrq;
}
status = ssam_ctrl_notif_d0_entry(ctrl); if (status) {
dev_err_probe(dev, status, "D0-entry notification failed\n"); goto err_initrq;
}
status = ssam_ctrl_notif_display_on(ctrl); if (status) {
dev_err_probe(dev, status, "display-on notification failed\n"); goto err_initrq;
}
status = sysfs_create_group(&dev->kobj, &ssam_sam_group); if (status) goto err_initrq;
/* Set up IRQ. */
status = ssam_irq_setup(ctrl); if (status) {
dev_err_probe(dev, status, "failed to setup IRQ\n"); goto err_irq;
}
/* Finally, set main controller reference. */
status = ssam_try_set_controller(ctrl); if (WARN_ON(status)) /* Currently, we're the only provider. */ goto err_mainref;
/* * TODO: The EC can wake up the system via the associated GPIO interrupt * in multiple situations. One of which is the remaining battery * capacity falling below a certain threshold. Normally, we should * use the device_init_wakeup function, however, the EC also seems * to have other reasons for waking up the system and it seems * that Windows has additional checks whether the system should be * resumed. In short, this causes some spurious unwanted wake-ups. * For now let's thus default power/wakeup to false.
*/
device_set_wakeup_capable(dev, true);
/* * When using DT, we have to register the platform hub driver manually, * as it can't be matched based on top-level board compatible (like it * does the ACPI case).
*/ if (!ssh) { struct platform_device *ph_pdev =
platform_device_register_simple("surface_aggregator_platform_hub",
0, NULL, 0); if (IS_ERR(ph_pdev)) return dev_err_probe(dev, PTR_ERR(ph_pdev), "Failed to register the platform hub driver\n");
}
/* Remove all client devices. */
ssam_remove_clients(&serdev->dev);
/* Act as if suspending to silence events. */
status = ssam_ctrl_notif_display_off(ctrl); if (status) {
dev_err(&serdev->dev, "display-off notification failed: %d\n",
status);
}
status = ssam_ctrl_notif_d0_exit(ctrl); if (status) {
dev_err(&serdev->dev, "D0-exit notification failed: %d\n",
status);
}
/* Shut down controller and remove serdev device reference from it. */
ssam_controller_shutdown(ctrl);
/* Shut down actual transport. */
serdev_device_wait_until_sent(serdev, 0);
serdev_device_close(serdev);
/* Drop our controller reference. */
ssam_controller_unlock(ctrl);
ssam_controller_put(ctrl);
MODULE_AUTHOR("Maximilian Luz ");
MODULE_DESCRIPTION("Subsystem and Surface Serial Hub driver for Surface System Aggregator Module");
MODULE_LICENSE("GPL");
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung und die Messung sind noch experimentell.