Add support for Microsoft Surface System Aggregator Module
Subsystems (7)
Maximilian Luz
maintainerv3 cover Add support for Microsoft Surface System Aggregator Module
Hello,
Here is version three of the Surface System Aggregator Module (SAM/SSAM) driver series, adding initial support for the embedded controller on 5th and later generation Microsoft Surface devices. Initial support includes the ACPI interface to the controller, via which battery and thermal information is provided on some of these devices.
The first version and cover letter detailing what this series is about can be found at
https://lore.kernel.org/platform-driver-x86/[email protected]/
the previous version (v2) at
https://lore.kernel.org/platform-driver-x86/[email protected]/
This patch-set can also be found at the following repository and reference, if you prefer to look at a kernel tree instead of these emails:
https://github.com/linux-surface/kernel tags/s/surface-aggregator/v3
Thank you all for the feedback to and reviews of the previous versions, I hope I have addressed all comments.
Regards,
Max
Note: In v3, I have dropped the explicit dependency of the core module and driver on CONFIG_ACPI due to the incoming
[PATCH] platform/surface: SURFACE_PLATFORMS should depend on ACPI
Thus, this series depends on said patch. This patch can be found at
https://www.spinics.net/lists/platform-driver-x86/msg23929.html
Changes in v1 (from RFC, overview):
- move to platform/surface
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- change user-space interface from debugfs to misc-device
- address issues in user-space interface
- fix typos in commit messages and documentation
- fix some bugs, address other issues
Changes in v2 (overview):
- simplify some code, mostly with regards to concurrency
- add architectural overview to documentation
- improve comments for documentation
- use printk specifier for hex prefix instead of hard-coding it
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix these and other style issues
Changes in v3 (overview):
- remove explicit dependency on ACPI as this is going to be covered by CONFIG_SURFACE_PLATFORMS
- simplify locking requirements
- help enforce locking requirements via lockdep assertions
- fix false-positive lockdep warning
- warn on event enablement reference counter exhaustion
- don't warn about unhandled event if event handling failed
- validate flags on request initialization
- improve documentation/add comments
- replace 'iff' with 'if' in documentation and comments
Changes regarding specific patches (and more details) can be found on the individual patch.
Maximilian Luz (9):
platform/surface: Add Surface Aggregator subsystem platform/surface: aggregator: Add control packet allocation caching platform/surface: aggregator: Add event item allocation caching platform/surface: aggregator: Add trace points platform/surface: aggregator: Add error injection capabilities platform/surface: aggregator: Add dedicated bus and device type
docs: driver-api: Add Surface Aggregator subsystem documentation platform/surface: Add Surface Aggregator user-space interface platform/surface: Add Surface ACPI Notify driver
Documentation/driver-api/index.rst | 1 + .../surface_aggregator/client-api.rst | 38 + .../driver-api/surface_aggregator/client.rst | 393 +++ .../surface_aggregator/clients/cdev.rst | 87 + .../surface_aggregator/clients/index.rst | 21 + .../surface_aggregator/clients/san.rst | 44 + .../driver-api/surface_aggregator/index.rst | 21 + .../surface_aggregator/internal-api.rst | 67 + .../surface_aggregator/internal.rst | 577 ++++ .../surface_aggregator/overview.rst | 77 + .../driver-api/surface_aggregator/ssh.rst | 344 +++ .../userspace-api/ioctl/ioctl-number.rst | 2 + MAINTAINERS | 13 + drivers/platform/surface/Kconfig | 38 + drivers/platform/surface/Makefile | 3 + drivers/platform/surface/aggregator/Kconfig | 68 + drivers/platform/surface/aggregator/Makefile | 17 + drivers/platform/surface/aggregator/bus.c | 415 +++ drivers/platform/surface/aggregator/bus.h | 27 + .../platform/surface/aggregator/controller.c | 2579 +++++++++++++++++ .../platform/surface/aggregator/controller.h | 285 ++ drivers/platform/surface/aggregator/core.c | 839 ++++++ .../platform/surface/aggregator/ssh_msgb.h | 205 ++ .../surface/aggregator/ssh_packet_layer.c | 2057 +++++++++++++ .../surface/aggregator/ssh_packet_layer.h | 190 ++ .../platform/surface/aggregator/ssh_parser.c | 228 ++ .../platform/surface/aggregator/ssh_parser.h | 154 + .../surface/aggregator/ssh_request_layer.c | 1264 ++++++++ .../surface/aggregator/ssh_request_layer.h | 143 + drivers/platform/surface/aggregator/trace.h | 632 ++++ .../platform/surface/surface_acpi_notify.c | 886 ++++++ .../surface/surface_aggregator_cdev.c | 303 ++ include/linux/mod_devicetable.h | 18 + include/linux/surface_acpi_notify.h | 39 + include/linux/surface_aggregator/controller.h | 824 ++++++ include/linux/surface_aggregator/device.h | 423 +++ include/linux/surface_aggregator/serial_hub.h | 672 +++++ include/uapi/linux/surface_aggregator/cdev.h | 78 + scripts/mod/devicetable-offsets.c | 8 + scripts/mod/file2alias.c | 23 + 40 files changed, 14103 insertions(+) create mode 100644 Documentation/driver-api/surface_aggregator/client-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/client.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/cdev.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/san.rst create mode 100644 Documentation/driver-api/surface_aggregator/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal.rst create mode 100644 Documentation/driver-api/surface_aggregator/overview.rst create mode 100644 Documentation/driver-api/surface_aggregator/ssh.rst create mode 100644 drivers/platform/surface/aggregator/Kconfig create mode 100644 drivers/platform/surface/aggregator/Makefile create mode 100644 drivers/platform/surface/aggregator/bus.c create mode 100644 drivers/platform/surface/aggregator/bus.h create mode 100644 drivers/platform/surface/aggregator/controller.c create mode 100644 drivers/platform/surface/aggregator/controller.h create mode 100644 drivers/platform/surface/aggregator/core.c create mode 100644 drivers/platform/surface/aggregator/ssh_msgb.h create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.h create mode 100644 drivers/platform/surface/aggregator/ssh_parser.c create mode 100644 drivers/platform/surface/aggregator/ssh_parser.h create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.h create mode 100644 drivers/platform/surface/aggregator/trace.h create mode 100644 drivers/platform/surface/surface_acpi_notify.c create mode 100644 drivers/platform/surface/surface_aggregator_cdev.c create mode 100644 include/linux/surface_acpi_notify.h create mode 100644 include/linux/surface_aggregator/controller.h create mode 100644 include/linux/surface_aggregator/device.h create mode 100644 include/linux/surface_aggregator/serial_hub.h create mode 100644 include/uapi/linux/surface_aggregator/cdev.h
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 1/9 platform/surface: Add Surface Aggregator subsystem
Add Surface System Aggregator Module core and Surface Serial Hub driver, required for the embedded controller found on Microsoft Surface devices.
The Surface System Aggregator Module (SSAM, SAM or Surface Aggregator) is an embedded controller (EC) found on 4th and later generation Microsoft Surface devices, with the exception of the Surface Go series. This EC provides various functionality, depending on the device in question. This can include battery status and thermal reporting (5th and later generations), but also HID keyboard (6th+) and touchpad input (7th+) on Surface Laptop and Surface Book 3 series devices.
This patch provides the basic necessities for communication with the SAM EC on 5th and later generation devices. On these devices, the EC provides an interface that acts as serial device, called the Surface Serial Hub (SSH). 4th generation devices, on which the EC interface is provided via an HID-over-I2C device, are not supported by this patch.
Specifically, this patch adds a driver for the SSH device (device HID MSHW0084 in ACPI), as well as a controller structure and associated API. This represents the functional core of the Surface Aggregator kernel subsystem, introduced with this patch, and will be expanded upon in subsequent commits.
The SSH driver acts as the main attachment point for this subsystem and sets-up and manages the controller structure. The controller in turn provides a basic communication interface, allowing to send requests from host to EC and receiving the corresponding responses, as well as managing and receiving events, sent from EC to host. It is structured into multiple layers, with the top layer presenting the API used by other kernel drivers and the lower layers modeled after the serial protocol used for communication.
Said other drivers are then responsible for providing the (Surface model specific) functionality accessible through the EC (e.g. battery status reporting, thermal information, ...) via said controller structure and API, and will be added in future commits.
---
Changes in v1 (from RFC):
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- fix bug in __ssh_ptl_queue_push, potentially leading to a deadlock in high-traffic situations
- remove unnecessary READ_ONCE on multiple occasions
- add NULL checks for ssh_packet_get, ssh_packet_put
- add NULL checks for ssh_request_get, ssh_request_put
- guard dev_pm_ops with CONFIG_PM_SLEEP check
- mark struct ssam_request pointer as const when possible
- introduce generic retry macro with defaults
- retry base controller requests on failure
Changes in v2:
- add transmission timeout for packets
- simplify acknowledgment timeout implementation
- simplify packet ACK handling
- restructure and simplify transmitter thread function
- restructure SSH message building
- switch to explicit RCU list for event notifiers
- use sysfs_emit for sysfs attributes
- fix memory leak on event item submission failure
- fix unaligned length access in parser
- use printk specifier for hex prefix instead of hard-coding it
- use numeric limit macros instead of casting around '-1'
- extract and document magic values
- try to make return values more consistent
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix these and other style issues
- improve comments/documentation
Changes in v3:
- remove explicit dependency on CONFIG_ACPI as this is going to be enforced by CONFIG_SURFACE_PLATFORMS
- simplify locking requirements
- help enforce locking requirements via lockdep assertions
- prevent false-positive lockdep warning
- validate flags on request initialization
- warn on event enablement reference counter exhaustion
- don't warn about unhandled event if handling failed
- add comment for return value in ssam_dsm_load_u32()
- add comment regarding _DSM presence
- replace 'iff' with 'if' in documentation
--- MAINTAINERS | 8 + drivers/platform/surface/Kconfig | 2 + drivers/platform/surface/Makefile | 1 + drivers/platform/surface/aggregator/Kconfig | 42 + drivers/platform/surface/aggregator/Makefile | 10 + .../platform/surface/aggregator/controller.c | 2504 +++++++++++++++++ .../platform/surface/aggregator/controller.h | 276 ++ drivers/platform/surface/aggregator/core.c | 787 ++++++ .../platform/surface/aggregator/ssh_msgb.h | 205 ++ .../surface/aggregator/ssh_packet_layer.c | 1710 +++++++++++ .../surface/aggregator/ssh_packet_layer.h | 187 ++ .../platform/surface/aggregator/ssh_parser.c | 228 ++ .../platform/surface/aggregator/ssh_parser.h | 154 + .../surface/aggregator/ssh_request_layer.c | 1211 ++++++++ .../surface/aggregator/ssh_request_layer.h | 143 + include/linux/surface_aggregator/controller.h | 824 ++++++ include/linux/surface_aggregator/serial_hub.h | 672 +++++ 17 files changed, 8964 insertions(+) create mode 100644 drivers/platform/surface/aggregator/Kconfig create mode 100644 drivers/platform/surface/aggregator/Makefile create mode 100644 drivers/platform/surface/aggregator/controller.c create mode 100644 drivers/platform/surface/aggregator/controller.h create mode 100644 drivers/platform/surface/aggregator/core.c create mode 100644 drivers/platform/surface/aggregator/ssh_msgb.h create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.h create mode 100644 drivers/platform/surface/aggregator/ssh_parser.c create mode 100644 drivers/platform/surface/aggregator/ssh_parser.h create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.h create mode 100644 include/linux/surface_aggregator/controller.h create mode 100644 include/linux/surface_aggregator/serial_hub.h
MAINTAINERS +8 -0
@@ -11692,6 +11692,14 @@ L: [email protected] S: Supported F: drivers/platform/surface/surfacepro3_button.c +MICROSOFT SURFACE SYSTEM AGGREGATOR SUBSYSTEM +M: Maximilian Luz <[email protected]> +S: Maintained +W: https://github.com/linux-surface/surface-aggregator-module +C: irc://chat.freenode.net/##linux-surface +F: drivers/platform/surface/aggregator/ +F: include/linux/surface_aggregator/ + MICROTEK X6 SCANNER M: Oliver Neukum <[email protected]> S: Maintained
drivers/platform/surface/Kconfig +2 -0
@@ -56,4 +56,6 @@ config SURFACE_PRO3_BUTTON help This driver handles the power/home/volume buttons on the Microsoft Surface Pro 3/4 tablet. +source "drivers/platform/surface/aggregator/Kconfig" + endif # SURFACE_PLATFORMS
drivers/platform/surface/Makefile +1 -0
@@ -7,5 +7,6 @@ obj-$(CONFIG_SURFACE3_WMI) += surface3-wmi.o obj-$(CONFIG_SURFACE_3_BUTTON) += surface3_button.o obj-$(CONFIG_SURFACE_3_POWER_OPREGION) += surface3_power.o +obj-$(CONFIG_SURFACE_AGGREGATOR) += aggregator/ obj-$(CONFIG_SURFACE_GPE) += surface_gpe.o obj-$(CONFIG_SURFACE_PRO3_BUTTON) += surfacepro3_button.o
drivers/platform/surface/aggregator/Kconfig new file +42 -0
42 lines not on this page · raw message
drivers/platform/surface/aggregator/Makefile new file +10 -0
@@ -0,0 +1,10 @@ +# SPDX-License-Identifier: GPL-2.0+ +# Copyright (C) 2019-2020 Maximilian Luz <[email protected]> + +obj-$(CONFIG_SURFACE_AGGREGATOR) += surface_aggregator.o + +surface_aggregator-objs := core.o +surface_aggregator-objs += ssh_parser.o +surface_aggregator-objs += ssh_packet_layer.o +surface_aggregator-objs += ssh_request_layer.o +surface_aggregator-objs += controller.o
drivers/platform/surface/aggregator/controller.c new file +2504 -0
2,504 lines not on this page · raw message
drivers/platform/surface/aggregator/controller.h new file +276 -0
276 lines not on this page · raw message
drivers/platform/surface/aggregator/core.c new file +787 -0
142 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_msgb.h new file +205 -0
205 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_packet_layer.c new file +1710 -0
1,710 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_packet_layer.h new file +187 -0
187 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_parser.c new file +228 -0
228 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_parser.h new file +154 -0
154 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_request_layer.c new file +1211 -0
1,211 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_request_layer.h new file +143 -0
143 lines not on this page · raw message
include/linux/surface_aggregator/controller.h new file +824 -0
824 lines not on this page · raw message
include/linux/surface_aggregator/serial_hub.h new file +672 -0
672 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.29.2
Part of the diff is not shown here. View the raw message.
Maximilian Luz
maintainerPATCH v3 2/9 platform/surface: aggregator: Add control packet allocation caching
In reply to Maximilian LuzSurface Serial Hub communication is, in its core, packet based. Each sequenced packet requires to be acknowledged, via an ACK-type control packet. In case invalid data has been received by the driver, a NAK-type (not-acknowledge/negative acknowledge) control packet is sent, triggering retransmission.
Control packets are therefore a core communication primitive and used frequently enough (with every sequenced packet transmission sent by the embedded controller, including events and request responses) that it may warrant caching their allocations to reduce possible memory fragmentation.
--- drivers/platform/surface/aggregator/core.c | 27 ++++++++++- .../surface/aggregator/ssh_packet_layer.c | 47 +++++++++++++++---- .../surface/aggregator/ssh_packet_layer.h | 3 ++ 3 files changed, 67 insertions(+), 10 deletions(-)
drivers/platform/surface/aggregator/core.c +26 -1
@@ -780,7 +780,32 @@ static struct serdev_device_driver ssam_serial_hub = { .probe_type = PROBE_PREFER_ASYNCHRONOUS, }, }; -module_serdev_device_driver (ssam_serial_hub); + + +/* -- Module setup. --------------------------------------------------------- */ + +static int __init ssam_core_init (void ) +{ +int status; + + status =ssh_ctrl_packet_cache_init (); +if (status) +return status; + + status =serdev_device_driver_register (&ssam_serial_hub); +if (status) +ssh_ctrl_packet_cache_destroy (); + +return status; +} +module_init (ssam_core_init); + +static void __exit ssam_core_exit(void) +{ +serdev_device_driver_unregister (&ssam_serial_hub); +ssh_ctrl_packet_cache_destroy (); +} +module_exit (ssam_core_exit);MODULE_AUTHOR ("Maximilian Luz <[email protected]>" );MODULE_DESCRIPTION ("Subsystem and Surface Serial Hub driver for Surface System Aggregator Module" );
drivers/platform/surface/aggregator/ssh_packet_layer.c +38 -9
74 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_packet_layer.h +3 -0
@@ -184,4 +184,7 @@ static inline void ssh_ptl_tx_wakeup_transfer(struct ssh_ptl *ptl)void ssh_packet_init (struct ssh_packet *packet,unsigned long type,u8 priority,const struct ssh_packet_ops *ops); +int ssh_ctrl_packet_cache_init (void ); +void ssh_ctrl_packet_cache_destroy (void ); +#endif /* _SURFACE_AGGREGATOR_SSH_PACKET_LAYER_H */
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 3/9 platform/surface: aggregator: Add event item allocation caching
In reply to Maximilian LuzEvent items are used for completing Surface Aggregator EC events, i.e. placing event command data and payload on a workqueue for later processing to avoid doing said processing directly on the receiver thread. This means that event items are allocated for each incoming event, regardless of that event being transmitted via sequenced or unsequenced packets.
On the Surface Book 3 and Surface Laptop 3, touchpad HID input events (unsequenced), can constitute a larger amount of traffic, and therefore allocation of event items. This warrants caching event items to reduce memory fragmentation. The size of the cached objects is specifically tuned to accommodate keyboard and touchpad input events and their payloads on those devices. As a result, this effectively also covers most other event types. In case of a larger event payload, event item allocation will fall back to kzalloc().
--- .../platform/surface/aggregator/controller.c | 86 +++++++++++++++++-- .../platform/surface/aggregator/controller.h | 9 ++ drivers/platform/surface/aggregator/core.c | 16 +++- 3 files changed, 101 insertions(+), 10 deletions(-)
drivers/platform/surface/aggregator/controller.c +78 -8
@@ -513,14 +513,74 @@ static void ssam_nf_destroy(struct ssam_nf *nf)*/ #define SSAM_CPLT_WQ_BATCH 10 +/* +* SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN - Maximum payload length for a cached +* &struct ssam_event_item. +* +* This length has been chosen to be accommodate standard touchpad and +* keyboard input events. Events with larger payloads will be allocated +* separately. +*/ +#define SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN 32 + +static struct kmem_cache *ssam_event_item_cache; + +/** +* ssam_event_item_cache_init() - Initialize the event item cache. +*/ +int ssam_event_item_cache_init (void ) +{ +const unsigned int size =sizeof (struct ssam_event_item ) + +SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN ; +const unsigned int align = __alignof__(struct ssam_event_item ); +struct kmem_cache *cache; + + cache =kmem_cache_create ("ssam_event_item" , size, align,0 ,NULL ); +if (!cache) +return -ENOMEM ; + + ssam_event_item_cache = cache; +return 0 ; +} + +/** +* ssam_event_item_cache_destroy() - Deinitialize the event item cache. +*/ +void ssam_event_item_cache_destroy (void ) +{ +kmem_cache_destroy (ssam_event_item_cache); + ssam_event_item_cache =NULL ; +} + +static void __ssam_event_item_free_cached (struct ssam_event_item *item) +{ +kmem_cache_free (ssam_event_item_cache, item); +} + +static void __ssam_event_item_free_generic (struct ssam_event_item *item) +{ +kfree (item); +} + +/** +* ssam_event_item_free() - Free the provided event item. +* @item: The event item to free. +*/ +static void ssam_event_item_free (struct ssam_event_item *item) +{ + item->ops.free (item); +} +/** * ssam_event_item_alloc() - Allocate an event item with the given payload size. * @len: The event payload length. * @flags: The flags used for allocation. * -* Allocate an event item with the given payload size. Sets the item -* operations and payload length values. The item free callback (``ops.free``) -* should not be overwritten after this call. +* Allocate an event item with the given payload size, preferring allocation +* from the event item cache if the payload is small enough (i.e. smaller than +* %SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN). Sets the item operations and payload +* length values. The item free callback (``ops.free``) should not be +* overwritten after this call. * * Return: Returns the newly allocated event item. */
@@ -528,9 +588,19 @@ static struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags) {struct ssam_event_item *item; - item =kzalloc (struct_size (item, event.data, len), flags); -if (!item) -return NULL ; +if (len <=SSAM_EVENT_ITEM_CACHE_PAYLOAD_LEN ) { + item =kmem_cache_alloc (ssam_event_item_cache, flags); +if (!item) +return NULL ; + + item->ops.free = __ssam_event_item_free_cached; + }else { + item =kzalloc (struct_size (item, event.data, len), flags); +if (!item) +return NULL ; + + item->ops.free = __ssam_event_item_free_generic; + } item->event.length = len;return item;
@@ -692,7 +762,7 @@ static void ssam_event_queue_work_fn(struct work_struct *work)return ;ssam_nf_call (nf, dev, item->rqid, &item->event); -kfree (item); +ssam_event_item_free (item); }while (--iterations);if (!ssam_event_queue_is_empty (queue))
@@ -900,7 +970,7 @@ static void ssam_handle_event(struct ssh_rtl *rtl,memcpy (&item->event.data[0 ], data->ptr, data->len);if (WARN_ON (ssam_cplt_submit_event (&ctrl->cplt, item))) -kfree (item); +ssam_event_item_free (item); }static const struct ssh_rtl_ops ssam_rtl_ops = {
drivers/platform/surface/aggregator/controller.h +9 -0
@@ -80,12 +80,18 @@ struct ssam_cplt;* struct ssam_event_item - Struct for event queuing and completion. * @node: The node in the queue. * @rqid: The request ID of the event. +* @ops: Instance specific functions. +* @ops.free: Callback for freeing this event item. * @event: Actual event data. */ struct ssam_event_item {struct list_head node;u16 rqid; +struct { +void (*free)(struct ssam_event_item *event); + } ops; +struct ssam_event event;/* must be last */ };
@@ -273,4 +279,7 @@ int ssam_ctrl_notif_d0_entry(struct ssam_controller *ctrl);int ssam_controller_suspend (struct ssam_controller *ctrl);int ssam_controller_resume (struct ssam_controller *ctrl); +int ssam_event_item_cache_init (void ); +void ssam_event_item_cache_destroy (void ); +#endif /* _SURFACE_AGGREGATOR_CONTROLLER_H */
drivers/platform/surface/aggregator/core.c +14 -2
@@ -790,12 +790,23 @@ static int __init ssam_core_init(void) status =ssh_ctrl_packet_cache_init ();if (status) -return status; + goto err_cpkg; + + status =ssam_event_item_cache_init (); +if (status) + goto err_evitem; status =serdev_device_driver_register (&ssam_serial_hub);if (status) -ssh_ctrl_packet_cache_destroy (); + goto err_register; +return 0 ; + +err_register: +ssam_event_item_cache_destroy (); +err_evitem: +ssh_ctrl_packet_cache_destroy (); +err_cpkg:return status; }module_init (ssam_core_init);
@@ -803,6 +814,7 @@ module_init(ssam_core_init); static void __exit ssam_core_exit(void) {serdev_device_driver_unregister (&ssam_serial_hub); +ssam_event_item_cache_destroy ();ssh_ctrl_packet_cache_destroy (); }module_exit (ssam_core_exit);
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 4/9 platform/surface: aggregator: Add trace points
In reply to Maximilian LuzAdd trace points to the Surface Aggregator subsystem core. These trace points can be used to track packets, requests, and allocations. They are further intended for debugging and testing/validation, specifically in combination with the error injection capabilities introduced in the subsequent commit.
---
Changes in v1 (from RFC):
- add copyright line
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- pack tracing structs
Changes in v2:
- add compiletime check on SSAM_PTR_UID_LEN
- fix ssam_trace_get_command_field_u8() macro
- use dedicated trace event class for timeout reaper
- use printk specifier for hex prefix instead of hard-coding it
- unify comment style
- run checkpatch --strict, fix warnings and style issues
--- drivers/platform/surface/aggregator/Makefile | 3 + .../platform/surface/aggregator/controller.c | 5 + drivers/platform/surface/aggregator/core.c | 3 + .../surface/aggregator/ssh_packet_layer.c | 26 +- .../surface/aggregator/ssh_request_layer.c | 18 + drivers/platform/surface/aggregator/trace.h | 601 ++++++++++++++++++ 6 files changed, 655 insertions(+), 1 deletion(-) create mode 100644 drivers/platform/surface/aggregator/trace.h
drivers/platform/surface/aggregator/Makefile +3 -0
@@ -1,6 +1,9 @@ # SPDX-License-Identifier: GPL-2.0+ # Copyright (C) 2019-2020 Maximilian Luz <[email protected]> +# For include/trace/define_trace.h to include trace.h +CFLAGS_core.o = -I$(src) + obj-$(CONFIG_SURFACE_AGGREGATOR) += surface_aggregator.o surface_aggregator-objs := core.o
drivers/platform/surface/aggregator/controller.c +5 -0
@@ -32,6 +32,8 @@#include "ssh_msgb.h" #include "ssh_request_layer.h" +#include "trace.h" +/* -- Safe counters. -------------------------------------------------------- */
@@ -568,6 +570,7 @@ static void __ssam_event_item_free_generic(struct ssam_event_item *item)*/ static void ssam_event_item_free (struct ssam_event_item *item) { +trace_ssam_event_item_free (item); item->ops.free (item); }
@@ -603,6 +606,8 @@ static struct ssam_event_item *ssam_event_item_alloc(size_t len, gfp_t flags) } item->event.length = len; + +trace_ssam_event_item_alloc (item, len);return item; }
drivers/platform/surface/aggregator/core.c +3 -0
@@ -24,6 +24,9 @@#include <linux/surface_aggregator/controller.h> #include "controller.h" +#define CREATE_TRACE_POINTS +#include "trace.h" +/* -- Static controller reference. ------------------------------------------ */
drivers/platform/surface/aggregator/ssh_packet_layer.c +25 -1
@@ -26,6 +26,8 @@#include "ssh_packet_layer.h" #include "ssh_parser.h" +#include "trace.h" +/* * To simplify reasoning about the code below, we define a few concepts. The * system below is similar to a state-machine for packets, however, there are
@@ -228,6 +230,8 @@ static void __ssh_ptl_packet_release(struct kref *kref) { struct ssh_packet *p = container_of(kref, struct ssh_packet, refcnt); +trace_ssam_packet_release (p); +ptl_dbg_cond (p->ptl,"ptl: releasing packet %p\n" , p); p->ops->release (p); }
@@ -356,6 +360,7 @@ static int ssh_ctrl_packet_alloc(struct ssh_packet **packet, buffer->ptr = (u8 *)(*packet +1 ); buffer->len =SSH_MSG_LEN_CTRL ; +trace_ssam_ctrl_packet_alloc (*packet, buffer->len);return 0 ; }
@@ -365,6 +370,7 @@ static int ssh_ctrl_packet_alloc(struct ssh_packet **packet,*/ static void ssh_ctrl_packet_free (struct ssh_packet *p) { +trace_ssam_ctrl_packet_free (p);kmem_cache_free (ssh_ctrl_packet_cache, p); }
@@ -398,7 +404,12 @@ static void ssh_packet_next_try(struct ssh_packet *p)lockdep_assert_held (&p->ptl->queue.lock); - p->priority =__SSH_PACKET_PRIORITY (base, try +1 ); +/* +* Ensure that we write the priority in one go via WRITE_ONCE() so we +* can access it via READ_ONCE() for tracing. Note that other access +* is guarded by the queue lock, so no need to use READ_ONCE() there. +*/ +WRITE_ONCE (p->priority,__SSH_PACKET_PRIORITY (base, try +1 )); }/* Must be called with queue lock held. */
@@ -560,6 +571,7 @@ static void __ssh_ptl_complete(struct ssh_packet *p, int status) {struct ssh_ptl *ptl =READ_ONCE (p->ptl); +trace_ssam_packet_complete (p, status);ptl_dbg_cond (ptl,"ptl: completing packet %p (status: %d)\n" , p, status);if (p->ops->complete)
@@ -1014,6 +1026,8 @@ int ssh_ptl_submit(struct ssh_ptl *ptl, struct ssh_packet *p)struct ssh_ptl *ptl_old;int status; +trace_ssam_packet_submit (p); +/* Validate packet fields. */ if (test_bit (SSH_PACKET_TY_FLUSH_BIT , &p->state)) {if (p->data.ptr ||test_bit (SSH_PACKET_TY_SEQUENCED_BIT , &p->state))
@@ -1065,6 +1079,8 @@ static int __ssh_ptl_resubmit(struct ssh_packet *packet)lockdep_assert_held (&packet->ptl->pending.lock); +trace_ssam_packet_resubmit (packet); +spin_lock (&packet->ptl->queue.lock);/* Check if the packet is out of tries. */
@@ -1148,6 +1164,8 @@ void ssh_ptl_cancel(struct ssh_packet *p)if (test_and_set_bit (SSH_PACKET_SF_CANCELED_BIT , &p->state))return ; +trace_ssam_packet_cancel (p); +/* * Lock packet and commit with memory barrier. If this packet has * already been locked, it's going to be removed and completed by
@@ -1202,6 +1220,8 @@ static void ssh_ptl_timeout_reap(struct work_struct *work)bool resub = false;int status; +trace_ssam_ptl_timeout_reap (atomic_read (&ptl->pending.count)); +/* * Mark reaper as "not pending". This is done before checking any * packets to avoid lost-update type problems.
@@ -1224,6 +1244,8 @@ static void ssh_ptl_timeout_reap(struct work_struct *work)continue ; } +trace_ssam_packet_timeout (p); + status =__ssh_ptl_resubmit (p);/*
@@ -1416,6 +1438,8 @@ static size_t ssh_ptl_rx_eval(struct ssh_ptl *ptl, struct ssam_span *source)if (!frame)/* Not enough data. */ return aligned.ptr - source->ptr; +trace_ssam_rx_frame_received (frame); +switch (frame->type) {case SSH_FRAME_TYPE_ACK :ssh_ptl_acknowledge (ptl, frame->seq);
drivers/platform/surface/aggregator/ssh_request_layer.c +18 -0
@@ -22,6 +22,8 @@#include "ssh_packet_layer.h" #include "ssh_request_layer.h" +#include "trace.h" +/* * SSH_RTL_REQUEST_TIMEOUT - Request timeout. *
@@ -144,6 +146,8 @@ static void ssh_rtl_complete_with_status(struct ssh_request *rqst, int status) {struct ssh_rtl *rtl =ssh_request_rtl (rqst); +trace_ssam_request_complete (rqst, status); +/* rtl/ptl may not be set if we're canceling before submitting. */ rtl_dbg_cond (rtl,"rtl: completing request (rqid: %#06x, status: %d)\n" ,ssh_request_get_rqid_safe (rqst), status);
@@ -157,6 +161,8 @@ static void ssh_rtl_complete_with_rsp(struct ssh_request *rqst, {struct ssh_rtl *rtl =ssh_request_rtl (rqst); +trace_ssam_request_complete (rqst,0 ); +rtl_dbg (rtl,"rtl: completing request with response (rqid: %#06x)\n" ,ssh_request_get_rqid (rqst));
@@ -329,6 +335,8 @@ static void ssh_rtl_tx_work_fn(struct work_struct *work)*/ int ssh_rtl_submit (struct ssh_rtl *rtl,struct ssh_request *rqst) { +trace_ssam_request_submit (rqst); +/* * Ensure that requests expecting a response are sequenced. If this * invariant ever changes, see the comment in ssh_rtl_complete() on what
@@ -439,6 +447,8 @@ static void ssh_rtl_complete(struct ssh_rtl *rtl,struct ssh_request *p, *n;u16 rqid =get_unaligned_le16 (&command->rqid); +trace_ssam_rx_response_received (command, command_data->len); +/* * Get request from pending based on request ID and mark it as response * received and locked.
@@ -688,6 +698,8 @@ bool ssh_rtl_cancel(struct ssh_request *rqst, bool pending)if (test_and_set_bit (SSH_REQUEST_SF_CANCELED_BIT , &rqst->state))return true; +trace_ssam_request_cancel (rqst); +if (pending) canceled =ssh_rtl_cancel_pending (rqst);else
@@ -779,6 +791,8 @@ static void ssh_rtl_timeout_reap(struct work_struct *work)ktime_t timeout = rtl->rtx_timeout.timeout;ktime_t next =KTIME_MAX ; +trace_ssam_rtl_timeout_reap (atomic_read (&rtl->pending.count)); +/* * Mark reaper as "not pending". This is done before checking any * requests to avoid lost-update type problems.
@@ -822,6 +836,8 @@ static void ssh_rtl_timeout_reap(struct work_struct *work)/* Cancel and complete the request. */ list_for_each_entry_safe (r, n, &claimed, node) { +trace_ssam_request_timeout (r); +/* * At this point we've removed the packet from pending. This * means that we've obtained the last (only) reference of the
@@ -849,6 +865,8 @@ static void ssh_rtl_timeout_reap(struct work_struct *work)static void ssh_rtl_rx_event (struct ssh_rtl *rtl,const struct ssh_command *cmd,const struct ssam_span *data) { +trace_ssam_rx_event_received (cmd, data->len); +rtl_dbg (rtl,"rtl: handling event (rqid: %#06x)\n" ,get_unaligned_le16 (&cmd->rqid));
drivers/platform/surface/aggregator/trace.h new file +601 -0
601 lines not on this page · raw message
Signature · 1 line
2.29.2
Re: [PATCH v3 4/9] platform/surface: aggregator: Add trace points
Quoted 15 lines · On Mon, 21 Dec 2020 19:39:54 +0100 Maximilian Luz <[email protected]>…
Add trace points to the Surface Aggregator subsystem core. These trace points can be used to track packets, requests, and allocations. They are further intended for debugging and testing/validation, specifically in combination with the error injection capabilities introduced in the subsequent commit.
Signed-off-by Maximilian Luz <[email protected]>Reviewed-by Hans de Goede <[email protected]>---
Changes in v1 (from RFC):
- add copyright line
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- pack tracing structs
Quoted 9 lines
Changes in v2:
- add compiletime check onSSAM_PTR_UID_LEN
- fixssam_trace_get_command_field_u8()macro
- use dedicated trace event class for timeout reaper
- use printk specifier for hex prefix instead of hard-coding it
- unify comment style
- run checkpatch --strict, fix warnings and style issues
From a tracing point of view:
-- Steve
Maximilian Luz
maintainerPATCH v3 5/9 platform/surface: aggregator: Add error injection capabilities
In reply to Maximilian LuzThis commit adds error injection hooks to the Surface Serial Hub communication protocol implementation, to:
- simulate simple serial transmission errors,
- drop packets, requests, and responses, simulating communication failures and potentially trigger retransmission timeouts, as well as
- inject invalid data into submitted and received packets.
Together with the trace points introduced in the previous commit, these facilities are intended to aid in testing, validation, and debugging of the Surface Aggregator communication layer.
---
Changes in v1 (from RFC):
- remove unnecessary default in Kconfig entry
Changes in v2:
- use dedicated trace event class for data error injection
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix warnings and style issues
--- drivers/platform/surface/aggregator/Kconfig | 14 + .../surface/aggregator/ssh_packet_layer.c | 296 +++++++++++++++++- .../surface/aggregator/ssh_request_layer.c | 35 +++ drivers/platform/surface/aggregator/trace.h | 31 ++ 4 files changed, 375 insertions(+), 1 deletion(-)
drivers/platform/surface/aggregator/Kconfig +14 -0
@@ -40,3 +40,17 @@ menuconfig SURFACE_AGGREGATOR Choose m if you want to build the SAM subsystem core and SSH driver as module, y if you want to build it into the kernel and n if you don't want it at all. + +config SURFACE_AGGREGATOR_ERROR_INJECTION + bool "Surface System Aggregator Module Error Injection Capabilities" + depends on SURFACE_AGGREGATOR + depends on FUNCTION_ERROR_INJECTION + help + Provides error-injection capabilities for the Surface System + Aggregator Module subsystem and Surface Serial Hub driver. + + Specifically, exports error injection hooks to be used with the + kernel's function error injection capabilities to simulate underlying + transport and communication problems, such as invalid data sent to or + received from the EC, dropped data, and communication timeouts. + Intended for development and debugging.
drivers/platform/surface/aggregator/ssh_packet_layer.c +295 -1
332 lines not on this page · raw message
drivers/platform/surface/aggregator/ssh_request_layer.c +35 -0
@@ -8,6 +8,7 @@#include <asm/unaligned.h> #include <linux/atomic.h> #include <linux/completion.h> +#include <linux/error-injection.h> #include <linux/ktime.h> #include <linux/limits.h> #include <linux/list.h>
@@ -58,6 +59,30 @@*/ #define SSH_RTL_TX_BATCH 10 +#ifdef CONFIG_SURFACE_AGGREGATOR_ERROR_INJECTION + +/** +* ssh_rtl_should_drop_response() - Error injection hook to drop request +* responses. +* +* Useful to cause request transmission timeouts in the driver by dropping the +* response to a request. +*/ +static noinline bool ssh_rtl_should_drop_response(void) +{ +return false; +} +ALLOW_ERROR_INJECTION (ssh_rtl_should_drop_response, TRUE); + +#else + +static inline bool ssh_rtl_should_drop_response (void ) +{ +return false; +} + +#endif +static u16 ssh_request_get_rqid (struct ssh_request *rqst) { return get_unaligned_le16(rqst->packet.data.ptr
@@ -459,6 +484,16 @@ static void ssh_rtl_complete(struct ssh_rtl *rtl,if (unlikely (ssh_request_get_rqid (p) != rqid))continue ; +/* Simulate response timeout. */ +if (ssh_rtl_should_drop_response ()) { +spin_unlock (&rtl->pending.lock); + +trace_ssam_ei_rx_drop_response (p); +rtl_info (rtl,"request error injection: dropping response for request %p\n" , + &p->packet); +return ; + } +/* * Mark as "response received" and "locked" as we're going to * complete it.
drivers/platform/surface/aggregator/trace.h +31 -0
@@ -565,6 +565,28 @@ DECLARE_EVENT_CLASS(ssam_pending_class, TP_ARGS(pending) \ ) +DECLARE_EVENT_CLASS (ssam_data_class, + TP_PROTO(size_t length), + +TP_ARGS (length), + +TP_STRUCT__entry ( +__field (size_t, length) + ), + +TP_fast_assign ( + __entry->length = length; + ), + +TP_printk ("length=%zu" , __entry->length) +); + +#define DEFINE_SSAM_DATA_EVENT (name) \ + DEFINE_EVENT(ssam_data_class, ssam_##name, \ + TP_PROTO(size_t length), \ + TP_ARGS(length) \ + ) +DEFINE_SSAM_FRAME_EVENT (rx_frame_received);DEFINE_SSAM_COMMAND_EVENT (rx_response_received);DEFINE_SSAM_COMMAND_EVENT (rx_event_received);
@@ -583,6 +605,15 @@ DEFINE_SSAM_REQUEST_EVENT(request_cancel);DEFINE_SSAM_REQUEST_STATUS_EVENT (request_complete);DEFINE_SSAM_PENDING_EVENT (rtl_timeout_reap); +DEFINE_SSAM_PACKET_EVENT (ei_tx_drop_ack_packet); +DEFINE_SSAM_PACKET_EVENT (ei_tx_drop_nak_packet); +DEFINE_SSAM_PACKET_EVENT (ei_tx_drop_dsq_packet); +DEFINE_SSAM_PACKET_STATUS_EVENT (ei_tx_fail_write); +DEFINE_SSAM_PACKET_EVENT (ei_tx_corrupt_data); +DEFINE_SSAM_DATA_EVENT (ei_rx_corrupt_syn); +DEFINE_SSAM_FRAME_EVENT (ei_rx_corrupt_data); +DEFINE_SSAM_REQUEST_EVENT (ei_rx_drop_response); +DEFINE_SSAM_ALLOC_EVENT (ctrl_packet_alloc);DEFINE_SSAM_FREE_EVENT (ctrl_packet_free);
Signature · 1 line
2.29.2
Re: [PATCH v3 5/9] platform/surface: aggregator: Add error injection capabilities
Quoted 18 lines · On Mon, 21 Dec 2020 19:39:55 +0100 Maximilian Luz <[email protected]>…
This commit adds error injection hooks to the Surface Serial Hub communication protocol implementation, to:
- simulate simple serial transmission errors,
- drop packets, requests, and responses, simulating communication failures and potentially trigger retransmission timeouts, as well as
- inject invalid data into submitted and received packets.
Together with the trace points introduced in the previous commit, these facilities are intended to aid in testing, validation, and debugging of the Surface Aggregator communication layer.
Signed-off-by Maximilian Luz <[email protected]>Reviewed-by Hans de Goede <[email protected]>---
Quoted 9 lines
Changes in v1 (from RFC):
- remove unnecessary default inKconfigentryChanges in v2:
- use dedicated trace event class for data error injection
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix warnings and style issues
From a tracing point of view:
-- Steve
Quoted 7 lines
--- drivers/platform/surface/aggregator/Kconfig | 14 + .../surface/aggregator/ssh_packet_layer.c | 296 +++++++++++++++++- .../surface/aggregator/ssh_request_layer.c | 35 +++ drivers/platform/surface/aggregator/trace.h | 31 ++ 4 files changed, 375 insertions(+), 1 deletion(-)
Maximilian Luz
maintainerPATCH v3 6/9 platform/surface: aggregator: Add dedicated bus and device type
In reply to Maximilian LuzThe Surface Aggregator EC provides varying functionality, depending on the Surface device. To manage this functionality, we use dedicated client devices for each subsystem or virtual device of the EC. While some of these clients are described as standard devices in ACPI and the corresponding client drivers can be implemented as platform drivers in the kernel (making use of the controller API already present), many devices, especially on newer Surface models, cannot be found there.
To simplify management of these devices, we introduce a new bus and client device type for the Surface Aggregator subsystem. The new device type takes care of managing the controller reference, essentially guaranteeing its validity for as long as the client device exists, thus alleviating the need to manually establish device links for that purpose in the client driver (as has to be done with the platform devices).
---
Changes in v1 (from RFC):
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- remove unnecessary READ_ONCE on multiple occasions
- improve documentation of special values for SSAM_DEVICE()
- add NULL checks for ssam_device_get, ssam_device_put
Changes in v2:
- return ENODEV instead of ENXIO if controller is not present
- use sysfs_emit for sysfs attributes
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix warnings and style issues
Changes in v3:
- replace 'iff' with 'if' in documentation/comments
--- drivers/platform/surface/aggregator/Kconfig | 12 + drivers/platform/surface/aggregator/Makefile | 4 + drivers/platform/surface/aggregator/bus.c | 415 ++++++++++++++++++ drivers/platform/surface/aggregator/bus.h | 27 ++ drivers/platform/surface/aggregator/core.c | 12 + include/linux/mod_devicetable.h | 18 + include/linux/surface_aggregator/device.h | 423 +++++++++++++++++++ scripts/mod/devicetable-offsets.c | 8 + scripts/mod/file2alias.c | 23 + 9 files changed, 942 insertions(+) create mode 100644 drivers/platform/surface/aggregator/bus.c create mode 100644 drivers/platform/surface/aggregator/bus.h create mode 100644 include/linux/surface_aggregator/device.h
drivers/platform/surface/aggregator/Kconfig +12 -0
@@ -41,6 +41,18 @@ menuconfig SURFACE_AGGREGATOR module, y if you want to build it into the kernel and n if you don't want it at all. +config SURFACE_AGGREGATOR_BUS + bool "Surface System Aggregator Module Bus" + depends on SURFACE_AGGREGATOR + default y + help + Expands the Surface System Aggregator Module (SSAM) core driver by + providing a dedicated bus and client-device type. + + This bus and device type are intended to provide and simplify support + for non-platform and non-ACPI SSAM devices, i.e. SSAM devices that are + not auto-detectable via the conventional means (e.g. ACPI). + config SURFACE_AGGREGATOR_ERROR_INJECTION bool "Surface System Aggregator Module Error Injection Capabilities" depends on SURFACE_AGGREGATOR
drivers/platform/surface/aggregator/Makefile +4 -0
@@ -11,3 +11,7 @@ surface_aggregator-objs += ssh_parser.o surface_aggregator-objs += ssh_packet_layer.o surface_aggregator-objs += ssh_request_layer.o surface_aggregator-objs += controller.o + +ifeq ($(CONFIG_SURFACE_AGGREGATOR_BUS),y) +surface_aggregator-objs += bus.o +endif
drivers/platform/surface/aggregator/bus.c new file +415 -0
415 lines not on this page · raw message
drivers/platform/surface/aggregator/bus.h new file +27 -0
@@ -0,0 +1,27 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* +* Surface System Aggregator Module bus and device integration. +* +* Copyright (C) 2019-2020 Maximilian Luz <[email protected]> +*/ + +#ifndef _SURFACE_AGGREGATOR_BUS_H +#define _SURFACE_AGGREGATOR_BUS_H + +#include <linux/surface_aggregator/controller.h> + +#ifdef CONFIG_SURFACE_AGGREGATOR_BUS + +void ssam_controller_remove_clients (struct ssam_controller *ctrl); + +int ssam_bus_register (void ); +void ssam_bus_unregister (void ); + +#else /* CONFIG_SURFACE_AGGREGATOR_BUS */ + +static inline void ssam_controller_remove_clients (struct ssam_controller *ctrl) {} +static inline int ssam_bus_register (void ) {return 0 ; } +static inline void ssam_bus_unregister (void ) {} + +#endif /* CONFIG_SURFACE_AGGREGATOR_BUS */ +#endif /* _SURFACE_AGGREGATOR_BUS_H */
drivers/platform/surface/aggregator/core.c +12 -0
@@ -22,6 +22,8 @@#include <linux/sysfs.h> #include <linux/surface_aggregator/controller.h> + +#include "bus.h" #include "controller.h" #define CREATE_TRACE_POINTS
@@ -739,6 +741,9 @@ static void ssam_serial_hub_remove(struct serdev_device *serdev)sysfs_remove_group (&serdev->dev.kobj, &ssam_sam_group);ssam_controller_lock (ctrl); +/* Remove all client devices. */ +ssam_controller_remove_clients (ctrl); +/* Act as if suspending to silence events. */ status =ssam_ctrl_notif_display_off (ctrl);if (status) {
@@ -791,6 +796,10 @@ static int __init ssam_core_init(void) {int status; + status =ssam_bus_register (); +if (status) + goto err_bus; + status =ssh_ctrl_packet_cache_init ();if (status) goto err_cpkg;
@@ -810,6 +819,8 @@ static int __init ssam_core_init(void) err_evitem:ssh_ctrl_packet_cache_destroy (); err_cpkg: +ssam_bus_unregister (); +err_bus:return status; }module_init (ssam_core_init);
@@ -819,6 +830,7 @@ static void __exit ssam_core_exit(void)serdev_device_driver_unregister (&ssam_serial_hub);ssam_event_item_cache_destroy ();ssh_ctrl_packet_cache_destroy (); +ssam_bus_unregister (); }module_exit (ssam_core_exit);
include/linux/mod_devicetable.h +18 -0
@@ -838,4 +838,22 @@ struct mhi_device_id { kernel_ulong_t driver_data; }; +/* Surface System Aggregator Module */ + +#define SSAM_MATCH_TARGET 0x1 +#define SSAM_MATCH_INSTANCE 0x2 +#define SSAM_MATCH_FUNCTION 0x4 + +struct ssam_device_id { +__u8 match_flags; + +__u8 domain; +__u8 category; +__u8 target; +__u8 instance; +__u8 function; + +kernel_ulong_t driver_data; +}; +#endif /* LINUX_MOD_DEVICETABLE_H */
include/linux/surface_aggregator/device.h new file +423 -0
423 lines not on this page · raw message
scripts/mod/devicetable-offsets.c +8 -0
@@ -243,5 +243,13 @@ int main(void)DEVID (mhi_device_id);DEVID_FIELD (mhi_device_id, chan); +DEVID (ssam_device_id); +DEVID_FIELD (ssam_device_id, match_flags); +DEVID_FIELD (ssam_device_id, domain); +DEVID_FIELD (ssam_device_id, category); +DEVID_FIELD (ssam_device_id, target); +DEVID_FIELD (ssam_device_id, instance); +DEVID_FIELD (ssam_device_id, function); +return 0 ; }
scripts/mod/file2alias.c +23 -0
@@ -1368,6 +1368,28 @@ static int do_mhi_entry(const char *filename, void *symval, char *alias)return 1 ; } +/* +* Looks like: ssam:dNcNtNiNfN +* +* N is exactly 2 digits, where each is an upper-case hex digit. +*/ +static int do_ssam_entry (const char *filename,void *symval,char *alias) +{ +DEF_FIELD (symval, ssam_device_id, match_flags); +DEF_FIELD (symval, ssam_device_id, domain); +DEF_FIELD (symval, ssam_device_id, category); +DEF_FIELD (symval, ssam_device_id, target); +DEF_FIELD (symval, ssam_device_id, instance); +DEF_FIELD (symval, ssam_device_id, function); + +sprintf (alias,"ssam:d%02Xc%02X" , domain, category); +ADD (alias,"t" , match_flags &SSAM_MATCH_TARGET , target); +ADD (alias,"i" , match_flags &SSAM_MATCH_INSTANCE , instance); +ADD (alias,"f" , match_flags &SSAM_MATCH_FUNCTION , function); + +return 1 ; +} +/* Does namelen bytes of name exactly match the symbol? */ static bool sym_is (const char *name,unsigned namelen,const char *symbol) {
@@ -1442,6 +1464,7 @@ static const struct devtable devtable[] = { {"tee", SIZE_tee_client_device_id, do_tee_entry}, {"wmi", SIZE_wmi_device_id, do_wmi_entry}, {"mhi", SIZE_mhi_device_id, do_mhi_entry}, + {"ssam", SIZE_ssam_device_id, do_ssam_entry}, };/* Create MODULE_ALIAS() statements.
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 7/9 docs: driver-api: Add Surface Aggregator subsystem documentation
In reply to Maximilian LuzAdd documentation for the Surface Aggregator subsystem and its client drivers, giving an overview of the subsystem, its use-cases, its internal structure and internal API, as well as its external API for writing client drivers.
---
Changes in v1 (from RFC):
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- fix typos
Changes in v2:
- add architectural overview for core driver internals
- reorder chapters
- improve wording
--- Documentation/driver-api/index.rst | 1 + .../surface_aggregator/client-api.rst | 38 ++ .../driver-api/surface_aggregator/client.rst | 393 ++++++++++++ .../surface_aggregator/clients/index.rst | 10 + .../driver-api/surface_aggregator/index.rst | 21 + .../surface_aggregator/internal-api.rst | 67 ++ .../surface_aggregator/internal.rst | 577 ++++++++++++++++++ .../surface_aggregator/overview.rst | 77 +++ .../driver-api/surface_aggregator/ssh.rst | 344 +++++++++++ MAINTAINERS | 1 + 10 files changed, 1529 insertions(+) create mode 100644 Documentation/driver-api/surface_aggregator/client-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/client.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal.rst create mode 100644 Documentation/driver-api/surface_aggregator/overview.rst create mode 100644 Documentation/driver-api/surface_aggregator/ssh.rst
Documentation/driver-api/index.rst +1 -0
@@ -97,6 +97,7 @@ available subsections can be seen below. rfkill serial/index sm501 + surface_aggregator/index switchtec sync_file vfio-mediated-device
Documentation/driver-api/surface_aggregator/client-api.rst new file +38 -0
@@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=============================== +Client Driver API Documentation +=============================== + +.. contents:: + :depth: 2 + + +Serial Hub Communication +======================== + +.. kernel-doc:: include/linux/surface_aggregator/serial_hub.h + +.. kernel-doc:: drivers/platform/surface/aggregator/ssh_packet_layer.c + :export: + + +Controller and Core Interface +============================= + +.. kernel-doc:: include/linux/surface_aggregator/controller.h + +.. kernel-doc:: drivers/platform/surface/aggregator/controller.c + :export: + +.. kernel-doc:: drivers/platform/surface/aggregator/core.c + :export: + + +Client Bus and Client Device API +================================ + +.. kernel-doc:: include/linux/surface_aggregator/device.h + +.. kernel-doc:: drivers/platform/surface/aggregator/bus.c + :export:
Documentation/driver-api/surface_aggregator/client.rst new file +393 -0
393 lines not on this page · raw message
Documentation/driver-api/surface_aggregator/clients/index.rst new file +10 -0
@@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +=========================== +Client Driver Documentation +=========================== + +This is the documentation for client drivers themselves. Refer to +:doc:`../client` for documentation on how to write client drivers. + +.. Place documentation for individual client drivers here.
Documentation/driver-api/surface_aggregator/index.rst new file +21 -0
@@ -0,0 +1,21 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +======================================= +Surface System Aggregator Module (SSAM) +======================================= + +.. toctree:: + :maxdepth: 2 + + overview + client + clients/index + ssh + internal + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Documentation/driver-api/surface_aggregator/internal-api.rst new file +67 -0
67 lines not on this page · raw message
Documentation/driver-api/surface_aggregator/internal.rst new file +577 -0
577 lines not on this page · raw message
Documentation/driver-api/surface_aggregator/overview.rst new file +77 -0
77 lines not on this page · raw message
Documentation/driver-api/surface_aggregator/ssh.rst new file +344 -0
344 lines not on this page · raw message
MAINTAINERS +1 -0
@@ -11697,6 +11697,7 @@ M: Maximilian Luz <[email protected]> S: Maintained W: https://github.com/linux-surface/surface-aggregator-module C: irc://chat.freenode.net/##linux-surface +F: Documentation/driver-api/surface_aggregator/ F: drivers/platform/surface/aggregator/ F: include/linux/surface_aggregator/
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 8/9 platform/surface: Add Surface Aggregator user-space interface
In reply to Maximilian LuzAdd a misc-device providing user-space access to the Surface Aggregator EC, mainly intended for debugging, testing, and reverse-engineering. This interface gives user-space applications the ability to send requests to the EC and receive the corresponding responses.
The device-file is managed by a pseudo platform-device and corresponding driver to avoid dependence on the dedicated bus, allowing it to be loaded in a minimal configuration.
A python library and scripts to access this device can be found at [1].
[1]: https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam
---
Changes in v1 (from RFC):
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- move from debugfs to proper misc-device
- move interface definitions to uapi header
- remove versioning
- allocate platform device dynamically
- prioritize EFAULT error in IOCTL return
- use ENOTTY error for unknown IOCTLs
- fix IOCTL compatibility for 32-bit user-space on 64-bit kernels
- mark request struct as __attribute__((__packed__))
- address issues when driver is unbound while file still open
Changes in v2:
- add ioctl-number.rst entry
- improve documentation
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix warnings and style issues
Changes in v3:
- export request flags in uapi header
- return ENOMEM instead of EFAULT on memory allocation failure
- add link to example tools to documentation and commit message
--- .../surface_aggregator/clients/cdev.rst | 87 +++++ .../surface_aggregator/clients/index.rst | 12 +- .../userspace-api/ioctl/ioctl-number.rst | 2 + MAINTAINERS | 2 + drivers/platform/surface/Kconfig | 17 + drivers/platform/surface/Makefile | 1 + .../surface/surface_aggregator_cdev.c | 303 ++++++++++++++++++ include/uapi/linux/surface_aggregator/cdev.h | 78 +++++ 8 files changed, 501 insertions(+), 1 deletion(-) create mode 100644 Documentation/driver-api/surface_aggregator/clients/cdev.rst create mode 100644 drivers/platform/surface/surface_aggregator_cdev.c create mode 100644 include/uapi/linux/surface_aggregator/cdev.h
Documentation/driver-api/surface_aggregator/clients/cdev.rst new file +87 -0
@@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +.. |u8| replace:: :c:type:`u8 <u8>` +.. |u16| replace:: :c:type:`u16 <u16>` +.. |ssam_cdev_request| replace:: :c:type:`struct ssam_cdev_request <ssam_cdev_request>` +.. |ssam_cdev_request_flags| replace:: :c:type:`enum ssam_cdev_request_flags <ssam_cdev_request_flags>` + +============================== +User-Space EC Interface (cdev) +============================== + +The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM +controller to allow for a (more or less) direct connection from user-space to +the SAM EC. It is intended to be used for development and debugging, and +therefore should not be used or relied upon in any other way. Note that this +module is not loaded automatically, but instead must be loaded manually. + +The provided interface is accessible through the ``/dev/surface/aggregator`` +device-file. All functionality of this interface is provided via IOCTLs. +These IOCTLs and their respective input/output parameter structs are defined in +``include/uapi/linux/surface_aggregator/cdev.h``. + +A small python library and scripts for accessing this interface can be found +at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam. + + +Controller IOCTLs +================= + +The following IOCTLs are provided: + +.. flat-table:: Controller IOCTLs + :widths: 1 1 1 1 4 + :header-rows: 1 + + * - Type + - Number + - Direction + - Name + - Description + + * - ``0xA5`` + - ``1`` + - ``WR`` + - ``REQUEST`` + - Perform synchronous SAM request. + + +``REQUEST`` +----------- + +Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``. + +Executes a synchronous SAM request. The request specification is passed in +as argument of type |ssam_cdev_request|, which is then written to/modified +by the IOCTL to return status and result of the request. + +Request payload data must be allocated separately and is passed in via the +``payload.data`` and ``payload.length`` members. If a response is required, +the response buffer must be allocated by the caller and passed in via the +``response.data`` member. The ``response.length`` member must be set to the +capacity of this buffer, or if no response is required, zero. Upon +completion of the request, the call will write the response to the response +buffer (if its capacity allows it) and overwrite the length field with the +actual size of the response, in bytes. + +Additionally, if the request has a response, this must be indicated via the +request flags, as is done with in-kernel requests. Request flags can be set +via the ``flags`` member and the values correspond to the values found in +|ssam_cdev_request_flags|. + +Finally, the status of the request itself is returned in the ``status`` +member (a negative errno value indicating failure). Note that failure +indication of the IOCTL is separated from failure indication of the request: +The IOCTL returns a negative status code if anything failed during setup of +the request (``-EFAULT``) or if the provided argument or any of its fields +are invalid (``-EINVAL``). In this case, the status value of the request +argument may be set, providing more detail on what went wrong (e.g. +``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL +will return with a zero status code in case the request has been set up, +submitted, and completed (i.e. handed back to user-space) successfully from +inside the IOCTL, but the request ``status`` member may still be negative in +case the actual execution of the request failed after it has been submitted. + +A full definition of the argument struct is provided below: + +.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h
Documentation/driver-api/surface_aggregator/clients/index.rst +11 -1
@@ -7,4 +7,14 @@ Client Driver Documentation This is the documentation for client drivers themselves. Refer to :doc:`../client` for documentation on how to write client drivers. -.. Place documentation for individual client drivers here. +.. toctree:: + :maxdepth: 1 + + cdev + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Documentation/userspace-api/ioctl/ioctl-number.rst +2 -0
@@ -323,6 +323,8 @@ Code Seq# Include File Comments <mailto:[email protected]> 0xA3 90-9F linux/dtlk.h 0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xA5 01 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator + <mailto:[email protected]> 0xAA 00-3F linux/uapi/linux/userfaultfd.h 0xAB 00-1F linux/nbd.h 0xAC 00-1F linux/raw.h
MAINTAINERS +2 -0
@@ -11699,7 +11699,9 @@ W: https://github.com/linux-surface/surface-aggregator-module C: irc://chat.freenode.net/##linux-surface F: Documentation/driver-api/surface_aggregator/ F: drivers/platform/surface/aggregator/ +F: drivers/platform/surface/surface_aggregator_cdev.c F: include/linux/surface_aggregator/ +F: include/uapi/linux/surface_aggregator/ MICROTEK X6 SCANNER M: Oliver Neukum <[email protected]>
drivers/platform/surface/Kconfig +17 -0
@@ -41,6 +41,23 @@ config SURFACE_3_POWER_OPREGION This driver provides support for ACPI operation region of the Surface 3 battery platform driver. +config SURFACE_AGGREGATOR_CDEV + tristate "Surface System Aggregator Module User-Space Interface" + depends on SURFACE_AGGREGATOR + help + Provides a misc-device interface to the Surface System Aggregator + Module (SSAM) controller. + + This option provides a module (called surface_aggregator_cdev), that, + when loaded, will add a client device (and its respective driver) to + the SSAM controller. Said client device manages a misc-device + interface (/dev/surface/aggregator), which can be used by user-space + tools to directly communicate with the SSAM EC by sending requests and + receiving the corresponding responses. + + The provided interface is intended for debugging and development only, + and should not be used otherwise. + config SURFACE_GPE tristate "Surface GPE/Lid Support Driver" depends on DMI
drivers/platform/surface/Makefile +1 -0
@@ -8,5 +8,6 @@ obj-$(CONFIG_SURFACE3_WMI) += surface3-wmi.o obj-$(CONFIG_SURFACE_3_BUTTON) += surface3_button.o obj-$(CONFIG_SURFACE_3_POWER_OPREGION) += surface3_power.o obj-$(CONFIG_SURFACE_AGGREGATOR) += aggregator/ +obj-$(CONFIG_SURFACE_AGGREGATOR_CDEV) += surface_aggregator_cdev.o obj-$(CONFIG_SURFACE_GPE) += surface_gpe.o obj-$(CONFIG_SURFACE_PRO3_BUTTON) += surfacepro3_button.o
drivers/platform/surface/surface_aggregator_cdev.c new file +303 -0
303 lines not on this page · raw message
include/uapi/linux/surface_aggregator/cdev.h new file +78 -0
78 lines not on this page · raw message
Signature · 1 line
2.29.2
Maximilian Luz
maintainerPATCH v3 9/9 platform/surface: Add Surface ACPI Notify driver
In reply to Maximilian LuzThe Surface ACPI Notify (SAN) device provides an ACPI interface to the Surface Aggregator EC, specifically the Surface Serial Hub interface. This interface allows EC requests to be made from ACPI code and can convert a subset of EC events back to ACPI notifications.
Specifically, this interface provides a GenericSerialBus operation region ACPI code can execute a request by writing the request command data and payload to this operation region and reading back the corresponding response via a write-then-read operation. Furthermore, this interface provides a _DSM method to be called when certain events from the EC have been received, essentially turning them into ACPI notifications.
The driver provided in this commit essentially takes care of translating the request data written to the operation region, executing the request, waiting for it to finish, and finally writing and translating back the response (if the request has one). Furthermore, this driver takes care of enabling the events handled via ACPI _DSM calls. Lastly, this driver also exposes an interface providing discrete GPU (dGPU) power-on notifications on the Surface Book 2, which are also received via the operation region interface (but not handled by the SAN driver directly), making them accessible to other drivers (such as a dGPU hot-plug driver that may be added later on).
On 5th and 6th generation Surface devices (Surface Pro 5/2017, Pro 6, Book 2, Laptop 1 and 2), the SAN interface provides full battery and thermal subsystem access, as well as other EC based functionality. On those models, battery and thermal sensor devices are implemented as standard ACPI devices of that type, however, forward ACPI calls to the corresponding Surface Aggregator EC request via the SAN interface and receive corresponding notifications (e.g. battery information change) from it. This interface is therefore required to provide said functionality on those devices.
---
Changes in v1 (from RFC):
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- fix invalid pointer calculation in san_evt_tmp
- add explicit dependency on CONFIG_ACPI
- remove default in Kconfig
Changes in v2:
- drop explicit dependency on ACPI in Kconfig
- use printk specifier for hex prefix instead of hard-coding it
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix warnings and style issues
--- .../surface_aggregator/clients/index.rst | 1 + .../surface_aggregator/clients/san.rst | 44 + MAINTAINERS | 2 + drivers/platform/surface/Kconfig | 19 + drivers/platform/surface/Makefile | 1 + .../platform/surface/surface_acpi_notify.c | 886 ++++++++++++++++++ include/linux/surface_acpi_notify.h | 39 + 7 files changed, 992 insertions(+) create mode 100644 Documentation/driver-api/surface_aggregator/clients/san.rst create mode 100644 drivers/platform/surface/surface_acpi_notify.c create mode 100644 include/linux/surface_acpi_notify.h
Documentation/driver-api/surface_aggregator/clients/index.rst +1 -0
@@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to :maxdepth: 1 cdev + san .. only:: subproject and html
Documentation/driver-api/surface_aggregator/clients/san.rst new file +44 -0
44 lines not on this page · raw message
MAINTAINERS +2 -0
@@ -11699,7 +11699,9 @@ W: https://github.com/linux-surface/surface-aggregator-module C: irc://chat.freenode.net/##linux-surface F: Documentation/driver-api/surface_aggregator/ F: drivers/platform/surface/aggregator/ +F: drivers/platform/surface/surface_acpi_notify.c F: drivers/platform/surface/surface_aggregator_cdev.c +F: include/linux/surface_acpi_notify.h F: include/linux/surface_aggregator/ F: include/uapi/linux/surface_aggregator/
drivers/platform/surface/Kconfig +19 -0
@@ -41,6 +41,25 @@ config SURFACE_3_POWER_OPREGION This driver provides support for ACPI operation region of the Surface 3 battery platform driver. +config SURFACE_ACPI_NOTIFY + tristate "Surface ACPI Notify Driver" + depends on SURFACE_AGGREGATOR + help + Surface ACPI Notify (SAN) driver for Microsoft Surface devices. + + This driver provides support for the ACPI interface (called SAN) of + the Surface System Aggregator Module (SSAM) EC. This interface is used + on 5th- and 6th-generation Microsoft Surface devices (including + Surface Pro 5 and 6, Surface Book 2, Surface Laptops 1 and 2, and in + reduced functionality on the Surface Laptop 3) to execute SSAM + requests directly from ACPI code, as well as receive SSAM events and + turn them into ACPI notifications. It essentially acts as a + translation layer between the SSAM controller and ACPI. + + Specifically, this driver may be needed for battery status reporting, + thermal sensor access, and real-time clock information, depending on + the Surface device in question. + config SURFACE_AGGREGATOR_CDEV tristate "Surface System Aggregator Module User-Space Interface" depends on SURFACE_AGGREGATOR
drivers/platform/surface/Makefile +1 -0
@@ -7,6 +7,7 @@ obj-$(CONFIG_SURFACE3_WMI) += surface3-wmi.o obj-$(CONFIG_SURFACE_3_BUTTON) += surface3_button.o obj-$(CONFIG_SURFACE_3_POWER_OPREGION) += surface3_power.o +obj-$(CONFIG_SURFACE_ACPI_NOTIFY) += surface_acpi_notify.o obj-$(CONFIG_SURFACE_AGGREGATOR) += aggregator/ obj-$(CONFIG_SURFACE_AGGREGATOR_CDEV) += surface_aggregator_cdev.o obj-$(CONFIG_SURFACE_GPE) += surface_gpe.o
drivers/platform/surface/surface_acpi_notify.c new file +886 -0
886 lines not on this page · raw message
include/linux/surface_acpi_notify.h new file +39 -0
@@ -0,0 +1,39 @@ +/* SPDX-License-Identifier: GPL-2.0+ */ +/* +* Interface for Surface ACPI Notify (SAN) driver. +* +* Provides access to discrete GPU notifications sent from ACPI via the SAN +* driver, which are not handled by this driver directly. +* +* Copyright (C) 2019-2020 Maximilian Luz <[email protected]> +*/ + +#ifndef _LINUX_SURFACE_ACPI_NOTIFY_H +#define _LINUX_SURFACE_ACPI_NOTIFY_H + +#include <linux/notifier.h> +#include <linux/types.h> + +/** +* struct san_dgpu_event - Discrete GPU ACPI event. +* @category: Category of the event. +* @target: Target ID of the event source. +* @command: Command ID of the event. +* @instance: Instance ID of the event source. +* @length: Length of the event's payload data (in bytes). +* @payload: Pointer to the event's payload data. +*/ +struct san_dgpu_event { +u8 category; +u8 target; +u8 command; +u8 instance; +u16 length; +u8 *payload; +}; + +int san_client_link (struct device *client); +int san_dgpu_notifier_register (struct notifier_block *nb); +int san_dgpu_notifier_unregister (struct notifier_block *nb); + +#endif /* _LINUX_SURFACE_ACPI_NOTIFY_H */
Signature · 1 line
2.29.2
Re: [PATCH v3 0/9] Add support for Microsoft Surface System Aggressor
In reply to Maximilian LuzOn 21. Dez 2020 by Mr Maximilian Luz:
Quoted 1 line
Here is version three of the Surface System Aggregator Module (SAM/SSAM)
... Read above what I initially misread the headline for. Can’t say I’m a big fan of M$. Trust me on that.
Hi,
Quoted 17 lines · Maximilian Luz
Hello,
Here is version three of the Surface System Aggregator Module (SAM/SSAM) driver series, adding initial support for the embedded controller on 5th and later generation Microsoft Surface devices. Initial support includes the ACPI interface to the controller, via which battery and thermal information is provided on some of these devices.
The first version and cover letter detailing what this series is about can be found at
https://lore.kernel.org/platform-driver-x86/[email protected]/
the previous version (v2) at
https://lore.kernel.org/platform-driver-x86/[email protected]/
Quoted 8 lines
This patch-set can also be found at the following repository and reference, if you prefer to look at a kernel tree instead of these emails:
https://github.com/linux-surface/kernel tags/s/surface-aggregator/v3
Thank you all for the feedback to and reviews of the previous versions, I hope I have addressed all comments.
Thank you for your patch-series, I've applied the series to my review-hans branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hans
This has been applied on top of:
"platform/surface: SURFACE_PLATFORMS should depend on ACPI"
As requested. Since my review-hans branch has been fast-forwarded to 5.11-rc1 there where some conflicts:
6/9 "platform/surface: aggregator: Add dedicated bus and device type" had conflicts in:scripts/mod/devicetable-offsets.cscripts/mod/file2alias.c
8/9 "platform/surface: Add Surface Aggregator user-space interface" had a conflict in:Documentation/userspace-api/ioctl/ioctl-number.rst
This conflict was caused by the addition of documentation of the sgx ioctls, these use 0xA4 as "Code" byte (shared with uapi/linux/tee.h), so the 0xA5 code for the sam cdev ioctl is still unique.
I'm pretty sure that I've properly resolved the conflicts, but please double-check.
Once I've run some tests on this branch the patches there will be added to the platform-drivers-x86/for-next branch and eventually will be included in the pdx86 pull-request to Linus for the next merge-window.
Regards,
Hans
Quoted 129 lines
Note: In v3, I have dropped the explicit dependency of the core module and driver on
CONFIG_ACPIdue to the incoming[PATCH] platform/surface:
SURFACE_PLATFORMSshould depend on ACPIThus, this series depends on said patch. This patch can be found at
https://www.spinics.net/lists/platform-driver-x86/msg23929.html
Changes in v1 (from RFC, overview):
- move to platform/surface
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- change user-space interface from debugfs to misc-device
- address issues in user-space interface
- fix typos in commit messages and documentation
- fix some bugs, address other issuesChanges in v2 (overview):
- simplify some code, mostly with regards to concurrency
- add architectural overview to documentation
- improve comments for documentation
- use printk specifier for hex prefix instead of hard-coding it
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix these and other style issuesChanges in v3 (overview):
- remove explicit dependency on ACPI as this is going to be covered byCONFIG_SURFACE_PLATFORMS
- simplify locking requirements
- help enforce locking requirements via lockdep assertions
- fix false-positive lockdep warning
- warn on event enablement reference counter exhaustion
- don't warn about unhandled event if event handling failed
- validate flags on request initialization
- improve documentation/add comments
- replace 'iff' with 'if' in documentation and commentsChanges regarding specific patches (and more details) can be found on the individual patch.
Maximilian Luz (9):
platform/surface: Add Surface Aggregator subsystem platform/surface: aggregator: Add control packet allocation caching platform/surface: aggregator: Add event item allocation caching platform/surface: aggregator: Add trace points platform/surface: aggregator: Add error injection capabilities platform/surface: aggregator: Add dedicated bus and device type
docs: driver-api: Add Surface Aggregator subsystem documentation platform/surface: Add Surface Aggregator user-space interface platform/surface: Add Surface ACPI Notify driverDocumentation/driver-api/index.rst | 1 + .../surface_aggregator/client-api.rst | 38 + .../driver-api/surface_aggregator/client.rst | 393 +++ .../surface_aggregator/clients/cdev.rst | 87 + .../surface_aggregator/clients/index.rst | 21 + .../surface_aggregator/clients/san.rst | 44 + .../driver-api/surface_aggregator/index.rst | 21 + .../surface_aggregator/internal-api.rst | 67 + .../surface_aggregator/internal.rst | 577 ++++ .../surface_aggregator/overview.rst | 77 + .../driver-api/surface_aggregator/ssh.rst | 344 +++ .../userspace-api/ioctl/ioctl-number.rst | 2 + MAINTAINERS | 13 + drivers/platform/surface/Kconfig | 38 + drivers/platform/surface/Makefile | 3 + drivers/platform/surface/aggregator/Kconfig | 68 + drivers/platform/surface/aggregator/Makefile | 17 + drivers/platform/surface/aggregator/bus.c | 415 +++ drivers/platform/surface/aggregator/bus.h | 27 + .../platform/surface/aggregator/controller.c | 2579 +++++++++++++++++ .../platform/surface/aggregator/controller.h | 285 ++ drivers/platform/surface/aggregator/core.c | 839 ++++++ .../platform/surface/aggregator/ssh_msgb.h | 205 ++ .../surface/aggregator/ssh_packet_layer.c | 2057 +++++++++++++ .../surface/aggregator/ssh_packet_layer.h | 190 ++ .../platform/surface/aggregator/ssh_parser.c | 228 ++ .../platform/surface/aggregator/ssh_parser.h | 154 + .../surface/aggregator/ssh_request_layer.c | 1264 ++++++++ .../surface/aggregator/ssh_request_layer.h | 143 + drivers/platform/surface/aggregator/trace.h | 632 ++++ .../platform/surface/surface_acpi_notify.c | 886 ++++++ .../surface/surface_aggregator_cdev.c | 303 ++ include/linux/mod_devicetable.h | 18 + include/linux/surface_acpi_notify.h | 39 + include/linux/surface_aggregator/controller.h | 824 ++++++ include/linux/surface_aggregator/device.h | 423 +++ include/linux/surface_aggregator/serial_hub.h | 672 +++++ include/uapi/linux/surface_aggregator/cdev.h | 78 + scripts/mod/devicetable-offsets.c | 8 + scripts/mod/file2alias.c | 23 + 40 files changed, 14103 insertions(+) create mode 100644 Documentation/driver-api/surface_aggregator/client-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/client.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/cdev.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/clients/san.rst create mode 100644 Documentation/driver-api/surface_aggregator/index.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal-api.rst create mode 100644 Documentation/driver-api/surface_aggregator/internal.rst create mode 100644 Documentation/driver-api/surface_aggregator/overview.rst create mode 100644 Documentation/driver-api/surface_aggregator/ssh.rst create mode 100644 drivers/platform/surface/aggregator/Kconfig create mode 100644 drivers/platform/surface/aggregator/Makefile create mode 100644 drivers/platform/surface/aggregator/bus.c create mode 100644 drivers/platform/surface/aggregator/bus.h create mode 100644 drivers/platform/surface/aggregator/controller.c create mode 100644 drivers/platform/surface/aggregator/controller.h create mode 100644 drivers/platform/surface/aggregator/core.c create mode 100644 drivers/platform/surface/aggregator/ssh_msgb.h create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_packet_layer.h create mode 100644 drivers/platform/surface/aggregator/ssh_parser.c create mode 100644 drivers/platform/surface/aggregator/ssh_parser.h create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.c create mode 100644 drivers/platform/surface/aggregator/ssh_request_layer.h create mode 100644 drivers/platform/surface/aggregator/trace.h create mode 100644 drivers/platform/surface/surface_acpi_notify.c create mode 100644 drivers/platform/surface/surface_aggregator_cdev.c create mode 100644 include/linux/surface_acpi_notify.h create mode 100644 include/linux/surface_aggregator/controller.h create mode 100644 include/linux/surface_aggregator/device.h create mode 100644 include/linux/surface_aggregator/serial_hub.h create mode 100644 include/uapi/linux/surface_aggregator/cdev.h
Maximilian Luz
maintainerQuoted 43 lines · Hans de Goede
Hi,
Quoted 17 lines · Maximilian Luz
Hello,
Here is version three of the Surface System Aggregator Module (SAM/SSAM) driver series, adding initial support for the embedded controller on 5th and later generation Microsoft Surface devices. Initial support includes the ACPI interface to the controller, via which battery and thermal information is provided on some of these devices.
The first version and cover letter detailing what this series is about can be found at
https://lore.kernel.org/platform-driver-x86/[email protected]/the previous version (v2) at
https://lore.kernel.org/platform-driver-x86/[email protected]/Quoted 8 lines
This patch-set can also be found at the following repository and reference, if you prefer to look at a kernel tree instead of these emails:
https://github.com/linux-surface/kernel tags/s/surface-aggregator/v3
Thank you all for the feedback to and reviews of the previous versions, I hope I have addressed all comments.
Thank you for your patch-series, I've applied the series to my review-hans branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=review-hansThis has been applied on top of:
"platform/surface:SURFACE_PLATFORMSshould depend on ACPI"As requested. Since my review-hans branch has been fast-forwarded to 5.11-rc1 there where some conflicts:
6/9 "platform/surface: aggregator: Add dedicated bus and device type" had conflicts in:
scripts/mod/devicetable-offsets.cscripts/mod/file2alias.c
Quoted 8 lines
8/9 "platform/surface: Add Surface Aggregator user-space interface" had a conflict in:
Documentation/userspace-api/ioctl/ioctl-number.rstThis conflict was caused by the addition of documentation of the sgx ioctls, these use
0xA4as "Code" byte (shared withuapi/linux/tee.h), so the0xA5code for the sam cdev ioctl is still unique.I'm pretty sure that I've properly resolved the conflicts, but please double-check.
Everything looks good to me. I'll compile your branch and run some tests just in case, but I really don't expect there to be any problems. In the unlikely event that I find anything, I'll submit a patch.
Quoted 4 lines
Once I've run some tests on this branch the patches there will be added to the platform-drivers-x86/for-next branch and eventually will be included in the pdx86 pull-request to Linus for the next merge-window.
Thank you (and all others involved in reviewing this).
Regards,
Max
Quoted 137 lines
Regards,
Hans
Quoted 129 lines
Note: In v3, I have dropped the explicit dependency of the core module and driver on
CONFIG_ACPIdue to the incoming[PATCH] platform/surface:
SURFACE_PLATFORMSshould depend on ACPIThus, this series depends on said patch. This patch can be found at
https://www.spinics.net/lists/platform-driver-x86/msg23929.htmlChanges in v1 (from RFC, overview):
- move to platform/surface
- add copyright lines
- change SPDX identifier to GPL-2.0+ (was GPL-2.0-or-later)
- change user-space interface from debugfs to misc-device
- address issues in user-space interface
- fix typos in commit messages and documentation
- fix some bugs, address other issuesChanges in v2 (overview):
- simplify some code, mostly with regards to concurrency
- add architectural overview to documentation
- improve comments for documentation
- use printk specifier for hex prefix instead of hard-coding it
- spell check comments and strings, fix typos
- unify comment style
- run checkpatch --strict, fix these and other style issuesChanges in v3 (overview):
- remove explicit dependency on ACPI as this is going to be covered byCONFIG_SURFACE_PLATFORMS
- simplify locking requirements
- help enforce locking requirements via lockdep assertions
- fix false-positive lockdep warning
- warn on event enablement reference counter exhaustion
- don't warn about unhandled event if event handling failed
- validate flags on request initialization
- improve documentation/add comments
- replace 'iff' with 'if' in documentation and commentsChanges regarding specific patches (and more details) can be found on the individual patch.
Maximilian Luz (9):
platform/surface: Add Surface Aggregator subsystem platform/surface: aggregator: Add control packet allocation caching platform/surface: aggregator: Add event item allocation caching platform/surface: aggregator: Add trace points platform/surface: aggregator: Add error injection capabilities platform/surface: aggregator: Add dedicated bus and device type
docs: driver-api: Add Surface Aggregator subsystem documentation platform/surface: Add Surface Aggregator user-space interface platform/surface: Add Surface ACPI Notify driverDocumentation/driver-api/index.rst | 1 + .../surface_aggregator/client-api.rst | 38 + .../driver-api/surface_aggregator/client.rst | 393 +++ .../surface_aggregator/clients/cdev.rst | 87 + .../surface_aggregator/clients/index.rst | 21 + .../surface_aggregator/clients/san.rst | 44 + .../driver-api/surface_aggregator/index.rst | 21 + .../surface_aggregator/internal-api.rst | 67 + .../surface_aggregator/internal.rst | 577 ++++ .../surface_aggregator/overview.rst | 77 + .../driver-api/surface_aggregator/ssh.rst | 344 +++ .../userspace-api/ioctl/ioctl-number.rst | 2 + MAINTAINERS | 13 + drivers/platform/surface/Kconfig | 38 + drivers/platform/surface/Makefile | 3 + drivers/platform/surface/aggregator/Kconfig | 68 + drivers/platform/surface/aggregator/Makefile | 17 + drivers/platform/surface/aggregator/bus.c | 415 +++ drivers/platform/surface/aggregator/bus.h | 27 + .../platform/surface/aggregator/controller.c | 2579 +++++++++++++++++ .../platform/surface/aggregator/controller.h | 285 ++ drivers/platform/surface/aggregator/core.c | 839 ++++++ .../platform/surface/aggregator/ssh_msgb.h | 205 ++ .../surface/aggregator/ssh_packet_layer.c | 2057 +++++++++++++ .../surface/aggregator/ssh_packet_layer.h | 190 ++ .../platform/surface/aggregator/ssh_parser.c | 228 ++ .../platform/surface/aggregator/ssh_parser.h | 154 + .../surface/aggregator/ssh_request_layer.c | 1264 ++++++++ .../surface/aggregator/ssh_request_layer.h | 143 + drivers/platform/surface/aggregator/trace.h | 632 ++++ .../platform/surface/surface_acpi_notify.c | 886 ++++++ .../surface/surface_aggregator_cdev.c | 303 ++ include/linux/mod_devicetable.h | 18 + include/linux/surface_acpi_notify.h | 39 + include/linux/surface_aggregator/controller.h | 824 ++++++ include/linux/surface_aggregator/device.h | 423 +++ include/linux/surface_aggregator/serial_hub.h | 672 +++++ include/uapi/linux/surface_aggregator/cdev.h | 78 + scripts/mod/devicetable-offsets.c | 8 + scripts/mod/file2alias.c | 23 + 40 files changed, 14103 insertions(+)create mode 100644
Documentation/driver-api/surface_aggregator/client-api.rstcreate mode 100644Documentation/driver-api/surface_aggregator/client.rstcreate mode 100644Documentation/driver-api/surface_aggregator/clients/cdev.rstcreate mode 100644Documentation/driver-api/surface_aggregator/clients/index.rstcreate mode 100644Documentation/driver-api/surface_aggregator/clients/san.rstcreate mode 100644Documentation/driver-api/surface_aggregator/index.rstcreate mode 100644Documentation/driver-api/surface_aggregator/internal-api.rstcreate mode 100644Documentation/driver-api/surface_aggregator/internal.rstcreate mode 100644Documentation/driver-api/surface_aggregator/overview.rstcreate mode 100644Documentation/driver-api/surface_aggregator/ssh.rstcreate mode 100644drivers/platform/surface/aggregator/Kconfigcreate mode 100644drivers/platform/surface/aggregator/Makefilecreate mode 100644drivers/platform/surface/aggregator/bus.c
create mode 100644drivers/platform/surface/aggregator/bus.h
create mode 100644drivers/platform/surface/aggregator/controller.ccreate mode 100644drivers/platform/surface/aggregator/controller.hcreate mode 100644drivers/platform/surface/aggregator/core.ccreate mode 100644drivers/platform/surface/aggregator/ssh_msgb.hcreate mode 100644drivers/platform/surface/aggregator/ssh_packet_layer.ccreate mode 100644drivers/platform/surface/aggregator/ssh_packet_layer.hcreate mode 100644drivers/platform/surface/aggregator/ssh_parser.ccreate mode 100644drivers/platform/surface/aggregator/ssh_parser.hcreate mode 100644drivers/platform/surface/aggregator/ssh_request_layer.ccreate mode 100644drivers/platform/surface/aggregator/ssh_request_layer.hcreate mode 100644drivers/platform/surface/aggregator/trace.hcreate mode 100644drivers/platform/surface/surface_acpi_notify.ccreate mode 100644drivers/platform/surface/surface_aggregator_cdev.ccreate mode 100644include/linux/surface_acpi_notify.h
create mode 100644include/linux/surface_aggregator/controller.hcreate mode 100644include/linux/surface_aggregator/device.h
create mode 100644include/linux/surface_aggregator/serial_hub.hcreate mode 100644include/uapi/linux/surface_aggregator/cdev.h