Re: [PATCH RESEND RESEND] Input: evdev - add event-mask API
From: David Herrmann <hidden>
Date: 2014-11-04 10:51:35
Hi Dmitry Sorry for the delay, back from holiday now. On Fri, Oct 10, 2014 at 12:52 AM, Dmitry Torokhov [off-list ref] wrote:
quoted hunk ↗ jump to hunk
diff -u b/include/uapi/linux/input.h b/include/uapi/linux/input.h--- b/include/uapi/linux/input.h +++ b/include/uapi/linux/input.h@@ -161,53 +161,59 @@ #define EVIOCREVOKE _IOW('E', 0x91, int) /* Revoke device access */ /** - * EVIOCGMASK - Retrieve current event-mask + * EVIOCGMASK - Retrieve current event mask * - * This retrieves the current event-mask for a specific event-type. The - * argument must be of type "struct input_mask" and specifies the event-type to - * query, the receive buffer and the size of the receive buffer. - * - * The event-mask is a per-client mask that specifies which events are forwarded - * to the client. Each event-code is represented by a single bit in the - * event-mask. If the bit is set, the event is passed to the client normally. - * Otherwise, the event is filtered and and will never be queued on the - * client's receive buffer. - * Event-masks do not affect global state of an input-device. They only affect - * the open-file they're applied on. Each open-file (i.e, file-description) can - * have a different event-mask. - * - * The default event-mask for a client has all bits set, i.e. all events are - * forwarded to the client. If a kernel is queried for an unknown event-type - * or if the receive buffer is larger than the number of event-codes known to - * the kernel, the kernel returns all zeroes for those codes. + * This ioctl allows user to retrieve the current event mask for specific + * event type. The argument must be of type "struct input_mask" and + * specifies the event type to query, the address of the receive buffer and + * the size of the receive buffer. + * + * The event mask is a per-client mask that specifies which events are + * forwarded to the client. Each event code is represented by a single bit + * in the event mask. If the bit is set, the event is passed to the client + * normally. Otherwise, the event is filtered and will never be queued on + * the client's receive buffer. + * + * Event masks do not affect global state of the input device. They only + * affect the file descriptor they are applied to. + * + * The default event mask for a client has all bits set, i.e. all events + * are forwarded to the client. If kernel is queried for an unknown + * event type or if the receive buffer is larger than the number of + * event codes known to the kernel, the kernel returns all zeroes for those + * codes. * * At maximum, codes_size bytes are copied. * - * This ioctl may fail with ENODEV in case the file is revoked, EFAULT - * if the receive-buffer points to invalid memory, or EINVAL if the kernel - * does not implement the ioctl. + * This ioctl may fail with ENODEV in case the descriptor is revoked, + * EFAULT if the receive buffer points to invalid memory, or EINVAL if the + * kernel does not implement the ioctl.
I fixed everything up, except for this hunk. A "descriptor" cannot be revoked, it's always the "description" that is revoked (file-descriptor vs. file-description). I'm not sure what name to use here. "file-description" would serve best, I guess, but it's not that commonly used (nor understood). It's defined properly by POSIX, though. Comments? Thanks David
*/
+
#define EVIOCGMASK _IOR('E', 0x92, struct input_mask) /* Get event-masks */
/**
- * EVIOCSMASK - Set event-mask
+ * EVIOCSMASK - Set event mask
*
- * This is the counterpart to EVIOCGMASK. Instead of receiving the current
- * event-mask, this changes the client's event-mask for a specific type. See
- * EVIOCGMASK for a description of event-masks and the argument-type.
- *
- * This ioctl provides full forward-compatibility. If the passed event-type is
- * unknown to the kernel, or if the number of codes is bigger than known to the
- * kernel, the ioctl is still accepted and applied. However, any unknown codes
- * are left untouched and stay cleared. That means, the kernel always filters
- * unknown codes regardless of what the client requests.
- * If the new mask doesn't cover all known event-codes, all remaining codes are
- * automatically cleared and thus filtered.
+ * This ioctl is the counterpart to EVIOCGMASK. Instead of receiving the
+ * current event mask, this changes the client's event mask for a specific
+ * type. See EVIOCGMASK for a description of event-masks and the
+ * argument-type.
+ *
+ * This ioctl provides full forward compatibility. If the passed event type
+ * is unknown to the kernel, or if the number of event codes specified in
+ * the mask is bigger than what is known to the kernel, the ioctl is still
+ * accepted and applied. However, any unknown codes are left untouched and
+ * stay cleared. That means, the kernel always filters unknown codes
+ * regardless of what the client requests. If the new mask doesn't cover
+ * all known event-codes, all remaining codes are automatically cleared and
+ * thus filtered.
*
* This ioctl may fail with ENODEV in case the file is revoked. EFAULT is
- * returned if the receive-buffer points to invalid memory. EINVAL is returned
- * if the kernel does not implement the ioctl.
+ * returned if the receive-buffer points to invalid memory. EINVAL is
+ * returned if the kernel does not implement the ioctl.
*/
+
#define EVIOCSMASK _IOW('E', 0x93, struct input_mask) /* Set event-masks */
#define EVIOCSCLOCKID _IOW('E', 0xa0, int) /* Set clockid to be used for timestamps */