1 | /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */ |
2 | /* |
3 | * Surface System Aggregator Module (SSAM) user-space EC interface. |
4 | * |
5 | * Definitions, structs, and IOCTLs for the /dev/surface/aggregator misc |
6 | * device. This device provides direct user-space access to the SSAM EC. |
7 | * Intended for debugging and development. |
8 | * |
9 | * Copyright (C) 2020-2021 Maximilian Luz <luzmaximilian@gmail.com> |
10 | */ |
11 | |
12 | #ifndef _UAPI_LINUX_SURFACE_AGGREGATOR_CDEV_H |
13 | #define _UAPI_LINUX_SURFACE_AGGREGATOR_CDEV_H |
14 | |
15 | #include <linux/ioctl.h> |
16 | #include <linux/types.h> |
17 | |
18 | /** |
19 | * enum ssam_cdev_request_flags - Request flags for SSAM cdev request IOCTL. |
20 | * |
21 | * @SSAM_CDEV_REQUEST_HAS_RESPONSE: |
22 | * Specifies that the request expects a response. If not set, the request |
23 | * will be directly completed after its underlying packet has been |
24 | * transmitted. If set, the request transport system waits for a response |
25 | * of the request. |
26 | * |
27 | * @SSAM_CDEV_REQUEST_UNSEQUENCED: |
28 | * Specifies that the request should be transmitted via an unsequenced |
29 | * packet. If set, the request must not have a response, meaning that this |
30 | * flag and the %SSAM_CDEV_REQUEST_HAS_RESPONSE flag are mutually |
31 | * exclusive. |
32 | */ |
33 | enum ssam_cdev_request_flags { |
34 | SSAM_CDEV_REQUEST_HAS_RESPONSE = 0x01, |
35 | SSAM_CDEV_REQUEST_UNSEQUENCED = 0x02, |
36 | }; |
37 | |
38 | /** |
39 | * struct ssam_cdev_request - Controller request IOCTL argument. |
40 | * @target_category: Target category of the SAM request. |
41 | * @target_id: Target ID of the SAM request. |
42 | * @command_id: Command ID of the SAM request. |
43 | * @instance_id: Instance ID of the SAM request. |
44 | * @flags: Request flags (see &enum ssam_cdev_request_flags). |
45 | * @status: Request status (output). |
46 | * @payload: Request payload (input data). |
47 | * @payload.data: Pointer to request payload data. |
48 | * @payload.length: Length of request payload data (in bytes). |
49 | * @response: Request response (output data). |
50 | * @response.data: Pointer to response buffer. |
51 | * @response.length: On input: Capacity of response buffer (in bytes). |
52 | * On output: Length of request response (number of bytes |
53 | * in the buffer that are actually used). |
54 | */ |
55 | struct ssam_cdev_request { |
56 | __u8 target_category; |
57 | __u8 target_id; |
58 | __u8 command_id; |
59 | __u8 instance_id; |
60 | __u16 flags; |
61 | __s16 status; |
62 | |
63 | struct { |
64 | __u64 data; |
65 | __u16 length; |
66 | __u8 __pad[6]; |
67 | } payload; |
68 | |
69 | struct { |
70 | __u64 data; |
71 | __u16 length; |
72 | __u8 __pad[6]; |
73 | } response; |
74 | } __attribute__((__packed__)); |
75 | |
76 | /** |
77 | * struct ssam_cdev_notifier_desc - Notifier descriptor. |
78 | * @priority: Priority value determining the order in which notifier |
79 | * callbacks will be called. A higher value means higher |
80 | * priority, i.e. the associated callback will be executed |
81 | * earlier than other (lower priority) callbacks. |
82 | * @target_category: The event target category for which this notifier should |
83 | * receive events. |
84 | * |
85 | * Specifies the notifier that should be registered or unregistered, |
86 | * specifically with which priority and for which target category of events. |
87 | */ |
88 | struct ssam_cdev_notifier_desc { |
89 | __s32 priority; |
90 | __u8 target_category; |
91 | } __attribute__((__packed__)); |
92 | |
93 | /** |
94 | * struct ssam_cdev_event_desc - Event descriptor. |
95 | * @reg: Registry via which the event will be enabled/disabled. |
96 | * @reg.target_category: Target category for the event registry requests. |
97 | * @reg.target_id: Target ID for the event registry requests. |
98 | * @reg.cid_enable: Command ID for the event-enable request. |
99 | * @reg.cid_disable: Command ID for the event-disable request. |
100 | * @id: ID specifying the event. |
101 | * @id.target_category: Target category of the event source. |
102 | * @id.instance: Instance ID of the event source. |
103 | * @flags: Flags used for enabling the event. |
104 | * |
105 | * Specifies which event should be enabled/disabled and how to do that. |
106 | */ |
107 | struct ssam_cdev_event_desc { |
108 | struct { |
109 | __u8 target_category; |
110 | __u8 target_id; |
111 | __u8 cid_enable; |
112 | __u8 cid_disable; |
113 | } reg; |
114 | |
115 | struct { |
116 | __u8 target_category; |
117 | __u8 instance; |
118 | } id; |
119 | |
120 | __u8 flags; |
121 | } __attribute__((__packed__)); |
122 | |
123 | /** |
124 | * struct ssam_cdev_event - SSAM event sent by the EC. |
125 | * @target_category: Target category of the event source. See &enum ssam_ssh_tc. |
126 | * @target_id: Target ID of the event source. |
127 | * @command_id: Command ID of the event. |
128 | * @instance_id: Instance ID of the event source. |
129 | * @length: Length of the event payload in bytes. |
130 | * @data: Event payload data. |
131 | */ |
132 | struct ssam_cdev_event { |
133 | __u8 target_category; |
134 | __u8 target_id; |
135 | __u8 command_id; |
136 | __u8 instance_id; |
137 | __u16 length; |
138 | __u8 data[]; |
139 | } __attribute__((__packed__)); |
140 | |
141 | #define SSAM_CDEV_REQUEST _IOWR(0xA5, 1, struct ssam_cdev_request) |
142 | #define SSAM_CDEV_NOTIF_REGISTER _IOW(0xA5, 2, struct ssam_cdev_notifier_desc) |
143 | #define SSAM_CDEV_NOTIF_UNREGISTER _IOW(0xA5, 3, struct ssam_cdev_notifier_desc) |
144 | #define SSAM_CDEV_EVENT_ENABLE _IOW(0xA5, 4, struct ssam_cdev_event_desc) |
145 | #define SSAM_CDEV_EVENT_DISABLE _IOW(0xA5, 5, struct ssam_cdev_event_desc) |
146 | |
147 | #endif /* _UAPI_LINUX_SURFACE_AGGREGATOR_CDEV_H */ |
148 | |