On Sat, Jul 04 2020, Matthew Wilcox wrote:
> Another suggestion for "slave" replacement should be "device". This is in
> the context of the w1 bus which is by far the largest user of the
> master/slave terminology in the kernel.
Ugh. Please, no. "device" doesn't mean anything, in that you can use
it to refer to any thing. (i.e. it is almost semantically equivalent to
"thing").
Look in /sys/devices. Everything in there is a device, and (nearly)
every thing is in there.
NeilBrown
>
> On Sat., Jul. 4, 2020, 16:19 Dan Williams, <[email protected]> wrote:
>
>> Recent events have prompted a Linux position statement on inclusive
>> terminology. Given that Linux maintains a coding-style and its own
>> idiomatic set of terminology here is a proposal to answer the call to
>> replace non-inclusive terminology.
>>
>> Cc: Jonathan Corbet <[email protected]>
>> Cc: Kees Cook <[email protected]>
>> Signed-off-by: Chris Mason <[email protected]>
>> Signed-off-by: Greg Kroah-Hartman <[email protected]>
>> Signed-off-by: Dan Williams <[email protected]>
>> ---
>> Documentation/process/coding-style.rst | 12 ++++
>> Documentation/process/inclusive-terminology.rst | 64
>> +++++++++++++++++++++++
>> Documentation/process/index.rst | 1
>> 3 files changed, 77 insertions(+)
>> create mode 100644 Documentation/process/inclusive-terminology.rst
>>
>> diff --git a/Documentation/process/coding-style.rst
>> b/Documentation/process/coding-style.rst
>> index 2657a55c6f12..4b15ab671089 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -319,6 +319,18 @@ If you are afraid to mix up your local variable
>> names, you have another
>> problem, which is called the function-growth-hormone-imbalance syndrome.
>> See chapter 6 (Functions).
>>
>> +For symbol names, avoid introducing new usage of the words 'slave' and
>> +'blacklist'. Recommended replacements for 'slave' are: 'secondary',
>> +'subordinate', 'replica', 'responder', 'follower', 'proxy', or
>> +'performer'. Recommended replacements for blacklist are: 'blocklist' or
>> +'denylist'.
>> +
>> +Exceptions for introducing new usage is to maintain a userspace ABI, or
>> +when updating code for an existing (as of 2020) hardware or protocol
>> +specification that mandates those terms. For new specifications consider
>> +translating specification usage of the terminology to the kernel coding
>> +standard where possible. See :ref:`process/inclusive-terminology.rst
>> +<inclusiveterminology>` for details.
>>
>> 5) Typedefs
>> -----------
>> diff --git a/Documentation/process/inclusive-terminology.rst
>> b/Documentation/process/inclusive-terminology.rst
>> new file mode 100644
>> index 000000000000..a8eb26690eb4
>> --- /dev/null
>> +++ b/Documentation/process/inclusive-terminology.rst
>> @@ -0,0 +1,64 @@
>> +.. _inclusiveterminology:
>> +
>> +Linux kernel inclusive terminology
>> +==================================
>> +
>> +The Linux kernel is a global software project, and in 2020 there was a
>> +global reckoning on race relations that caused many organizations to
>> +re-evaluate their policies and practices relative to the inclusion of
>> +people of African descent. This document describes why the 'Naming'
>> +section in :ref:`process/coding-style.rst <codingstyle>` recommends
>> +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux
>> +kernel.
>> +
>> +On the triviality of replacing words
>> +====================================
>> +
>> +The African slave trade was a brutal system of human misery deployed at
>> +global scale. Some word choice decisions in a modern software project
>> +does next to nothing to compensate for that legacy. So why put any
>> +effort into something so trivial in comparison? Because the goal is not
>> +to repair, or erase the past. The goal is to maximize availability and
>> +efficiency of the global developer community to participate in the Linux
>> +kernel development process.
>> +
>> +Word choice and developer efficiency
>> +====================================
>> +
>> +Why does any software project go through the trouble of developing a
>> +document like :ref:`process/coding-style.rst <codingstyle>`? It does so
>> +because a common coding style maximizes the efficiency of both
>> +maintainers and developers. Developers learn common design patterns and
>> +idiomatic expressions while maintainers can spot deviations from those
>> +norms. Even non-compliant whitespace is considered a leading indicator
>> +to deeper problems in a patchset. Coding style violations are known to
>> +take a maintainer "out of the zone" of reviewing code. Maintainers are
>> +also sensitive to word choice across specifications and often choose to
>> +deploy Linux terminology to replace non-idiomatic word-choice in a
>> +specification.
>> +
>> +Non-inclusive terminology has that same distracting effect which is why
>> +it is a style issue for Linux, it injures developer efficiency.
>> +
>> +Of course it is around this point someone jumps in with an etymological
>> +argument about why people should not be offended. Etymological arguments
>> +do not scale. The scope and pace of Linux to reach new developers
>> +exceeds the ability of historical terminology defenders to describe "no,
>> +not that connotation". The revelation of 2020 was that black voices were
>> +heard on a global scale and the Linux kernel project has done its small
>> +part to answer that call as it wants black voices, among all voices, in
>> +its developer community.
>> +
>> +Really, 'blacklist' too?
>> +========================
>> +
>> +While 'slave' has a direct connection to human suffering the etymology
>> +of 'blacklist' is devoid of a historical racial connection. However, one
>> +thought exercise is to consider replacing 'blacklist/whitelist' with
>> +'redlist/greenlist'. Realize that the replacement only makes sense if
>> +you have been socialized with the concepts that 'red/green' implies
>> +'stop/go'. Colors to represent a policy requires an indirection. The
>> +socialization of 'black/white' to have the connotation of
>> +'impermissible/permissible' does not support inclusion.
>> +
>> +Inclusion == global developer community efficiency.
>> diff --git a/Documentation/process/index.rst
>> b/Documentation/process/index.rst
>> index f07c9250c3ac..ed861f6f8d25 100644
>> --- a/Documentation/process/index.rst
>> +++ b/Documentation/process/index.rst
>> @@ -27,6 +27,7 @@ Below are the essential guides that every developer
>> should read.
>> submitting-patches
>> programming-language
>> coding-style
>> + inclusive-terminology
>> maintainer-pgp-guide
>> email-clients
>> kernel-enforcement-statement
>>
>> _______________________________________________
>> Ksummit-discuss mailing list
>> [email protected]
>> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
>>
> _______________________________________________
> Ksummit-discuss mailing list
> [email protected]
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote:
> On Sat, Jul 04 2020, Matthew Wilcox wrote:
>
> > Another suggestion for "slave" replacement should be "device". This is in
> > the context of the w1 bus which is by far the largest user of the
> > master/slave terminology in the kernel.
>
> Ugh. Please, no. "device" doesn't mean anything, in that you can use
> it to refer to any thing. (i.e. it is almost semantically equivalent to
> "thing").
Context is everything, you can have a "controller" and a "device" that
the controller controls. These are common terms in many specs today,
look at the USB spec for an example of these terms being used in this
way for many decades.
So while the term might be generic, like the word it is replacing, it
makes sense when used in the context it will show up in, so it is a good
replacement in many instances.
thanks,
greg k-h
On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman
<[email protected]> wrote:
> On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote:
> > On Sat, Jul 04 2020, Matthew Wilcox wrote:
> > > Another suggestion for "slave" replacement should be "device". This is in
> > > the context of the w1 bus which is by far the largest user of the
> > > master/slave terminology in the kernel.
W1 the largest? Really?
> >
> > Ugh. Please, no. "device" doesn't mean anything, in that you can use
> > it to refer to any thing. (i.e. it is almost semantically equivalent to
> > "thing").
>
> Context is everything, you can have a "controller" and a "device" that
> the controller controls. These are common terms in many specs today,
A "controller" is also any block of electronics that performs a function
involving a state machine.
So for SPI and I2C, we'll have Linux drivers talking to an "SPI controller
controller", an "SPI device controller", an "I2C controller controller",
and an "I2C device controller".
For W1, Linux is still limited to supporting "W1 controller controllers",
but supporting "W1 device controllers" might be just beyond the horizon...
> look at the USB spec for an example of these terms being used in this
> way for many decades.
And when does the "gadget" enter the show? ;-)
P.S. In Dutch, we just assimilate all English technical words, and
they'll only have that specific meaning. E.g. if someone
talks about the "cloud", even lay people know they're not talking
about those things that may ruin your holiday outside.
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On Mon, Jul 06, 2020 at 09:53:55AM +0200, Geert Uytterhoeven wrote:
> On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman
> <[email protected]> wrote:
> > look at the USB spec for an example of these terms being used in this
> > way for many decades.
>
> And when does the "gadget" enter the show? ;-)
It doesn't, as the USB spec does not describe that in any reasonable way
for us to use when dealing with drivers for both "types" of devices. So
we came up with the word "gadget" on purpose to be able to talk about
those things in a specific manner.
thanks,
greg k-h
On Mon, Jul 6, 2020 at 3:54 AM Geert Uytterhoeven <[email protected]> wrote:
> On Mon, Jul 6, 2020 at 9:22 AM Greg Kroah-Hartman
> <[email protected]> wrote:
> > On Mon, Jul 06, 2020 at 05:10:37PM +1000, NeilBrown wrote:
> > > On Sat, Jul 04 2020, Matthew Wilcox wrote:
> > > > Another suggestion for "slave" replacement should be "device". This is in
> > > > the context of the w1 bus which is by far the largest user of the
> > > > master/slave terminology in the kernel.
>
> W1 the largest? Really?
I should have said "most obnoxious". They managed to put that terminology in
filenames, eg drivers/w1/slaves and Documentation/w1/slaves
In terms of number of lines of code using the word, it's only seventh
in drivers/:
$ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc
-l); echo "$c $i"; done |sort -rn |head
5218 drivers/net
1341 drivers/dma
988 drivers/i2c
695 drivers/gpu
666 drivers/soundwire
665 drivers/spi
559 drivers/w1
461 drivers/infiniband
389 drivers/media
301 drivers/scsi
On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote:
[]
> In terms of number of lines of code using the word, it's only seventh
> in drivers/:
>
> $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc
> -l); echo "$c $i"; done |sort -rn |head
> 5218 drivers/net
> 1341 drivers/dma
> 988 drivers/i2c
> 695 drivers/gpu
> 666 drivers/soundwire
> 665 drivers/spi
> 559 drivers/w1
> 461 drivers/infiniband
> 389 drivers/media
> 301 drivers/scsi
I get rather different and much lower numbers
$ git grep -i -w slave drivers | \
cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
1 3091 drivers/net
2 654 drivers/i2c
3 595 drivers/soundwire
4 483 drivers/dma
5 284 drivers/infiniband
6 269 drivers/gpu
7 198 drivers/media
8 192 drivers/fsi
9 174 drivers/spi
10 131 drivers/ata
11 111 drivers/w1
12 110 drivers/staging
13 89 drivers/iio
14 71 drivers/usb
15 60 drivers/mfd
16 53 drivers/soc
17 52 drivers/tty
18 32 drivers/vme
19 32 drivers/mtd
20 28 drivers/ide
On Mon, Jul 6, 2020 at 8:59 AM Joe Perches <[email protected]> wrote:
> On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote:
> > In terms of number of lines of code using the word, it's only seventh
> > in drivers/:
> >
> > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc
> > -l); echo "$c $i"; done |sort -rn |head
> > 5218 drivers/net
> > 1341 drivers/dma
> > 988 drivers/i2c
> > 695 drivers/gpu
> > 666 drivers/soundwire
> > 665 drivers/spi
> > 559 drivers/w1
> > 461 drivers/infiniband
> > 389 drivers/media
> > 301 drivers/scsi
>
> I get rather different and much lower numbers
>
> $ git grep -i -w slave drivers | \
> cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
That's because you're using grep -w which excludes, for example,
slave_configure in drivers/scsi.
On Mon, 2020-07-06 at 09:04 -0400, Matthew Wilcox wrote:
> On Mon, Jul 6, 2020 at 8:59 AM Joe Perches <[email protected]> wrote:
> > On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote:
> > > In terms of number of lines of code using the word, it's only seventh
> > > in drivers/:
> > >
> > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc
> > > -l); echo "$c $i"; done |sort -rn |head
> > > 5218 drivers/net
> > > 1341 drivers/dma
> > > 988 drivers/i2c
> > > 695 drivers/gpu
> > > 666 drivers/soundwire
> > > 665 drivers/spi
> > > 559 drivers/w1
> > > 461 drivers/infiniband
> > > 389 drivers/media
> > > 301 drivers/scsi
> >
> > I get rather different and much lower numbers
> >
> > $ git grep -i -w slave drivers | \
> > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
>
> That's because you're using grep -w which excludes, for example,
> slave_configure in drivers/scsi.
upper/lower case uses too... (anyway, there are a lot)
$ git grep -i -w -P '\w*slave\w*' drivers | \
cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
1 5683 drivers/net
2 2118 drivers/gpu
3 1807 drivers/dma
4 1389 drivers/i2c
5 866 drivers/interconnect
6 835 drivers/soundwire
7 821 drivers/spi
8 698 drivers/w1
9 508 drivers/media
10 481 drivers/infiniband
11 440 drivers/ata
12 317 drivers/scsi
13 267 drivers/fsi
14 240 drivers/tty
15 225 drivers/vme
16 223 drivers/staging
17 157 drivers/mmc
18 155 drivers/usb
19 141 drivers/video
20 140 drivers/char
Em Mon, 06 Jul 2020 06:30:01 -0700
Joe Perches <[email protected]> escreveu:
> On Mon, 2020-07-06 at 09:04 -0400, Matthew Wilcox wrote:
> > On Mon, Jul 6, 2020 at 8:59 AM Joe Perches <[email protected]> wrote:
> > > On Mon, 2020-07-06 at 08:51 -0400, Matthew Wilcox wrote:
> > > > In terms of number of lines of code using the word, it's only seventh
> > > > in drivers/:
> > > >
> > > > $ for i in drivers/*; do c=$(find $i -type f |xargs grep slave |wc
> > > > -l); echo "$c $i"; done |sort -rn |head
> > > > 5218 drivers/net
> > > > 1341 drivers/dma
> > > > 988 drivers/i2c
> > > > 695 drivers/gpu
> > > > 666 drivers/soundwire
> > > > 665 drivers/spi
> > > > 559 drivers/w1
> > > > 461 drivers/infiniband
> > > > 389 drivers/media
> > > > 301 drivers/scsi
> > >
> > > I get rather different and much lower numbers
> > >
> > > $ git grep -i -w slave drivers | \
> > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
> >
> > That's because you're using grep -w which excludes, for example,
> > slave_configure in drivers/scsi.
>
> upper/lower case uses too... (anyway, there are a lot)
>
> $ git grep -i -w -P '\w*slave\w*' drivers | \
> cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
> 1 5683 drivers/net
> 2 2118 drivers/gpu
> 3 1807 drivers/dma
> 4 1389 drivers/i2c
> 5 866 drivers/interconnect
> 6 835 drivers/soundwire
> 7 821 drivers/spi
> 8 698 drivers/w1
> 9 508 drivers/media
> 10 481 drivers/infiniband
> 11 440 drivers/ata
> 12 317 drivers/scsi
> 13 267 drivers/fsi
> 14 240 drivers/tty
> 15 225 drivers/vme
> 16 223 drivers/staging
> 17 157 drivers/mmc
> 18 155 drivers/usb
> 19 141 drivers/video
> 20 140 drivers/char
It sounds that, as soon after this patch gets merged, the mailing lists
will be flooded by lots of patches replacing such terms with something
else :-(
Doing a quick look at the media subsystem, it sounds that most terms
come from I2C master/slave and DiSEqC terminology, as defined by their
specs (and the others seem to be derived from some hardware vendor
specific terminology).
As they're all supported by the current specs, if one would want
to replace them, it should first ensure that the supporting specs
should be using a different terminology, as otherwise replacing
them would just make harder for anyone trying to understand the
code.
Thanks,
Mauro
Hi Mauro,
On 09-07-20, 13:11, Mauro Carvalho Chehab wrote:
> Em Mon, 06 Jul 2020 06:30:01 -0700
> Joe Perches <[email protected]> escreveu:
> >
> > $ git grep -i -w -P '\w*slave\w*' drivers | \
> > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
> > 1 5683 drivers/net
> > 2 2118 drivers/gpu
> > 3 1807 drivers/dma
> > 4 1389 drivers/i2c
> > 5 866 drivers/interconnect
> > 6 835 drivers/soundwire
> > 7 821 drivers/spi
> > 8 698 drivers/w1
> > 9 508 drivers/media
> > 10 481 drivers/infiniband
> > 11 440 drivers/ata
> > 12 317 drivers/scsi
> > 13 267 drivers/fsi
> > 14 240 drivers/tty
> > 15 225 drivers/vme
> > 16 223 drivers/staging
> > 17 157 drivers/mmc
> > 18 155 drivers/usb
> > 19 141 drivers/video
> > 20 140 drivers/char
>
> It sounds that, as soon after this patch gets merged, the mailing lists
> will be flooded by lots of patches replacing such terms with something
> else :-(
>
> Doing a quick look at the media subsystem, it sounds that most terms
> come from I2C master/slave and DiSEqC terminology, as defined by their
> specs (and the others seem to be derived from some hardware vendor
> specific terminology).
>
> As they're all supported by the current specs, if one would want
> to replace them, it should first ensure that the supporting specs
> should be using a different terminology, as otherwise replacing
> them would just make harder for anyone trying to understand the
> code.
I think waiting for specs may result in long delays, we all know how
'fast' spec bodies work!
Putting my soundwire maintainer hat, I see more than 1K uses of 'slave'
in the subsystem due to MIPI defined terms of SoundWire Master/Slave, so
I am planning to replace that and not wait for MIPI to update the spec.
A similar approach where we discuss with relevant stakeholder and arrive
at replacement terms and swap them would be great
Thanks
--
~Vinod
On Sun, Jul 12, 2020 at 9:26 PM Vinod Koul <[email protected]> wrote:
>
> Hi Mauro,
>
> On 09-07-20, 13:11, Mauro Carvalho Chehab wrote:
> > Em Mon, 06 Jul 2020 06:30:01 -0700
> > Joe Perches <[email protected]> escreveu:
> > >
> > > $ git grep -i -w -P '\w*slave\w*' drivers | \
> > > cut -f1,2 -d/ | uniq -c | sort -rn | head -20 | cat -n
> > > 1 5683 drivers/net
> > > 2 2118 drivers/gpu
> > > 3 1807 drivers/dma
> > > 4 1389 drivers/i2c
> > > 5 866 drivers/interconnect
> > > 6 835 drivers/soundwire
> > > 7 821 drivers/spi
> > > 8 698 drivers/w1
> > > 9 508 drivers/media
> > > 10 481 drivers/infiniband
> > > 11 440 drivers/ata
> > > 12 317 drivers/scsi
> > > 13 267 drivers/fsi
> > > 14 240 drivers/tty
> > > 15 225 drivers/vme
> > > 16 223 drivers/staging
> > > 17 157 drivers/mmc
> > > 18 155 drivers/usb
> > > 19 141 drivers/video
> > > 20 140 drivers/char
> >
> > It sounds that, as soon after this patch gets merged, the mailing lists
> > will be flooded by lots of patches replacing such terms with something
> > else :-(
> >
> > Doing a quick look at the media subsystem, it sounds that most terms
> > come from I2C master/slave and DiSEqC terminology, as defined by their
> > specs (and the others seem to be derived from some hardware vendor
> > specific terminology).
> >
> > As they're all supported by the current specs, if one would want
> > to replace them, it should first ensure that the supporting specs
> > should be using a different terminology, as otherwise replacing
> > them would just make harder for anyone trying to understand the
> > code.
>
> I think waiting for specs may result in long delays, we all know how
> 'fast' spec bodies work!
>
> Putting my soundwire maintainer hat, I see more than 1K uses of 'slave'
> in the subsystem due to MIPI defined terms of SoundWire Master/Slave, so
> I am planning to replace that and not wait for MIPI to update the spec.
Sounds good.
> A similar approach where we discuss with relevant stakeholder and arrive
> at replacement terms and swap them would be great
Right, just like any other coding-style cleanup, stage it the way that
makes the most sense for the subsystem you maintain.