| Message ID | 1463916983-12562-3-git-send-email-pali.rohar@gmail.com (mailing list archive) |
|---|---|
| State | Superseded, archived |
| Headers | show |
> Signed-off-by: Pali Rohár <pali.rohar@gmail.com> My guess is that Darren won't let you off without at least a short commit message. > --- > drivers/platform/x86/dell-wmi.c | 31 ++++++++++++++++++------------- > 1 file changed, 18 insertions(+), 13 deletions(-) > > diff --git a/drivers/platform/x86/dell-wmi.c b/drivers/platform/x86/dell-wmi.c > index 4d23c91..363d927 100644 > --- a/drivers/platform/x86/dell-wmi.c > +++ b/drivers/platform/x86/dell-wmi.c > @@ -86,31 +86,32 @@ static const struct dmi_system_id dell_wmi_smbios_list[] __initconst = { > */ > > static const struct key_entry dell_wmi_legacy_keymap[] __initconst = { > - { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, > > - { KE_KEY, 0xe009, { KEY_EJECTCD } }, > + { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, > > - /* These also contain the brightness level at offset 6 */ > - { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, > - { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, > + /* These also contain the brightness level after key code */ > + { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, > + { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, These two entries were left unsorted. > > /* Battery health status button */ > - { KE_KEY, 0xe007, { KEY_BATTERY } }, > + { KE_KEY, 0xe007, { KEY_BATTERY } }, > > - /* Radio devices state change */ > + /* Radio devices state change, also contains additional information */ > { KE_IGNORE, 0xe008, { KEY_RFKILL } }, > > - /* The next device is at offset 6, the active devices are at > - offset 8 and the attached devices at offset 10 */ > - { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, > + { KE_KEY, 0xe009, { KEY_EJECTCD } }, > > + /* After key code is: next device, active devices, attached devices */ > + { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, > + > + /* Also contains keyboard illumination level after key code */ I know I'm being really pedantic here, but as this is a cleanup patch, maybe it makes sense to unify the comments a bit? After this patch is applied, the comments are: /* These also contain the brightness level after key code */ /* Radio devices state change, also contains additional information */ /* After key code is: next device, active devices, attached devices */ /* Also contains keyboard illumination level after key code */ How about changing them to something like: /* Key code is followed by brightness level */ /* Radio devices state change, key code is followed by additional information */ /* Key code is followed by: next device, active devices, attached devices */ /* Key code is followed by keyboard illumination level */ And looking at the bigger picture, do you think these comments (especially the generic one: "also contains additional information") are actually needed? Anything that follows the key code is ignored by kernel code anyway.
On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > My guess is that Darren won't let you off without at least a short > commit message. I have no idea what else to write. I think that description is enough. > > --- > > drivers/platform/x86/dell-wmi.c | 31 ++++++++++++++++++------------- > > 1 file changed, 18 insertions(+), 13 deletions(-) > > > > diff --git a/drivers/platform/x86/dell-wmi.c b/drivers/platform/x86/dell-wmi.c > > index 4d23c91..363d927 100644 > > --- a/drivers/platform/x86/dell-wmi.c > > +++ b/drivers/platform/x86/dell-wmi.c > > @@ -86,31 +86,32 @@ static const struct dmi_system_id dell_wmi_smbios_list[] __initconst = { > > */ > > > > static const struct key_entry dell_wmi_legacy_keymap[] __initconst = { > > - { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, > > > > - { KE_KEY, 0xe009, { KEY_EJECTCD } }, > > + { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, > > > > - /* These also contain the brightness level at offset 6 */ > > - { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, > > - { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, > > + /* These also contain the brightness level after key code */ > > + { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, > > + { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, > > These two entries were left unsorted. Thanks, I will fix it. > > > > /* Battery health status button */ > > - { KE_KEY, 0xe007, { KEY_BATTERY } }, > > + { KE_KEY, 0xe007, { KEY_BATTERY } }, > > > > - /* Radio devices state change */ > > + /* Radio devices state change, also contains additional information */ > > { KE_IGNORE, 0xe008, { KEY_RFKILL } }, > > > > - /* The next device is at offset 6, the active devices are at > > - offset 8 and the attached devices at offset 10 */ > > - { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, > > + { KE_KEY, 0xe009, { KEY_EJECTCD } }, > > > > + /* After key code is: next device, active devices, attached devices */ > > + { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, > > + > > + /* Also contains keyboard illumination level after key code */ > > I know I'm being really pedantic here, but as this is a cleanup patch, > maybe it makes sense to unify the comments a bit? After this patch is > applied, the comments are: > > /* These also contain the brightness level after key code */ > /* Radio devices state change, also contains additional information */ > /* After key code is: next device, active devices, attached devices */ > /* Also contains keyboard illumination level after key code */ > > How about changing them to something like: > > /* Key code is followed by brightness level */ > /* Radio devices state change, key code is followed by additional information */ > /* Key code is followed by: next device, active devices, attached devices */ > /* Key code is followed by keyboard illumination level */ No problem, I will change it. > And looking at the bigger picture, do you think these comments > (especially the generic one: "also contains additional information") are > actually needed? Anything that follows the key code is ignored by > kernel code anyway. Currently it is ignored, but it is the only documentation which we have for these WMI events. Somebody in future can use these documentation information and extend code to process also these information...
On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote: > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > > > My guess is that Darren won't let you off without at least a short > > commit message. > > I have no idea what else to write. I think that description is enough. There is always something. For example, why? See Documentation/SubmittingPatches section "14) The canonical patch format" for an explanation. "Traceability" of changes is important. If it's worth preparing the patch, it's worth documenting why.
On Wednesday 08 June 2016 21:48:24 Darren Hart wrote: > On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote: > > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > > > > > My guess is that Darren won't let you off without at least a > > > short commit message. > > > > I have no idea what else to write. I think that description is > > enough. > > There is always something. For example, why? See > Documentation/SubmittingPatches section "14) The canonical patch > format" for an explanation. > > "Traceability" of changes is important. If it's worth preparing the > patch, it's worth documenting why. In my opinion current description is enough and cover everything what this patch is doing. I think it is clear from my description what this patch is doing and so it is documented. But if it is not clear and something is missing, let me know or show what is wrong and how you change it... It is just my assumption that "Sort WMI event codes and update comments" is clear...
On Wed, Jun 08, 2016 at 09:57:26PM +0200, Pali Rohár wrote: > On Wednesday 08 June 2016 21:48:24 Darren Hart wrote: > > On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote: > > > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > > > > > > > My guess is that Darren won't let you off without at least a > > > > short commit message. > > > > > > I have no idea what else to write. I think that description is > > > enough. > > > > There is always something. For example, why? See > > Documentation/SubmittingPatches section "14) The canonical patch > > format" for an explanation. > > > > "Traceability" of changes is important. If it's worth preparing the > > patch, it's worth documenting why. > > In my opinion current description is enough and cover everything what > this patch is doing. I think it is clear from my description what this > patch is doing and so it is documented. > > But if it is not clear and something is missing, let me know or show > what is wrong and how you change it... It is just my assumption that > "Sort WMI event codes and update comments" is clear... The patch summary accurately states what it does. It does not explain why it does it, or why it is necessary. I understand this is a trivial change, but also understand that both maintainers and people doing maintenance and regression analysis will appreciate understanding the motivation and intent of the patch, in addition to the content of the patch. From the maintainer perspective, whether we have 20 or 200 patches to review, we will naturally merge the ones that require the least effort first. This maximizes our efficiency and benefits the most people with what time we have available. For many of us, this is our nights and weekends (guessing that's the case for you as well). It is in the submitter's best interest to take the time document the why, what, and how of each patch in a way that minimizes the effort on the part of the maintainer to decide if the patch should be merged. It is also a matter of scale, if every patch conforms to these guidelines, the workflow is much more efficient. In this case, I don't know why you decided to sort the event codes or update the comments. I assume the comments were wrong before, but maybe something changed. Do you care about alphabetically order or optimizing the switch statements? Is it purely for legibility? Etc. If that isn't sufficient, then just do it out of self-interest, because I will not send patches to Linus that do not provide both a summary and a description in the commit which meet the guidelines of section 14 referenced above. Thanks,
On Wednesday 08 June 2016 22:15:18 Darren Hart wrote: > On Wed, Jun 08, 2016 at 09:57:26PM +0200, Pali Rohár wrote: > > On Wednesday 08 June 2016 21:48:24 Darren Hart wrote: > > > On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote: > > > > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > > > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > > > > > > > > > My guess is that Darren won't let you off without at least a > > > > > short commit message. > > > > > > > > I have no idea what else to write. I think that description is > > > > enough. > > > > > > There is always something. For example, why? See > > > Documentation/SubmittingPatches section "14) The canonical patch > > > format" for an explanation. > > > > > > "Traceability" of changes is important. If it's worth preparing > > > the patch, it's worth documenting why. > > > > In my opinion current description is enough and cover everything > > what this patch is doing. I think it is clear from my description > > what this patch is doing and so it is documented. > > > > But if it is not clear and something is missing, let me know or > > show what is wrong and how you change it... It is just my > > assumption that "Sort WMI event codes and update comments" is > > clear... > > The patch summary accurately states what it does. It does not explain > why it does it, or why it is necessary. I understand this is a > trivial change, but also understand that both maintainers and people > doing maintenance and regression analysis will appreciate > understanding the motivation and intent of the patch, in addition to > the content of the patch. > > From the maintainer perspective, whether we have 20 or 200 patches to > review, we will naturally merge the ones that require the least > effort first. This maximizes our efficiency and benefits the most > people with what time we have available. For many of us, this is our > nights and weekends (guessing that's the case for you as well). It > is in the submitter's best interest to take the time document the > why, what, and how of each patch in a way that minimizes the effort > on the part of the maintainer to decide if the patch should be > merged. It is also a matter of scale, if every patch conforms to > these guidelines, the workflow is much more efficient. > > In this case, I don't know why you decided to sort the event codes or > update the comments. I assume the comments were wrong before, but > maybe something changed. Do you care about alphabetically order or > optimizing the switch statements? Is it purely for legibility? Etc. > > If that isn't sufficient, then just do it out of self-interest, > because I will not send patches to Linus that do not provide both a > summary and a description in the commit which meet the guidelines of > section 14 referenced above. > > Thanks, I fully understand your maintainer perspective. I just though that my one line explain everything what is needed about my patch... So do you want to include reason for my patch? What about this additional description? === For better readability of keymap table, sort events by codes and also update comments for events to be more informative. ===
On Wed, Jun 08, 2016 at 10:27:20PM +0200, Pali Rohár wrote: > On Wednesday 08 June 2016 22:15:18 Darren Hart wrote: > > On Wed, Jun 08, 2016 at 09:57:26PM +0200, Pali Rohár wrote: > > > On Wednesday 08 June 2016 21:48:24 Darren Hart wrote: > > > > On Wed, Jun 08, 2016 at 12:03:24AM +0200, Pali Rohár wrote: > > > > > On Thursday 02 June 2016 12:41:42 Michał Kępień wrote: > > > > > > > Signed-off-by: Pali Rohár <pali.rohar@gmail.com> > > > > > > > > > > > > My guess is that Darren won't let you off without at least a > > > > > > short commit message. > > > > > > > > > > I have no idea what else to write. I think that description is > > > > > enough. > > > > > > > > There is always something. For example, why? See > > > > Documentation/SubmittingPatches section "14) The canonical patch > > > > format" for an explanation. > > > > > > > > "Traceability" of changes is important. If it's worth preparing > > > > the patch, it's worth documenting why. > > > > > > In my opinion current description is enough and cover everything > > > what this patch is doing. I think it is clear from my description > > > what this patch is doing and so it is documented. > > > > > > But if it is not clear and something is missing, let me know or > > > show what is wrong and how you change it... It is just my > > > assumption that "Sort WMI event codes and update comments" is > > > clear... > > > > The patch summary accurately states what it does. It does not explain > > why it does it, or why it is necessary. I understand this is a > > trivial change, but also understand that both maintainers and people > > doing maintenance and regression analysis will appreciate > > understanding the motivation and intent of the patch, in addition to > > the content of the patch. > > > > From the maintainer perspective, whether we have 20 or 200 patches to > > review, we will naturally merge the ones that require the least > > effort first. This maximizes our efficiency and benefits the most > > people with what time we have available. For many of us, this is our > > nights and weekends (guessing that's the case for you as well). It > > is in the submitter's best interest to take the time document the > > why, what, and how of each patch in a way that minimizes the effort > > on the part of the maintainer to decide if the patch should be > > merged. It is also a matter of scale, if every patch conforms to > > these guidelines, the workflow is much more efficient. > > > > In this case, I don't know why you decided to sort the event codes or > > update the comments. I assume the comments were wrong before, but > > maybe something changed. Do you care about alphabetically order or > > optimizing the switch statements? Is it purely for legibility? Etc. > > > > If that isn't sufficient, then just do it out of self-interest, > > because I will not send patches to Linus that do not provide both a > > summary and a description in the commit which meet the guidelines of > > section 14 referenced above. > > > > Thanks, > > I fully understand your maintainer perspective. I just though that my > one line explain everything what is needed about my patch... > > So do you want to include reason for my patch? What about this > additional description? > > === > For better readability of keymap table, sort events by codes and also > update comments for events to be more informative. Great, that works for me. Reason was readability and providing context. I'm just getting to the series now, if it's otherwise ready, I'll include this myself. If changes are required, I'll leave it to you. Thanks Pali.
On Wednesday 08 June 2016 22:43:28 Darren Hart wrote: > I'm just getting to the series now, if it's otherwise ready, I'll > include this myself. If changes are required, I'll leave it to you. > Thanks Pali. There is already V2 of this series with fixed problems reported by Michał. So Michał should ack it...
diff --git a/drivers/platform/x86/dell-wmi.c b/drivers/platform/x86/dell-wmi.c index 4d23c91..363d927 100644 --- a/drivers/platform/x86/dell-wmi.c +++ b/drivers/platform/x86/dell-wmi.c @@ -86,31 +86,32 @@ static const struct dmi_system_id dell_wmi_smbios_list[] __initconst = { */ static const struct key_entry dell_wmi_legacy_keymap[] __initconst = { - { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, - { KE_KEY, 0xe009, { KEY_EJECTCD } }, + { KE_IGNORE, 0x003a, { KEY_CAPSLOCK } }, - /* These also contain the brightness level at offset 6 */ - { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, - { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, + /* These also contain the brightness level after key code */ + { KE_KEY, 0xe006, { KEY_BRIGHTNESSUP } }, + { KE_KEY, 0xe005, { KEY_BRIGHTNESSDOWN } }, /* Battery health status button */ - { KE_KEY, 0xe007, { KEY_BATTERY } }, + { KE_KEY, 0xe007, { KEY_BATTERY } }, - /* Radio devices state change */ + /* Radio devices state change, also contains additional information */ { KE_IGNORE, 0xe008, { KEY_RFKILL } }, - /* The next device is at offset 6, the active devices are at - offset 8 and the attached devices at offset 10 */ - { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, + { KE_KEY, 0xe009, { KEY_EJECTCD } }, + /* After key code is: next device, active devices, attached devices */ + { KE_KEY, 0xe00b, { KEY_SWITCHVIDEOMODE } }, + + /* Also contains keyboard illumination level after key code */ { KE_IGNORE, 0xe00c, { KEY_KBDILLUMTOGGLE } }, /* BIOS error detected */ { KE_IGNORE, 0xe00d, { KEY_RESERVED } }, /* Wifi Catcher */ - { KE_KEY, 0xe011, {KEY_PROG2 } }, + { KE_KEY, 0xe011, { KEY_PROG2 } }, /* Ambient light sensor toggle */ { KE_IGNORE, 0xe013, { KEY_RESERVED } }, @@ -118,12 +119,14 @@ static const struct key_entry dell_wmi_legacy_keymap[] __initconst = { { KE_IGNORE, 0xe020, { KEY_MUTE } }, /* Dell Instant Launch key */ - { KE_KEY, 0xe025, { KEY_PROG4 } }, - { KE_KEY, 0xe029, { KEY_PROG4 } }, + { KE_KEY, 0xe025, { KEY_PROG4 } }, /* Audio panel key */ { KE_IGNORE, 0xe026, { KEY_RESERVED } }, + /* Dell Instant Launch key */ + { KE_KEY, 0xe029, { KEY_PROG4 } }, + { KE_IGNORE, 0xe02e, { KEY_VOLUMEDOWN } }, { KE_IGNORE, 0xe030, { KEY_VOLUMEUP } }, { KE_IGNORE, 0xe033, { KEY_KBDILLUMUP } }, @@ -146,7 +149,9 @@ static const struct key_entry dell_wmi_legacy_keymap[] __initconst = { { KE_IGNORE, 0xe0f7, { KEY_MUTE } }, { KE_IGNORE, 0xe0f8, { KEY_VOLUMEDOWN } }, { KE_IGNORE, 0xe0f9, { KEY_VOLUMEUP } }, + { KE_END, 0 } + }; static bool dell_new_hk_type;
Signed-off-by: Pali Rohár <pali.rohar@gmail.com> --- drivers/platform/x86/dell-wmi.c | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-)