[PATCH v2 00/12] media: atomisp: Codingstyle
Hello! This series fix some codingstyle errors in the files rmgr_vbuf.c, ia_css_rmgr.h, timer.c, spctrl.c and queue.c in the drivers/staging/media area. V2: [Patch 1/12] Also remove NULL, 0 and false members to make it C99 standard comform. [Patch 6/12] Checkpatch throws COMPLEX_MACRO Error. Handle that error by deleting these defines. The other patches are the same. Best regards Philipp -- media: atomisp: Convert comments to C99 initializers media: atomisp: Fix Block Comments media: atomisp: Fix EMBEDDED_FUNCTION_NAME warning media: atomisp: Fix OPEN_ENDED_LINE media: atomisp: Fix overlong line media: atomisp: Remove defines media: atomisp: Fix funciton decleration media: atomisp: Delete braces media: atomisp: Fix PARENTHESIS_ALIGNMENT media: atomisp: Fix BLOCK_COMMENT_STYLE media: atomisp: Write function decleration in one line media: atomisp: Fix LOGICAL_CONTINUATIONS .../atomisp/pci/runtime/queue/src/queue.c | 48 +-- .../pci/runtime/rmgr/interface/ia_css_rmgr.h | 5 +- .../atomisp/pci/runtime/rmgr/src/rmgr_vbuf.c | 41 ++-- .../atomisp/pci/runtime/spctrl/src/spctrl.c | 7 ++- .../atomisp/pci/runtime/timer/src/timer.c | 7 +-- 5 files changed, 33 insertions(+), 75 deletions(-) -- 2.20.1
[PATCH 00/12] media: atomisp: Codingstyle
Hello! This series fix some codingstyle errors in the files rmgr_vbuf.c, ia_css_rmgr.h, timer.c, spctrl.c and queue.c in the drivers/staging/media area. Best regards Philipp -- media: atomsip: Convert comments to C99 initializers media: atomisp: Fix Block Comments media: atomisp: Fix EMBEDDED_FUNCTION_NAME warning media: atomisp: Fix OPEN_ENDED_LINE media: atomisp: Fix overlong line media: atomisp: Add parentheses media: atomisp: Fix funciton decleration media: atomisp: Delete braces media: atomisp: Fix PARENTHESIS_ALIGNMENT media: atomisp: Fix BLOCK_COMMENT_STYLE media: atomisp: Write function decleration in one line media: atomisp: Fix LOGICAL_CONTINUATIONS .../atomisp/pci/runtime/queue/src/queue.c | 48 +- .../pci/runtime/rmgr/interface/ia_css_rmgr.h | 4 +- .../atomisp/pci/runtime/rmgr/src/rmgr_vbuf.c | 49 +-- .../atomisp/pci/runtime/spctrl/src/spctrl.c | 7 ++- .../atomisp/pci/runtime/timer/src/timer.c | 7 +-- 5 files changed, 44 insertions(+), 71 deletions(-) -- 2.20.1
Re: [PATCH 0/2] pinctrl: rockchip: codingstyle for pinctrl-rockchip
Hi Linus, Am Samstag, 12. September 2020, 13:27:44 CEST schrieb Linus Walleij: > Jianqun, Heiko, > > On Fri, Jan 17, 2020 at 9:14 AM Jianqun Xu wrote: > > > Do codingstyle for pinctrl-rockchip by spliting driver by SoC types. > > > > Convenienty for reviewing, the first patch only moving > > pinctrl-rockchip.c from driver/pinctrl to driver/pinctrl/rockchip/ . > > > > Jianqun Xu (2): > > pinctrl: rockchip: new rockchip dir for pinctrl-rockchip > > pinctrl: rockchip: split rockchip pinctrl driver by SoC type > > Why were these patches never applied? Is it my fault? It's not your fault :-) > I don't even have patch 2/2 in my mailbox, possibly it was > too big! > > Heiko if you're OK with this change can Jianqun just send a > rebased version? We agreed to split it into smaller chunks which I think is the 13-patch series you mentioned elsewhere today. But I guess that fell through the cracks in my review :-( . So I guess we should do the current GKI thingy first to get that module build and after that maybe Jianqun can find the time to rebase the per-soc split on top of that. Heiko
Re: [PATCH 0/2] pinctrl: rockchip: codingstyle for pinctrl-rockchip
Jianqun, Heiko, On Fri, Jan 17, 2020 at 9:14 AM Jianqun Xu wrote: > Do codingstyle for pinctrl-rockchip by spliting driver by SoC types. > > Convenienty for reviewing, the first patch only moving > pinctrl-rockchip.c from driver/pinctrl to driver/pinctrl/rockchip/ . > > Jianqun Xu (2): > pinctrl: rockchip: new rockchip dir for pinctrl-rockchip > pinctrl: rockchip: split rockchip pinctrl driver by SoC type Why were these patches never applied? Is it my fault? I don't even have patch 2/2 in my mailbox, possibly it was too big! Heiko if you're OK with this change can Jianqun just send a rebased version? Yours, Linus Walleij
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Dan, and everybody, Thank you for the patch. On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams 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 > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- > 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 > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..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 ` 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 `? 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. I've been pondering about this statement for several weeks now, sleeping over it for far longer than I usual
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, Jul 13, 2020 at 1:02 AM Takashi Iwai wrote: > > On Wed, 08 Jul 2020 20:14:27 +0200, > Dan Williams wrote: > > > > +Recommended replacements for 'blacklist/whitelist' are: > > +'denylist / allowlist' > > +'blocklist / passlist' > > I started looking through the tree now and noticed there are lots of > patterns like "whitelisted" or "blacklisted". How can the words fit > for those? Actually, there are two cases like: > > - Foo is blacklisted > - Allow to load the non-whitelisted cards > > Currently I'm replacing the former with "Foo is in denylist", but not > sure about the latter case. I thought Kees mentioned about this, but > don't remember the proposal... Hmm. In these cases, we're trying to convey one of two things. A given device/platform/CPU/whatever could be known to be problematic and thus disallowed, or we could have a policy that we generally don't trust hardware but we have specific reason to believe that this particular hardware is okay. After doing a highly scientific sampling of a few cases, some of these are indeed lists and some are not. If we're going to look for new words for these concepts, perhaps we shouldn't focus on the *list* aspect -- after all, that's just a rather popular implementation detail, but it's not the core concept we're trying to express. As an example case, we have a horrible concept in which some Intel CPUs support a form of memory failure recovery, and there is no enumeration mechanism. Instead, there's a list (sigh). So we could say "your CPU is whitelisted for such-and-such," which at least gets the idea across, but saying "your CPU is allowlisted for such-and-such" seems like a stretch. It's not that we have a policy to allow things on the list -- it's that we think that CPUs not on the list simply don't have the relevant capability. Here are some brainstormed ideas: - Such-and-such feature is quirked off. (Or disabled due to a quirk.) - Your device is not on the known-good list. - Your device is not known-good. It might work anyway -- to try it, set such-and-such option. - Your device is known bad. - Your device is busted and we think you should pressure the manufacturer to fix it. - Your device is too old and no longer supported. - Seriously, you're trying to use an 80386 on a modern kernel? No thanks. We think it's neat that you still have one that works, though. - (Specifically for modules and not part of the Linux kernel tree) disable_autoload instead of blacklist, perhaps? Part of my point is that we use blacklist and whitelist to mean various things, and I don't think we should try to invent a couple of new catch-all terms to replace them. Perhaps replacing these words could be an opportunity to come up with better descriptions at the same time.
Re: [PATCH v3] CodingStyle: Inclusive Terminology
On Wed 2020-07-08 11:14:27, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: SeongJae Park > Acked-by: Christian Brauner > Acked-by: James Bottomley > Reviewed-by: Mark Brown > Signed-off-by: Theodore Ts'o > Signed-off-by: Shuah Khan > Signed-off-by: Dan Carpenter > Signed-off-by: Kees Cook > Signed-off-by: Olof Johansson > Signed-off-by: Jonathan Corbet > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- > Changes since v2 [1]: > - Pick up missed sign-offs and acks from Jon, Shuah, and Christian > (sorry about missing those earlier). > > - Reformat the replacement list to make it easier to read. > > - Add 'controller' as a suggested replacement (Kees and Mark) > > - Fix up the paired term for 'performer' to be 'director' (Kees) > > - Collect some new acks, reviewed-by's, and sign-offs for v2. > > - Fix up Chris's email > > [1]: > http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com > > > Documentation/process/coding-style.rst | 20 > 1 file changed, 20 insertions(+) > > +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / > allowlist' + > 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain > a > userspace ABI/API, +or when updating code for an existing (as of 2020) > hardware or > protocol +specification that mandates those terms. For new specifications > +translate > specification usage of the terminology to the kernel coding +standard where > possible. Please try to understand how "blacklist" is used in the kernel before suggesting replacements. NAK. Pavel -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
Re: [PATCH] CodingStyle: Inclusive Terminology
Hi! > +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. I'd preffer to keep politics out of kernel. > +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 So you are trying to blacklist colors. That's stupid. > +socialization of 'black/white' to have the connotation of > +'impermissible/permissible' does not support inclusion. > + > +Inclusion == global developer community efficiency. It seems inclusion == reason to push politics and questionable patches into kernel. That is opposite of efficiency. :-( Pavel -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
[PATCH 13/13] pinctrl: rockchip: do codingstyle by adding mux route definitions
Add MR_SAME/MR_GRF/MR_PMU definitions, and update data in mux route
structures.
This patch do nothing change, only do some codingstyle.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 674 +
1 file changed, 104 insertions(+), 570 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index 71a367896297..50558ffcc05c 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -78,6 +78,9 @@ enum rockchip_pinctrl_type {
#define ROCKCHIP_DRV_3BITS_PER_PIN (3)
#define ROCKCHIP_DRV_BITS_PER_PIN (2)
+#define RK_GENMASK_VAL(h, l, v) \
+ (GENMASK(((h) + 16), ((l) + 16)) | (((v) << (l)) & GENMASK((h), (l
+
/**
* @type: iomux variant using IOMUX_* constants
* @offset: if initialized to -1 it will be autocalculated, by specifying
@@ -290,6 +293,25 @@ struct rockchip_pin_bank {
.pull_type[3] = pull3, \
}
+#define PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, FLAG)
\
+ { \
+ .bank_num = ID, \
+ .pin= PIN, \
+ .func = FUNC, \
+ .route_offset = REG, \
+ .route_val = VAL, \
+ .route_location = FLAG, \
+ }
+
+#define MR_SAME(ID, PIN, FUNC, REG, VAL) \
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_SAME)
+
+#define MR_GRF(ID, PIN, FUNC, REG, VAL)\
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_GRF)
+
+#define MR_PMU(ID, PIN, FUNC, REG, VAL)\
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_PMU)
+
/**
* struct rockchip_mux_recalced_data: represent a pin iomux data.
* @num: bank number.
@@ -804,597 +826,109 @@ static void rockchip_get_recalced_mux(struct
rockchip_pin_bank *bank, int pin,
}
static struct rockchip_mux_route_data px30_mux_route_data[] = {
- {
- /* cif-d2m0 */
- .bank_num = 2,
- .pin = 0,
- .func = 1,
- .route_offset = 0x184,
- .route_val = BIT(16 + 7),
- }, {
- /* cif-d2m1 */
- .bank_num = 3,
- .pin = 3,
- .func = 3,
- .route_offset = 0x184,
- .route_val = BIT(16 + 7) | BIT(7),
- }, {
- /* pdm-m0 */
- .bank_num = 3,
- .pin = 22,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 8),
- }, {
- /* pdm-m1 */
- .bank_num = 2,
- .pin = 22,
- .func = 1,
- .route_offset = 0x184,
- .route_val = BIT(16 + 8) | BIT(8),
- }, {
- /* uart2-rxm0 */
- .bank_num = 1,
- .pin = 27,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 10),
- }, {
- /* uart2-rxm1 */
- .bank_num = 2,
- .pin = 14,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 10) | BIT(10),
- }, {
- /* uart3-rxm0 */
- .bank_num = 0,
- .pin = 17,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 9),
- }, {
- /* uart3-rxm1 */
- .bank_num = 1,
- .pin = 15,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 9) | BIT(9),
- },
+ MR_SAME(2, 0, 1, 0x184, RK_GENMASK_VAL(7, 7, 0)), /* cif-d2m0 */
+ MR_SAME(3, 3, 3, 0x184, RK_GENMASK_VAL(7, 7, 1)), /* cif-d2m1 */
+ MR_SAME(3, 22, 2, 0x184, RK_GENMASK_VAL(8, 8, 0)), /* pdm-m0 */
+ MR_SAME(2, 22, 1, 0x184, RK_GENMASK_VAL(8, 8, 1)), /* pdm-m1 */
+ MR_SAME(0, 17, 2, 0x184, RK_GENMASK_VAL(9, 9, 0)), /* uart3-rxm0 */
+ MR_SAME(1, 15, 2, 0x184, RK_GENMASK_VAL(9, 9, 1)), /* uart3-rxm1 */
+ MR_SAME(1, 27, 2, 0x184, RK_GENMASK_VAL(10, 10, 0)), /* uart2-rxm0 */
+ MR_SAME(2, 14, 2, 0x184, RK_GENMASK_VAL(10, 10, 1)), /* uart2-rxm1 */
};
static struct rockchip_mux_route_data rk3128_mux_route_data[] = {
- {
- /* spi-0 */
- .bank_num = 1,
- .pin = 10,
- .func = 1,
- .route_offset = 0x144,
- .route_val = BIT(16 + 3) | BIT(16 + 4),
- }, {
- /* spi-1 */
- .bank_num = 1,
-
[PATCH 09/13] pinctrl: rockchip: do codingstyle
Add RK3228 definitions to separate from other SoCs. Signed-off-by: Jianqun Xu --- drivers/pinctrl/pinctrl-rockchip.c | 22 ++ 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/drivers/pinctrl/pinctrl-rockchip.c b/drivers/pinctrl/pinctrl-rockchip.c index 44f051af97c6..ec6a1a08f8b1 100644 --- a/drivers/pinctrl/pinctrl-rockchip.c +++ b/drivers/pinctrl/pinctrl-rockchip.c @@ -1918,6 +1918,9 @@ static void rk3288_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, } #define RK3228_PULL_OFFSET 0x100 +#define RK3228_PULL_BITS_PER_PIN 2 +#define RK3228_PULL_PINS_PER_REG 8 +#define RK3228_PULL_BANK_STRIDE16 static void rk3228_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, int pin_num, struct regmap **regmap, @@ -1927,14 +1930,17 @@ static void rk3228_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, *regmap = info->regmap_base; *reg = RK3228_PULL_OFFSET; - *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE; - *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4); + *reg += bank->bank_num * RK3228_PULL_BANK_STRIDE; + *reg += ((pin_num / RK3228_PULL_PINS_PER_REG) * 4); - *bit = (pin_num % RK3188_PULL_PINS_PER_REG); - *bit *= RK3188_PULL_BITS_PER_PIN; + *bit = (pin_num % RK3228_PULL_PINS_PER_REG); + *bit *= RK3228_PULL_BITS_PER_PIN; } #define RK3228_DRV_GRF_OFFSET 0x200 +#define RK3228_DRV_BITS_PER_PIN2 +#define RK3228_DRV_PINS_PER_REG8 +#define RK3228_DRV_BANK_STRIDE 16 static void rk3228_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, int pin_num, struct regmap **regmap, @@ -1944,11 +1950,11 @@ static void rk3228_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, *regmap = info->regmap_base; *reg = RK3228_DRV_GRF_OFFSET; - *reg += bank->bank_num * RK3288_DRV_BANK_STRIDE; - *reg += ((pin_num / RK3288_DRV_PINS_PER_REG) * 4); + *reg += bank->bank_num * RK3228_DRV_BANK_STRIDE; + *reg += ((pin_num / RK3228_DRV_PINS_PER_REG) * 4); - *bit = (pin_num % RK3288_DRV_PINS_PER_REG); - *bit *= RK3288_DRV_BITS_PER_PIN; + *bit = (pin_num % RK3228_DRV_PINS_PER_REG); + *bit *= RK3228_DRV_BITS_PER_PIN; } #define RK3308_PULL_OFFSET 0xa0 -- 2.17.1
[PATCH 13/13] pinctrl: rockchip: do codingstyle by adding mux route definitions
Add MR_SAME/MR_GRF/MR_PMU definitions, and update data in mux route
structures.
This patch do nothing change, only do some codingstyle.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 674 +
1 file changed, 104 insertions(+), 570 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index 71a367896297..50558ffcc05c 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -78,6 +78,9 @@ enum rockchip_pinctrl_type {
#define ROCKCHIP_DRV_3BITS_PER_PIN (3)
#define ROCKCHIP_DRV_BITS_PER_PIN (2)
+#define RK_GENMASK_VAL(h, l, v) \
+ (GENMASK(((h) + 16), ((l) + 16)) | (((v) << (l)) & GENMASK((h), (l
+
/**
* @type: iomux variant using IOMUX_* constants
* @offset: if initialized to -1 it will be autocalculated, by specifying
@@ -290,6 +293,25 @@ struct rockchip_pin_bank {
.pull_type[3] = pull3, \
}
+#define PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, FLAG)
\
+ { \
+ .bank_num = ID, \
+ .pin= PIN, \
+ .func = FUNC, \
+ .route_offset = REG, \
+ .route_val = VAL, \
+ .route_location = FLAG, \
+ }
+
+#define MR_SAME(ID, PIN, FUNC, REG, VAL) \
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_SAME)
+
+#define MR_GRF(ID, PIN, FUNC, REG, VAL)\
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_GRF)
+
+#define MR_PMU(ID, PIN, FUNC, REG, VAL)\
+ PIN_BANK_MUX_ROUTE_FLAGS(ID, PIN, FUNC, REG, VAL, ROCKCHIP_ROUTE_PMU)
+
/**
* struct rockchip_mux_recalced_data: represent a pin iomux data.
* @num: bank number.
@@ -804,597 +826,109 @@ static void rockchip_get_recalced_mux(struct
rockchip_pin_bank *bank, int pin,
}
static struct rockchip_mux_route_data px30_mux_route_data[] = {
- {
- /* cif-d2m0 */
- .bank_num = 2,
- .pin = 0,
- .func = 1,
- .route_offset = 0x184,
- .route_val = BIT(16 + 7),
- }, {
- /* cif-d2m1 */
- .bank_num = 3,
- .pin = 3,
- .func = 3,
- .route_offset = 0x184,
- .route_val = BIT(16 + 7) | BIT(7),
- }, {
- /* pdm-m0 */
- .bank_num = 3,
- .pin = 22,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 8),
- }, {
- /* pdm-m1 */
- .bank_num = 2,
- .pin = 22,
- .func = 1,
- .route_offset = 0x184,
- .route_val = BIT(16 + 8) | BIT(8),
- }, {
- /* uart2-rxm0 */
- .bank_num = 1,
- .pin = 27,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 10),
- }, {
- /* uart2-rxm1 */
- .bank_num = 2,
- .pin = 14,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 10) | BIT(10),
- }, {
- /* uart3-rxm0 */
- .bank_num = 0,
- .pin = 17,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 9),
- }, {
- /* uart3-rxm1 */
- .bank_num = 1,
- .pin = 15,
- .func = 2,
- .route_offset = 0x184,
- .route_val = BIT(16 + 9) | BIT(9),
- },
+ MR_SAME(2, 0, 1, 0x184, RK_GENMASK_VAL(7, 7, 0)), /* cif-d2m0 */
+ MR_SAME(3, 3, 3, 0x184, RK_GENMASK_VAL(7, 7, 1)), /* cif-d2m1 */
+ MR_SAME(3, 22, 2, 0x184, RK_GENMASK_VAL(8, 8, 0)), /* pdm-m0 */
+ MR_SAME(2, 22, 1, 0x184, RK_GENMASK_VAL(8, 8, 1)), /* pdm-m1 */
+ MR_SAME(0, 17, 2, 0x184, RK_GENMASK_VAL(9, 9, 0)), /* uart3-rxm0 */
+ MR_SAME(1, 15, 2, 0x184, RK_GENMASK_VAL(9, 9, 1)), /* uart3-rxm1 */
+ MR_SAME(1, 27, 2, 0x184, RK_GENMASK_VAL(10, 10, 0)), /* uart2-rxm0 */
+ MR_SAME(2, 14, 2, 0x184, RK_GENMASK_VAL(10, 10, 1)), /* uart2-rxm1 */
};
static struct rockchip_mux_route_data rk3128_mux_route_data[] = {
- {
- /* spi-0 */
- .bank_num = 1,
- .pin = 10,
- .func = 1,
- .route_offset = 0x144,
- .route_val = BIT(16 + 3) | BIT(16 + 4),
- }, {
- /* spi-1 */
- .bank_num = 1,
-
[PATCH 11/13] pinctrl: rockchip: do codingstyle
Add RK3128 definitions to separate from other SoCs. Signed-off-by: Jianqun Xu --- drivers/pinctrl/pinctrl-rockchip.c | 8 +--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/drivers/pinctrl/pinctrl-rockchip.c b/drivers/pinctrl/pinctrl-rockchip.c index 04e7027ec8e1..3b74455dcdb2 100644 --- a/drivers/pinctrl/pinctrl-rockchip.c +++ b/drivers/pinctrl/pinctrl-rockchip.c @@ -1799,6 +1799,8 @@ static void rk2928_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, }; #define RK3128_PULL_OFFSET 0x118 +#define RK3128_PULL_PINS_PER_REG 16 +#define RK3128_PULL_BANK_STRIDE8 static void rk3128_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, int pin_num, struct regmap **regmap, @@ -1808,10 +1810,10 @@ static void rk3128_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, *regmap = info->regmap_base; *reg = RK3128_PULL_OFFSET; - *reg += bank->bank_num * RK2928_PULL_BANK_STRIDE; - *reg += ((pin_num / RK2928_PULL_PINS_PER_REG) * 4); + *reg += bank->bank_num * RK3128_PULL_BANK_STRIDE; + *reg += ((pin_num / RK3128_PULL_PINS_PER_REG) * 4); - *bit = pin_num % RK2928_PULL_PINS_PER_REG; + *bit = pin_num % RK3128_PULL_PINS_PER_REG; } #define RK3188_PULL_OFFSET 0x164 -- 2.17.1
[PATCH 07/13] pinctrl: rockchip: do codingstyle
Add RK3368 definitions to separate from other SoCs.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 34 ++
1 file changed, 20 insertions(+), 14 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index 71335ed003b3..8e3fa9011165 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -1987,6 +1987,9 @@ static void rk3308_calc_drv_reg_and_bit(struct
rockchip_pin_bank *bank,
#define RK3368_PULL_GRF_OFFSET 0x100
#define RK3368_PULL_PMU_OFFSET 0x10
+#define RK3368_PULL_BITS_PER_PIN 2
+#define RK3368_PULL_PINS_PER_REG 8
+#define RK3368_PULL_BANK_STRIDE16
static void rk3368_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank,
int pin_num, struct regmap **regmap,
@@ -1999,25 +2002,28 @@ static void rk3368_calc_pull_reg_and_bit(struct
rockchip_pin_bank *bank,
*regmap = info->regmap_pmu;
*reg = RK3368_PULL_PMU_OFFSET;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
- *bit = pin_num % RK3188_PULL_PINS_PER_REG;
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *reg += ((pin_num / RK3368_PULL_PINS_PER_REG) * 4);
+ *bit = pin_num % RK3368_PULL_PINS_PER_REG;
+ *bit *= RK3368_PULL_BITS_PER_PIN;
} else {
*regmap = info->regmap_base;
*reg = RK3368_PULL_GRF_OFFSET;
/* correct the offset, as we're starting with the 2nd bank */
*reg -= 0x10;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
+ *reg += bank->bank_num * RK3368_PULL_BANK_STRIDE;
+ *reg += ((pin_num / RK3368_PULL_PINS_PER_REG) * 4);
- *bit = (pin_num % RK3188_PULL_PINS_PER_REG);
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *bit = (pin_num % RK3368_PULL_PINS_PER_REG);
+ *bit *= RK3368_PULL_BITS_PER_PIN;
}
}
#define RK3368_DRV_PMU_OFFSET 0x20
#define RK3368_DRV_GRF_OFFSET 0x200
+#define RK3368_DRV_BITS_PER_PIN2
+#define RK3368_DRV_PINS_PER_REG8
+#define RK3368_DRV_BANK_STRIDE 16
static void rk3368_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank,
int pin_num, struct regmap **regmap,
@@ -2030,20 +2036,20 @@ static void rk3368_calc_drv_reg_and_bit(struct
rockchip_pin_bank *bank,
*regmap = info->regmap_pmu;
*reg = RK3368_DRV_PMU_OFFSET;
- *reg += ((pin_num / RK3288_DRV_PINS_PER_REG) * 4);
- *bit = pin_num % RK3288_DRV_PINS_PER_REG;
- *bit *= RK3288_DRV_BITS_PER_PIN;
+ *reg += ((pin_num / RK3368_DRV_PINS_PER_REG) * 4);
+ *bit = pin_num % RK3368_DRV_PINS_PER_REG;
+ *bit *= RK3368_DRV_BITS_PER_PIN;
} else {
*regmap = info->regmap_base;
*reg = RK3368_DRV_GRF_OFFSET;
/* correct the offset, as we're starting with the 2nd bank */
*reg -= 0x10;
- *reg += bank->bank_num * RK3288_DRV_BANK_STRIDE;
- *reg += ((pin_num / RK3288_DRV_PINS_PER_REG) * 4);
+ *reg += bank->bank_num * RK3368_DRV_BANK_STRIDE;
+ *reg += ((pin_num / RK3368_DRV_PINS_PER_REG) * 4);
- *bit = (pin_num % RK3288_DRV_PINS_PER_REG);
- *bit *= RK3288_DRV_BITS_PER_PIN;
+ *bit = (pin_num % RK3368_DRV_PINS_PER_REG);
+ *bit *= RK3368_DRV_BITS_PER_PIN;
}
}
--
2.17.1
[PATCH 08/13] pinctrl: rockchip: do codingstyle
Add RK3308 definitions to separate from other SoCs. Signed-off-by: Jianqun Xu --- drivers/pinctrl/pinctrl-rockchip.c | 22 ++ 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/drivers/pinctrl/pinctrl-rockchip.c b/drivers/pinctrl/pinctrl-rockchip.c index 8e3fa9011165..44f051af97c6 100644 --- a/drivers/pinctrl/pinctrl-rockchip.c +++ b/drivers/pinctrl/pinctrl-rockchip.c @@ -1952,6 +1952,9 @@ static void rk3228_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, } #define RK3308_PULL_OFFSET 0xa0 +#define RK3308_PULL_BITS_PER_PIN 2 +#define RK3308_PULL_PINS_PER_REG 8 +#define RK3308_PULL_BANK_STRIDE16 static void rk3308_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, int pin_num, struct regmap **regmap, @@ -1961,14 +1964,17 @@ static void rk3308_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank, *regmap = info->regmap_base; *reg = RK3308_PULL_OFFSET; - *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE; - *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4); + *reg += bank->bank_num * RK3308_PULL_BANK_STRIDE; + *reg += ((pin_num / RK3308_PULL_PINS_PER_REG) * 4); - *bit = (pin_num % RK3188_PULL_PINS_PER_REG); - *bit *= RK3188_PULL_BITS_PER_PIN; + *bit = (pin_num % RK3308_PULL_PINS_PER_REG); + *bit *= RK3308_PULL_BITS_PER_PIN; } #define RK3308_DRV_GRF_OFFSET 0x100 +#define RK3308_DRV_BITS_PER_PIN2 +#define RK3308_DRV_PINS_PER_REG8 +#define RK3308_DRV_BANK_STRIDE 16 static void rk3308_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, int pin_num, struct regmap **regmap, @@ -1978,11 +1984,11 @@ static void rk3308_calc_drv_reg_and_bit(struct rockchip_pin_bank *bank, *regmap = info->regmap_base; *reg = RK3308_DRV_GRF_OFFSET; - *reg += bank->bank_num * RK3288_DRV_BANK_STRIDE; - *reg += ((pin_num / RK3288_DRV_PINS_PER_REG) * 4); + *reg += bank->bank_num * RK3308_DRV_BANK_STRIDE; + *reg += ((pin_num / RK3308_DRV_PINS_PER_REG) * 4); - *bit = (pin_num % RK3288_DRV_PINS_PER_REG); - *bit *= RK3288_DRV_BITS_PER_PIN; + *bit = (pin_num % RK3308_DRV_PINS_PER_REG); + *bit *= RK3308_DRV_BITS_PER_PIN; } #define RK3368_PULL_GRF_OFFSET 0x100 -- 2.17.1
[PATCH 10/13] pinctrl: rockchip: do codingstyle
Add RK3288 definitons to separate from other SoCs.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 21 +
1 file changed, 13 insertions(+), 8 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index ec6a1a08f8b1..04e7027ec8e1 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -1855,6 +1855,11 @@ static void rk3188_calc_pull_reg_and_bit(struct
rockchip_pin_bank *bank,
}
#define RK3288_PULL_OFFSET 0x140
+#define RK3288_PULL_PMU_OFFSET 0x64
+#define RK3288_PULL_BITS_PER_PIN 2
+#define RK3288_PULL_PINS_PER_REG 8
+#define RK3288_PULL_BANK_STRIDE16
+
static void rk3288_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank,
int pin_num, struct regmap **regmap,
int *reg, u8 *bit)
@@ -1864,22 +1869,22 @@ static void rk3288_calc_pull_reg_and_bit(struct
rockchip_pin_bank *bank,
/* The first 24 pins of the first bank are located in PMU */
if (bank->bank_num == 0) {
*regmap = info->regmap_pmu;
- *reg = RK3188_PULL_PMU_OFFSET;
+ *reg = RK3288_PULL_PMU_OFFSET;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
- *bit = pin_num % RK3188_PULL_PINS_PER_REG;
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *reg += ((pin_num / RK3288_PULL_PINS_PER_REG) * 4);
+ *bit = pin_num % RK3288_PULL_PINS_PER_REG;
+ *bit *= RK3288_PULL_BITS_PER_PIN;
} else {
*regmap = info->regmap_base;
*reg = RK3288_PULL_OFFSET;
/* correct the offset, as we're starting with the 2nd bank */
*reg -= 0x10;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
+ *reg += bank->bank_num * RK3288_PULL_BANK_STRIDE;
+ *reg += ((pin_num / RK3288_PULL_PINS_PER_REG) * 4);
- *bit = (pin_num % RK3188_PULL_PINS_PER_REG);
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *bit = (pin_num % RK3288_PULL_PINS_PER_REG);
+ *bit *= RK3288_PULL_BITS_PER_PIN;
}
}
--
2.17.1
[PATCH 06/13] pinctrl: rockchip: do codingstyle
Add RK3399 definitions to separate from other SoCs.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 19 +++
1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index 1be4627f3877..71335ed003b3 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -2050,6 +2050,9 @@ static void rk3368_calc_drv_reg_and_bit(struct
rockchip_pin_bank *bank,
#define RK3399_PULL_GRF_OFFSET 0xe040
#define RK3399_PULL_PMU_OFFSET 0x40
#define RK3399_DRV_3BITS_PER_PIN 3
+#define RK3399_PULL_BITS_PER_PIN 2
+#define RK3399_PULL_PINS_PER_REG 8
+#define RK3399_PULL_BANK_STRIDE16
static void rk3399_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank,
int pin_num, struct regmap **regmap,
@@ -2062,22 +2065,22 @@ static void rk3399_calc_pull_reg_and_bit(struct
rockchip_pin_bank *bank,
*regmap = info->regmap_pmu;
*reg = RK3399_PULL_PMU_OFFSET;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
+ *reg += bank->bank_num * RK3399_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
- *bit = pin_num % RK3188_PULL_PINS_PER_REG;
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *reg += ((pin_num / RK3399_PULL_PINS_PER_REG) * 4);
+ *bit = pin_num % RK3399_PULL_PINS_PER_REG;
+ *bit *= RK3399_PULL_BITS_PER_PIN;
} else {
*regmap = info->regmap_base;
*reg = RK3399_PULL_GRF_OFFSET;
/* correct the offset, as we're starting with the 3rd bank */
*reg -= 0x20;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
+ *reg += bank->bank_num * RK3399_PULL_BANK_STRIDE;
+ *reg += ((pin_num / RK3399_PULL_PINS_PER_REG) * 4);
- *bit = (pin_num % RK3188_PULL_PINS_PER_REG);
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *bit = (pin_num % RK3399_PULL_PINS_PER_REG);
+ *bit *= RK3399_PULL_BITS_PER_PIN;
}
}
--
2.17.1
[PATCH 06/13] pinctrl: rockchip: do codingstyle
Add RK3399 definitions to separate from other SoCs.
Signed-off-by: Jianqun Xu
---
drivers/pinctrl/pinctrl-rockchip.c | 19 +++
1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/drivers/pinctrl/pinctrl-rockchip.c
b/drivers/pinctrl/pinctrl-rockchip.c
index 1be4627f3877..71335ed003b3 100644
--- a/drivers/pinctrl/pinctrl-rockchip.c
+++ b/drivers/pinctrl/pinctrl-rockchip.c
@@ -2050,6 +2050,9 @@ static void rk3368_calc_drv_reg_and_bit(struct
rockchip_pin_bank *bank,
#define RK3399_PULL_GRF_OFFSET 0xe040
#define RK3399_PULL_PMU_OFFSET 0x40
#define RK3399_DRV_3BITS_PER_PIN 3
+#define RK3399_PULL_BITS_PER_PIN 2
+#define RK3399_PULL_PINS_PER_REG 8
+#define RK3399_PULL_BANK_STRIDE16
static void rk3399_calc_pull_reg_and_bit(struct rockchip_pin_bank *bank,
int pin_num, struct regmap **regmap,
@@ -2062,22 +2065,22 @@ static void rk3399_calc_pull_reg_and_bit(struct
rockchip_pin_bank *bank,
*regmap = info->regmap_pmu;
*reg = RK3399_PULL_PMU_OFFSET;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
+ *reg += bank->bank_num * RK3399_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
- *bit = pin_num % RK3188_PULL_PINS_PER_REG;
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *reg += ((pin_num / RK3399_PULL_PINS_PER_REG) * 4);
+ *bit = pin_num % RK3399_PULL_PINS_PER_REG;
+ *bit *= RK3399_PULL_BITS_PER_PIN;
} else {
*regmap = info->regmap_base;
*reg = RK3399_PULL_GRF_OFFSET;
/* correct the offset, as we're starting with the 3rd bank */
*reg -= 0x20;
- *reg += bank->bank_num * RK3188_PULL_BANK_STRIDE;
- *reg += ((pin_num / RK3188_PULL_PINS_PER_REG) * 4);
+ *reg += bank->bank_num * RK3399_PULL_BANK_STRIDE;
+ *reg += ((pin_num / RK3399_PULL_PINS_PER_REG) * 4);
- *bit = (pin_num % RK3188_PULL_PINS_PER_REG);
- *bit *= RK3188_PULL_BITS_PER_PIN;
+ *bit = (pin_num % RK3399_PULL_PINS_PER_REG);
+ *bit *= RK3399_PULL_BITS_PER_PIN;
}
}
--
2.17.1
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, 08 Jul 2020, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: SeongJae Park
> Acked-by: Christian Brauner
> Acked-by: James Bottomley
> Reviewed-by: Mark Brown
> Signed-off-by: Theodore Ts'o
> Signed-off-by: Shuah Khan
> Signed-off-by: Dan Carpenter
> Signed-off-by: Kees Cook
> Signed-off-by: Olof Johansson
> Signed-off-by: Jonathan Corbet
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
FWIW,
Acked-by: Jani Nikula
> ---
> Changes since v2 [1]:
> - Pick up missed sign-offs and acks from Jon, Shuah, and Christian
> (sorry about missing those earlier).
>
> - Reformat the replacement list to make it easier to read.
>
> - Add 'controller' as a suggested replacement (Kees and Mark)
>
> - Fix up the paired term for 'performer' to be 'director' (Kees)
>
> - Collect some new acks, reviewed-by's, and sign-offs for v2.
>
> - Fix up Chris's email
>
> [1]:
> http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
>
>
> Documentation/process/coding-style.rst | 20
> 1 file changed, 20 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
> index 2657a55c6f12..1bee6f8affdb 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
> +'master / slave' (or 'slave' independent of 'master') and 'blacklist /
> +whitelist'.
> +
> +Recommended replacements for 'master / slave' are:
> +'{primary,main} / {secondary,replica,subordinate}'
> +'{initiator,requester} / {target,responder}'
> +'{controller,host} / {device,worker,proxy}'
> +'leader / follower'
> +'director / performer'
> +
> +Recommended replacements for 'blacklist/whitelist' are:
> +'denylist / allowlist'
> +'blocklist / passlist'
> +
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
>
> 5) Typedefs
> ---
>
> ___
> Ksummit-discuss mailing list
> ksummit-disc...@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
--
Jani Nikula, Intel Open Source Graphics Center
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Tue, 14 Jul 2020 06:39:49 +0200, j...@joshtriplett.org wrote: > > On Mon, Jul 13, 2020 at 10:02:24AM +0200, Takashi Iwai wrote: > > On Wed, 08 Jul 2020 20:14:27 +0200, > > Dan Williams wrote: > > > > > > +Recommended replacements for 'blacklist/whitelist' are: > > > +'denylist / allowlist' > > > +'blocklist / passlist' > > > > I started looking through the tree now and noticed there are lots of > > patterns like "whitelisted" or "blacklisted". How can the words fit > > for those? Actually, there are two cases like: > > > > - Foo is blacklisted > > - Allow to load the non-whitelisted cards > > > > Currently I'm replacing the former with "Foo is in denylist", but not > > sure about the latter case. I thought Kees mentioned about this, but > > don't remember the proposal... > > I find that "blocklist" works well as a verb: "foo is blocklisted", > "blocklist foo", or in some cases just "block foo" or "deny foo". For > the second case, phrasings like "allow loading non-safelisted cards" or > "allow loading cards not on the passlist" seem clear. Yes, that makes sense. I have wished some simple replacement with sed, but it seems that it'd be better to rephrase such texts in anyway. thanks, Takashi
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, Jul 13, 2020 at 10:02:24AM +0200, Takashi Iwai wrote: > On Wed, 08 Jul 2020 20:14:27 +0200, > Dan Williams wrote: > > > > +Recommended replacements for 'blacklist/whitelist' are: > > +'denylist / allowlist' > > +'blocklist / passlist' > > I started looking through the tree now and noticed there are lots of > patterns like "whitelisted" or "blacklisted". How can the words fit > for those? Actually, there are two cases like: > > - Foo is blacklisted > - Allow to load the non-whitelisted cards > > Currently I'm replacing the former with "Foo is in denylist", but not > sure about the latter case. I thought Kees mentioned about this, but > don't remember the proposal... I find that "blocklist" works well as a verb: "foo is blocklisted", "blocklist foo", or in some cases just "block foo" or "deny foo". For the second case, phrasings like "allow loading non-safelisted cards" or "allow loading cards not on the passlist" seem clear.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sun, Jul 12, 2020 at 9:26 PM Vinod Koul wrote: > > Hi Mauro, > > On 09-07-20, 13:11, Mauro Carvalho Chehab wrote: > > Em Mon, 06 Jul 2020 06:30:01 -0700 > > Joe Perches 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.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, 2020-07-13 at 10:02 +0200, Takashi Iwai wrote: > On Wed, 08 Jul 2020 20:14:27 +0200, > Dan Williams wrote: > > > > +Recommended replacements for 'blacklist/whitelist' are: > > +'denylist / allowlist' > > +'blocklist / passlist' > > I started looking through the tree now and noticed there are lots of > patterns like "whitelisted" or "blacklisted". How can the words fit > for those? Actually, there are two cases like: > > - Foo is blacklisted > - Allow to load the non-whitelisted cards > > Currently I'm replacing the former with "Foo is in denylist", but not > sure about the latter case. I thought Kees mentioned about this, but > don't remember the proposal... Remember these are suggestions for going forwards, not requirements for changing everything. We tend to be a community that likes make work projects because they're easier to do than solving the hard problems, but since we have over 100k occurrences of the various words in the kernel, changing them all would cause massive churn and disrupt forward development, which would cause way more harm than any gain from the change. James
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, 13 Jul 2020 11:39:56 +0200, Julia Lawall wrote: > > > > On Mon, 13 Jul 2020, Takashi Iwai wrote: > > > On Mon, 13 Jul 2020 10:43:28 +0200, > > Julia Lawall wrote: > > > > > > > > > > > > On Mon, 13 Jul 2020, Takashi Iwai wrote: > > > > > > > On Wed, 08 Jul 2020 20:14:27 +0200, > > > > Dan Williams wrote: > > > > > > > > > > +Recommended replacements for 'blacklist/whitelist' are: > > > > > +'denylist / allowlist' > > > > > +'blocklist / passlist' > > > > > > > > I started looking through the tree now and noticed there are lots of > > > > patterns like "whitelisted" or "blacklisted". How can the words fit > > > > for those? Actually, there are two cases like: > > > > > > > > - Foo is blacklisted > > > > - Allow to load the non-whitelisted cards > > > > > > > > Currently I'm replacing the former with "Foo is in denylist", but not > > > > > > In the denylist? > > > > Not really, only the allowlist exists in this case. > > I'm not sure to understand. in denylist is not grammatical. It needs "a" > or "the". Ah, now I see how I confused you. The two cases I mentioned in the above are completely individual. They were found in two different drivers. I put those just as two distinct examples for the passive form usages. Sorry for unclearness. What I meant about the latter was that "not in allowlist" doesn't mean it being "in denylist". It's simply unknown. Takashi
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, 13 Jul 2020, Takashi Iwai wrote: > On Mon, 13 Jul 2020 10:43:28 +0200, > Julia Lawall wrote: > > > > > > > > On Mon, 13 Jul 2020, Takashi Iwai wrote: > > > > > On Wed, 08 Jul 2020 20:14:27 +0200, > > > Dan Williams wrote: > > > > > > > > +Recommended replacements for 'blacklist/whitelist' are: > > > > +'denylist / allowlist' > > > > +'blocklist / passlist' > > > > > > I started looking through the tree now and noticed there are lots of > > > patterns like "whitelisted" or "blacklisted". How can the words fit > > > for those? Actually, there are two cases like: > > > > > > - Foo is blacklisted > > > - Allow to load the non-whitelisted cards > > > > > > Currently I'm replacing the former with "Foo is in denylist", but not > > > > In the denylist? > > Not really, only the allowlist exists in this case. I'm not sure to understand. in denylist is not grammatical. It needs "a" or "the". Maybe it has to be foo is denylisted? foo is in the implicit denyList? foo is not in the allowList? julia
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, 13 Jul 2020 10:43:28 +0200, Julia Lawall wrote: > > > > On Mon, 13 Jul 2020, Takashi Iwai wrote: > > > On Wed, 08 Jul 2020 20:14:27 +0200, > > Dan Williams wrote: > > > > > > +Recommended replacements for 'blacklist/whitelist' are: > > > +'denylist / allowlist' > > > +'blocklist / passlist' > > > > I started looking through the tree now and noticed there are lots of > > patterns like "whitelisted" or "blacklisted". How can the words fit > > for those? Actually, there are two cases like: > > > > - Foo is blacklisted > > - Allow to load the non-whitelisted cards > > > > Currently I'm replacing the former with "Foo is in denylist", but not > > In the denylist? Not really, only the allowlist exists in this case. thanks, Takashi
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Mon, 13 Jul 2020, Takashi Iwai wrote: > On Wed, 08 Jul 2020 20:14:27 +0200, > Dan Williams wrote: > > > > +Recommended replacements for 'blacklist/whitelist' are: > > +'denylist / allowlist' > > +'blocklist / passlist' > > I started looking through the tree now and noticed there are lots of > patterns like "whitelisted" or "blacklisted". How can the words fit > for those? Actually, there are two cases like: > > - Foo is blacklisted > - Allow to load the non-whitelisted cards > > Currently I'm replacing the former with "Foo is in denylist", but not In the denylist? julia > sure about the latter case. I thought Kees mentioned about this, but > don't remember the proposal... > > In anyway, I'm for the action: > Acked-by: Takashi Iwai > > > thanks, > > Takashi > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss >
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, 08 Jul 2020 20:14:27 +0200, Dan Williams wrote: > > +Recommended replacements for 'blacklist/whitelist' are: > +'denylist / allowlist' > +'blocklist / passlist' I started looking through the tree now and noticed there are lots of patterns like "whitelisted" or "blacklisted". How can the words fit for those? Actually, there are two cases like: - Foo is blacklisted - Allow to load the non-whitelisted cards Currently I'm replacing the former with "Foo is in denylist", but not sure about the latter case. I thought Kees mentioned about this, but don't remember the proposal... In anyway, I'm for the action: Acked-by: Takashi Iwai thanks, Takashi
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 11:14:27AM -0700, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. Acked-by: Joerg Roedel
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hi Mauro, On 09-07-20, 13:11, Mauro Carvalho Chehab wrote: > Em Mon, 06 Jul 2020 06:30:01 -0700 > Joe Perches 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
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
Hi Dan,
On 08-07-20, 11:14, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: SeongJae Park
> Acked-by: Christian Brauner
> Acked-by: James Bottomley
> Reviewed-by: Mark Brown
> Signed-off-by: Theodore Ts'o
> Signed-off-by: Shuah Khan
> Signed-off-by: Dan Carpenter
> Signed-off-by: Kees Cook
> Signed-off-by: Olof Johansson
> Signed-off-by: Jonathan Corbet
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
Acked-By: Vinod Koul
Thanks for working on this
> ---
> Changes since v2 [1]:
> - Pick up missed sign-offs and acks from Jon, Shuah, and Christian
> (sorry about missing those earlier).
>
> - Reformat the replacement list to make it easier to read.
>
> - Add 'controller' as a suggested replacement (Kees and Mark)
>
> - Fix up the paired term for 'performer' to be 'director' (Kees)
>
> - Collect some new acks, reviewed-by's, and sign-offs for v2.
>
> - Fix up Chris's email
>
> [1]:
> http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
>
>
> Documentation/process/coding-style.rst | 20
> 1 file changed, 20 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
> index 2657a55c6f12..1bee6f8affdb 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
> +'master / slave' (or 'slave' independent of 'master') and 'blacklist /
> +whitelist'.
> +
> +Recommended replacements for 'master / slave' are:
> +'{primary,main} / {secondary,replica,subordinate}'
> +'{initiator,requester} / {target,responder}'
> +'{controller,host} / {device,worker,proxy}'
> +'leader / follower'
> +'director / performer'
> +
> +Recommended replacements for 'blacklist/whitelist' are:
> +'denylist / allowlist'
> +'blocklist / passlist'
> +
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
>
> 5) Typedefs
> ---
>
> ___
> Ksummit-discuss mailing list
> ksummit-disc...@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
--
~Vinod
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 11:14:27AM -0700, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: SeongJae Park > Acked-by: Christian Brauner > Acked-by: James Bottomley > Reviewed-by: Mark Brown > Signed-off-by: Theodore Ts'o > Signed-off-by: Shuah Khan > Signed-off-by: Dan Carpenter > Signed-off-by: Kees Cook > Signed-off-by: Olof Johansson > Signed-off-by: Jonathan Corbet > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Thank you for working on this, Dan! Reviewed-by: Josh Triplett
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed 2020-07-08 00:23:59, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > +replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or > +'blocklist/passlist'. I don't see what is "non inclusive" about blacklist and whitelist... Plus, please grep kernel for actual usages. blocklist/denylist is _not_ suitable replacement for kernel use of blacklist. Pavel -- (english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html signature.asc Description: Digital signature
Re: [GIT PULL] CodingStyle: Inclusive Terminology
The pull request you sent on Fri, 10 Jul 2020 17:17:15 -0700: > git://git.kernel.org/pub/scm/linux/kernel/git/djbw/linux > tags/inclusive-terminology has been merged into torvalds/linux.git: https://git.kernel.org/torvalds/c/49decddd39e5f6132ccd7d9fdc3d7c470b0061bb Thank you! -- Deet-doot-dot, I am a bot. https://korg.wiki.kernel.org/userdoc/prtracker
[GIT PULL] CodingStyle: Inclusive Terminology
Hi Linus, please pull from: git://git.kernel.org/pub/scm/linux/kernel/git/djbw/linux tags/inclusive-terminology ...to receive a coding-style update for v5.9. The discussion has tapered off as well as the incoming ack, review, and sign-off tags. I did not see a reason to wait for the next merge window. Thank you. --- The following changes since commit 9ebcfadb0610322ac537dd7aa5d9cbc2b2894c68: Linux 5.8-rc3 (2020-06-28 15:00:24 -0700) are available in the Git repository at: git://git.kernel.org/pub/scm/linux/kernel/git/djbw/linux tags/inclusive-terminology for you to fetch changes up to a5f526ecb075a08c4a082355020166c7fe13ae27: CodingStyle: Inclusive Terminology (2020-07-03 23:54:35 -0700) Extend coding-style with inclusive-terminology recommendations. Dan Williams (1): CodingStyle: Inclusive Terminology Documentation/process/coding-style.rst | 20 1 file changed, 20 insertions(+) --- Acked-by: Randy Dunlap Acked-by: Dave Airlie Acked-by: SeongJae Park Acked-by: Christian Brauner Acked-by: James Bottomley Acked-by: Daniel Vetter Acked-by: Andy Lutomirski Acked-by: Laura Abbott Acked-by: Gustavo A. R. Silva Reviewed-by: Matthias Brugger Reviewed-by: Mark Brown Signed-off-by: Stephen Hemminger Signed-off-by: Theodore Ts'o Signed-off-by: Shuah Khan Signed-off-by: Dan Carpenter Signed-off-by: Kees Cook Signed-off-by: Olof Johansson Signed-off-by: Jonathan Corbet Signed-off-by: Chris Mason Signed-off-by: Greg Kroah-Hartman Signed-off-by: Dan Williams
Re: [PATCH v3] CodingStyle: Inclusive Terminology
On 7/8/20 13:14, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: SeongJae Park > Acked-by: Christian Brauner > Acked-by: James Bottomley > Reviewed-by: Mark Brown > Signed-off-by: Theodore Ts'o > Signed-off-by: Shuah Khan > Signed-off-by: Dan Carpenter > Signed-off-by: Kees Cook > Signed-off-by: Olof Johansson > Signed-off-by: Jonathan Corbet > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Acked-by: Gustavo A. R. Silva Thanks -- Gustavo
Re: [PATCH v3] CodingStyle: Inclusive Terminology
On Fri, Jul 10, 2020 at 2:13 PM Laura Abbott wrote: > > On 7/8/20 2:14 PM, Dan Williams wrote: > > Linux maintains a coding-style and its own idiomatic set of terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > [..] > Acked-by: Laura Abbott Thanks, Laura.
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Fri, Jul 10, 2020 at 2:12 PM Andy Lutomirski wrote: > > On Wed, Jul 8, 2020 at 11:30 AM Dan Williams wrote: > > > > Linux maintains a coding-style and its own idiomatic set of terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > Acked-by: Andy Lutomirski Thanks, Andy.
Re: [PATCH v3] CodingStyle: Inclusive Terminology
On 7/8/20 2:14 PM, Dan Williams wrote:
Linux maintains a coding-style and its own idiomatic set of terminology.
Update the style guidelines to recommend replacements for the terms
master/slave and blacklist/whitelist.
Link:
http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
Acked-by: Randy Dunlap
Acked-by: Dave Airlie
Acked-by: SeongJae Park
Acked-by: Christian Brauner
Acked-by: James Bottomley
Reviewed-by: Mark Brown
Signed-off-by: Theodore Ts'o
Signed-off-by: Shuah Khan
Signed-off-by: Dan Carpenter
Signed-off-by: Kees Cook
Signed-off-by: Olof Johansson
Signed-off-by: Jonathan Corbet
Signed-off-by: Chris Mason
Signed-off-by: Greg Kroah-Hartman
Signed-off-by: Dan Williams
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian
(sorry about missing those earlier).
- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
[1]:
http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
Documentation/process/coding-style.rst | 20
1 file changed, 20 insertions(+)
diff --git a/Documentation/process/coding-style.rst
b/Documentation/process/coding-style.rst
index 2657a55c6f12..1bee6f8affdb 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
+'master / slave' (or 'slave' independent of 'master') and 'blacklist /
+whitelist'.
+
+Recommended replacements for 'master / slave' are:
+'{primary,main} / {secondary,replica,subordinate}'
+'{initiator,requester} / {target,responder}'
+'{controller,host} / {device,worker,proxy}'
+'leader / follower'
+'director / performer'
+
+Recommended replacements for 'blacklist/whitelist' are:
+'denylist / allowlist'
+'blocklist / passlist'
+
+Exceptions for introducing new usage is to maintain a userspace ABI/API,
+or when updating code for an existing (as of 2020) hardware or protocol
+specification that mandates those terms. For new specifications
+translate specification usage of the terminology to the kernel coding
+standard where possible.
5) Typedefs
---
Acked-by: Laura Abbott
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 11:30 AM Dan Williams wrote: > > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. Acked-by: Andy Lutomirski
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:30 PM Dan Williams wrote: > > On Sat, Jul 4, 2020 at 5:41 PM Kees Cook wrote: > > > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams 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 > > > Cc: Kees Cook > > > Signed-off-by: Chris Mason > > > Signed-off-by: Greg Kroah-Hartman > > > Signed-off-by: Dan Williams > > > > (nit: isn't this a Co-developed-by chain, not a SoB chain?) > > > > Acked-by: Kees Cook > > > > Comments below... > > > > > --- > > > 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'. > > > > Keeping "master" in a "master/slave" pairing (i.e. replacing only > > "slave") seems incomplete to me. If "master" is paired with "slave", it > > should be replaced too. Potential examples: 'primary', 'leader', > > 'principle', > > 'controller', 'sender', 'initial'. > > Yes, this matches Andy's feedback, will add. > > > Similarly, for "whitelist/blacklist", "whitelist" needs to replaced when > > "blacklist" has been. For example, seccomp documentation[1] uses > > "allow-list" and "deny-list". > > > > [1] https://man7.org/linux/man-pages/man2/seccomp.2.html > > Oh, good to know will make that change. Looks like that change already happened. And the new language is IMO not vastly better than the old language. I'll send a patch.
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Fri, Jul 10, 2020 at 9:03 AM Linus Walleij wrote: > > On Wed, Jul 8, 2020 at 9:40 AM Dan Williams wrote: > > > Linux maintains a coding-style and its own idiomatic set of terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > > > Link: > > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > > Cc: Jonathan Corbet > > Acked-by: Randy Dunlap > > Acked-by: Dave Airlie > > Acked-by: Kees Cook > > Acked-by: SeongJae Park > > Signed-off-by: Olof Johansson > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > Signed-off-by: Linus Walleij Thanks Linus. > > An interesting piece on the topic is Douglas R. Hofstadter's > satirical "A Person paper On Purity in Language" from 1985, > which is funny, witty, Jonathan Swift-like and at one point > convinced me on the importance of proper language in > my professional work. > http://www.cs.virginia.edu/~evans/cs655/readings/purity.html ...and thanks for that laugh.
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 9:40 AM Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Cc: Jonathan Corbet > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: Kees Cook > Acked-by: SeongJae Park > Signed-off-by: Olof Johansson > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Signed-off-by: Linus Walleij An interesting piece on the topic is Douglas R. Hofstadter's satirical "A Person paper On Purity in Language" from 1985, which is funny, witty, Jonathan Swift-like and at one point convinced me on the importance of proper language in my professional work. http://www.cs.virginia.edu/~evans/cs655/readings/purity.html Thanks, Linus Walleij
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
>>> Nobody has a problem understanding "blacklist" and "whitelist". These >>> are universally understood words even outside of computing. Claiming >>> that we need clearer alternatives is smoke and mirrors. >> >> Actually, as a non-native English speaker, the first time I saw >> "list", I had to do some research in order to understand what it >> means :-) You have to research and lookup *any* new words in a language when you see them the first time. You'd also have to look up "allow" when seeing it for the first time too. > Thanks for the perspective. This is why we need clear and uniform words. > Our community is global. English isn't English everywhere either. > So, the proposed alternatives "allowlist" and "denylist" are better because they are not English but are in some kind of a global language? Your argumentation doesn't seem to pan out. The language in the Linux source is English, and in that language "blacklist" has a meaning that is not limited to computing but is universal, irrespective of the field of science, and is even used in everyday life. And this meaning isn't associated with ethnic differences. As I stated multiple times, I support removing all references to slavery and masters. But trying to avoid "blacklist" is not just pointless but also useless. The real problem is that "black" by itself already has a negative connotation. so instead of blocking words unrelated to ethnicity, we should not call Afro-Americans "blacks" anymore. The problem is that a group of people are marked with "black" which is a word with black connotation. We should stop calling them blacks, and that'd be a real solution (at least as far as the language is concerned). Raschko T.
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Thu, Jul 9, 2020 at 2:45 AM Matthias Brugger wrote: > > > > On 08/07/2020 20:14, Dan Williams wrote: > > Linux maintains a coding-style and its own idiomatic set of terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > > > Link: > > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > > Acked-by: Randy Dunlap > > Acked-by: Dave Airlie > > Acked-by: SeongJae Park > > Acked-by: Christian Brauner > > Acked-by: James Bottomley > > Reviewed-by: Mark Brown > > Signed-off-by: Theodore Ts'o > > Signed-off-by: Shuah Khan > > Signed-off-by: Dan Carpenter > > Signed-off-by: Kees Cook > > Signed-off-by: Olof Johansson > > Signed-off-by: Jonathan Corbet > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > Reviewed-by: Matthias Brugger Got it, thanks Matthias.
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Thu, Jul 9, 2020 at 12:26 AM Daniel Vetter wrote: > > On Wed, Jul 8, 2020 at 8:30 PM Dan Williams wrote: > > > > Linux maintains a coding-style and its own idiomatic set of terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > > > Link: > > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > > Acked-by: Randy Dunlap > > Acked-by: Dave Airlie > > Acked-by: SeongJae Park > > Acked-by: Christian Brauner > > Acked-by: James Bottomley > > Reviewed-by: Mark Brown > > Signed-off-by: Theodore Ts'o > > Signed-off-by: Shuah Khan > > Signed-off-by: Dan Carpenter > > Signed-off-by: Kees Cook > > Signed-off-by: Olof Johansson > > Signed-off-by: Jonathan Corbet > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > Replied to the old version, once more here so it's not lost. > > Acked-by: Daniel Vetter Got it, thanks Daniel.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Thu, 9 Jul 2020 17:13:51 +0100 Mark Brown wrote: > On Thu, Jul 09, 2020 at 10:01:18AM -0600, Shuah Khan wrote: > > On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: > > > > For coherency, if "blacklist/whitelist" won't be used anymore, an > > > alternative to graylist should also be provided. > > > What is "graylist"? Does it mean in between allow/deny? > > Yes. Typically it's used in situations where you don't want to deny > something but might for example want to do extra checks to verify that > things are OK. The only time I use greylist is for postgrey, that when an email comes in, it will initially reject it, expecting the mail server to try again, and the second time it lets it through. This does stop a lot of spam, at the cost of waiting up to a few hours for email :-/ -- Steve
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Thu, 2020-07-09 at 17:13 +0100, Mark Brown wrote: > On Thu, Jul 09, 2020 at 10:01:18AM -0600, Shuah Khan wrote: > > On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: > > > For coherency, if "blacklist/whitelist" won't be used anymore, an > > > alternative to graylist should also be provided. > > What is "graylist"? Does it mean in between allow/deny? > > Yes. Typically it's used in situations where you don't want to deny > something but might for example want to do extra checks to verify > that things are OK. greylisting was originally pioneered by email. It's where you initially reject an email but remember you did so and then let it through if the retries follow an RFC mandated pattern. The technical use spread from there since the technique (treating something as untrusted until it proves trust) is very useful. It has its origin in the English idiom "grey area" expressing doubt or lack of clarity. The etymology of "grey area" is a grey area, but I'd bet it has to do with not having the clarity of black and white ... but is equally likely to be tied to Yin and Yang. Grey is also used in England to describe the lack of clarity given by mist or fog (he woke up and saw the world was very grey). I'd say we just leave it alone as too distantly related to any problematic uses. James signature.asc Description: This is a digitally signed message part
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Thu, Jul 09, 2020 at 10:01:18AM -0600, Shuah Khan wrote: > On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: > > For coherency, if "blacklist/whitelist" won't be used anymore, an > > alternative to graylist should also be provided. > What is "graylist"? Does it mean in between allow/deny? Yes. Typically it's used in situations where you don't want to deny something but might for example want to do extra checks to verify that things are OK. signature.asc Description: PGP signature
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 7/9/20 4:43 AM, Mauro Carvalho Chehab wrote: Em Tue, 7 Jul 2020 01:58:21 +0200 Tibor Raschko escreveu: Allowlist/denylist terms are intuitive and action based which have a globally uniform meaning. Nobody has a problem understanding "blacklist" and "whitelist". These are universally understood words even outside of computing. Claiming that we need clearer alternatives is smoke and mirrors. Actually, as a non-native English speaker, the first time I saw "list", I had to do some research in order to understand what it means :-) Thanks for the perspective. This is why we need clear and uniform words. Our community is global. English isn't English everywhere either. That reminds me: what about "graylist"? For coherency, if "blacklist/whitelist" won't be used anymore, an alternative to graylist should also be provided. Right now, it seems that only ACPI uses it: $ git grep -i graylist drivers/clocksource/acpi_pm.c:static void acpi_pm_check_graylist(struct pci_dev *dev) drivers/clocksource/acpi_pm.c: acpi_pm_check_graylist); drivers/clocksource/acpi_pm.c: acpi_pm_check_graylist); What is "graylist"? Does it mean in between allow/deny? thanks, -- Shuah
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Em Mon, 06 Jul 2020 06:30:01 -0700 Joe Perches escreveu: > On Mon, 2020-07-06 at 09:04 -0400, Matthew Wilcox wrote: > > On Mon, Jul 6, 2020 at 8:59 AM Joe Perches 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 > 5866 drivers/interconnect > 6835 drivers/soundwire > 7821 drivers/spi > 8698 drivers/w1 > 9508 drivers/media > 10481 drivers/infiniband > 11440 drivers/ata > 12317 drivers/scsi > 13267 drivers/fsi > 14240 drivers/tty > 15225 drivers/vme > 16223 drivers/staging > 17157 drivers/mmc > 18155 drivers/usb > 19141 drivers/video > 20140 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
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
Em Tue, 7 Jul 2020 01:58:21 +0200 Tibor Raschko escreveu: > > Allowlist/denylist terms are intuitive and action based which have a > > globally uniform meaning. > > Nobody has a problem understanding "blacklist" and "whitelist". These > are universally understood words even outside of computing. Claiming > that we need clearer alternatives is smoke and mirrors. Actually, as a non-native English speaker, the first time I saw "list", I had to do some research in order to understand what it means :-) That reminds me: what about "graylist"? For coherency, if "blacklist/whitelist" won't be used anymore, an alternative to graylist should also be provided. Right now, it seems that only ACPI uses it: $ git grep -i graylist drivers/clocksource/acpi_pm.c:static void acpi_pm_check_graylist(struct pci_dev *dev) drivers/clocksource/acpi_pm.c: acpi_pm_check_graylist); drivers/clocksource/acpi_pm.c: acpi_pm_check_graylist); Thanks, Mauro
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On 08/07/2020 20:14, Dan Williams wrote:
Linux maintains a coding-style and its own idiomatic set of terminology.
Update the style guidelines to recommend replacements for the terms
master/slave and blacklist/whitelist.
Link:
http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
Acked-by: Randy Dunlap
Acked-by: Dave Airlie
Acked-by: SeongJae Park
Acked-by: Christian Brauner
Acked-by: James Bottomley
Reviewed-by: Mark Brown
Signed-off-by: Theodore Ts'o
Signed-off-by: Shuah Khan
Signed-off-by: Dan Carpenter
Signed-off-by: Kees Cook
Signed-off-by: Olof Johansson
Signed-off-by: Jonathan Corbet
Signed-off-by: Chris Mason
Signed-off-by: Greg Kroah-Hartman
Signed-off-by: Dan Williams
Reviewed-by: Matthias Brugger
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian
(sorry about missing those earlier).
- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
[1]:
http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
Documentation/process/coding-style.rst | 20
1 file changed, 20 insertions(+)
diff --git a/Documentation/process/coding-style.rst
b/Documentation/process/coding-style.rst
index 2657a55c6f12..1bee6f8affdb 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
+'master / slave' (or 'slave' independent of 'master') and 'blacklist /
+whitelist'.
+
+Recommended replacements for 'master / slave' are:
+'{primary,main} / {secondary,replica,subordinate}'
+'{initiator,requester} / {target,responder}'
+'{controller,host} / {device,worker,proxy}'
+'leader / follower'
+'director / performer'
+
+Recommended replacements for 'blacklist/whitelist' are:
+'denylist / allowlist'
+'blocklist / passlist'
+
+Exceptions for introducing new usage is to maintain a userspace ABI/API,
+or when updating code for an existing (as of 2020) hardware or protocol
+specification that mandates those terms. For new specifications
+translate specification usage of the terminology to the kernel coding
+standard where possible.
5) Typedefs
---
___
Ksummit-discuss mailing list
ksummit-disc...@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Re: [Ksummit-discuss] [PATCH v3] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 8:30 PM Dan Williams wrote:
>
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: SeongJae Park
> Acked-by: Christian Brauner
> Acked-by: James Bottomley
> Reviewed-by: Mark Brown
> Signed-off-by: Theodore Ts'o
> Signed-off-by: Shuah Khan
> Signed-off-by: Dan Carpenter
> Signed-off-by: Kees Cook
> Signed-off-by: Olof Johansson
> Signed-off-by: Jonathan Corbet
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
Replied to the old version, once more here so it's not lost.
Acked-by: Daniel Vetter
> ---
> Changes since v2 [1]:
> - Pick up missed sign-offs and acks from Jon, Shuah, and Christian
> (sorry about missing those earlier).
>
> - Reformat the replacement list to make it easier to read.
>
> - Add 'controller' as a suggested replacement (Kees and Mark)
>
> - Fix up the paired term for 'performer' to be 'director' (Kees)
>
> - Collect some new acks, reviewed-by's, and sign-offs for v2.
>
> - Fix up Chris's email
>
> [1]:
> http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
>
>
> Documentation/process/coding-style.rst | 20
> 1 file changed, 20 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
> index 2657a55c6f12..1bee6f8affdb 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
> +'master / slave' (or 'slave' independent of 'master') and 'blacklist /
> +whitelist'.
> +
> +Recommended replacements for 'master / slave' are:
> +'{primary,main} / {secondary,replica,subordinate}'
> +'{initiator,requester} / {target,responder}'
> +'{controller,host} / {device,worker,proxy}'
> +'leader / follower'
> +'director / performer'
> +
> +Recommended replacements for 'blacklist/whitelist' are:
> +'denylist / allowlist'
> +'blocklist / passlist'
> +
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
>
> 5) Typedefs
> ---
>
> ___
> Ksummit-discuss mailing list
> ksummit-disc...@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
Re: [Ksummit-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, 08 Jul 2020 00:23:59 -0700 Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Cc: Jonathan Corbet > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: Kees Cook > Acked-by: SeongJae Park > Signed-off-by: Olof Johansson > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Thanks for doing this. Signed-off-by: Stephen Hemminger
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams 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 > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Acked-by: Daniel Vetter > --- > 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 > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..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 ` 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 `? 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 etym
[PATCH v3] CodingStyle: Inclusive Terminology
Linux maintains a coding-style and its own idiomatic set of terminology.
Update the style guidelines to recommend replacements for the terms
master/slave and blacklist/whitelist.
Link:
http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
Acked-by: Randy Dunlap
Acked-by: Dave Airlie
Acked-by: SeongJae Park
Acked-by: Christian Brauner
Acked-by: James Bottomley
Reviewed-by: Mark Brown
Signed-off-by: Theodore Ts'o
Signed-off-by: Shuah Khan
Signed-off-by: Dan Carpenter
Signed-off-by: Kees Cook
Signed-off-by: Olof Johansson
Signed-off-by: Jonathan Corbet
Signed-off-by: Chris Mason
Signed-off-by: Greg Kroah-Hartman
Signed-off-by: Dan Williams
---
Changes since v2 [1]:
- Pick up missed sign-offs and acks from Jon, Shuah, and Christian
(sorry about missing those earlier).
- Reformat the replacement list to make it easier to read.
- Add 'controller' as a suggested replacement (Kees and Mark)
- Fix up the paired term for 'performer' to be 'director' (Kees)
- Collect some new acks, reviewed-by's, and sign-offs for v2.
- Fix up Chris's email
[1]:
http://lore.kernel.org/r/159419296487.2464622.863943877093636532.st...@dwillia2-desk3.amr.corp.intel.com
Documentation/process/coding-style.rst | 20
1 file changed, 20 insertions(+)
diff --git a/Documentation/process/coding-style.rst
b/Documentation/process/coding-style.rst
index 2657a55c6f12..1bee6f8affdb 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -319,6 +319,26 @@ 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 and documentation, avoid introducing new usage of
+'master / slave' (or 'slave' independent of 'master') and 'blacklist /
+whitelist'.
+
+Recommended replacements for 'master / slave' are:
+'{primary,main} / {secondary,replica,subordinate}'
+'{initiator,requester} / {target,responder}'
+'{controller,host} / {device,worker,proxy}'
+'leader / follower'
+'director / performer'
+
+Recommended replacements for 'blacklist/whitelist' are:
+'denylist / allowlist'
+'blocklist / passlist'
+
+Exceptions for introducing new usage is to maintain a userspace ABI/API,
+or when updating code for an existing (as of 2020) hardware or protocol
+specification that mandates those terms. For new specifications
+translate specification usage of the terminology to the kernel coding
+standard where possible.
5) Typedefs
---
Re: [Tech-board-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
On 7/8/20 1:23 AM, Dan Williams wrote: Linux maintains a coding-style and its own idiomatic set of terminology. Update the style guidelines to recommend replacements for the terms master/slave and blacklist/whitelist. Link: http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com Cc: Jonathan Corbet Acked-by: Randy Dunlap Acked-by: Dave Airlie Acked-by: Kees Cook Acked-by: SeongJae Park Signed-off-by: Olof Johansson Signed-off-by: Chris Mason Signed-off-by: Greg Kroah-Hartman Signed-off-by: Dan Williams --- Changes since v1 [1] - Drop inclusive-terminology.rst, it is in the lore archives if the arguments are needed for future debates, but otherwise no pressing need to carry it in the tree (Linus, James) - Update the recommended terms to include replacement for 'master' and 'whitelist' (Kees, Andy) - Add 'target' as a replacement (Andy) - Add 'device' as a replacement (Mark) - Collect acks and signed-off-bys. Yes, the sign-offs are not reflective of a submission chain, but I kept "Signed-off-by" if people offered it. Dan, Looks like you missed my Signed-off I sent for v1 Please add my Signed-off-by: Shuah Khan thanks, -- Shuah
Re: [Ksummit-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 12:23:59AM -0700, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Cc: Jonathan Corbet
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: Kees Cook
> Acked-by: SeongJae Park
> Signed-off-by: Olof Johansson
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
> ---
Probably got lost somewhere:
Acked-by: Christian Brauner
> Changes since v1 [1]
> - Drop inclusive-terminology.rst, it is in the lore archives if the
> arguments are needed for future debates, but otherwise no pressing
> need to carry it in the tree (Linus, James)
>
> - Update the recommended terms to include replacement for 'master' and
> 'whitelist' (Kees, Andy)
>
> - Add 'target' as a replacement (Andy)
>
> - Add 'device' as a replacement (Mark)
>
> - Collect acks and signed-off-bys. Yes, the sign-offs are not reflective
> of a submission chain, but I kept "Signed-off-by" if people offered
> it.
>
> - Non-change: I did not add explicit language as to what to do with
> existing usages. My personal inclination is to prioritize this
> coding-style cleanup higher than others, but the coding-style document
> has typically not indicated policy on how cleanups are handled by
> subsystems. It will be a case by case effort and consideration.
>
> [1]:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
>
> Documentation/process/coding-style.rst | 13 +
> 1 file changed, 13 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
> index 2657a55c6f12..a5b61e9005ac 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -319,6 +319,19 @@ 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 'master/slave' (or
> +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> +'primary/replica', '{initiator,requester}/{target,responder}',
> +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
> +replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or
> +'blocklist/passlist'.
> +
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
>
> 5) Typedefs
> ---
>
> ___
> Ksummit-discuss mailing list
> ksummit-disc...@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss
Re: [Tech-board-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, 2020-07-08 at 04:04 -0700, Joe Perches wrote: > On Wed, 2020-07-08 at 00:23 -0700, Dan Williams wrote: > > Linux maintains a coding-style and its own idiomatic set of > > terminology. > > Update the style guidelines to recommend replacements for the terms > > master/slave and blacklist/whitelist. > > > > Link: http://lore.kernel.org/r/159389297140.2210796.135901422546687 > > 87525.st...@dwillia2-desk3.amr.corp.intel.com > > Cc: Jonathan Corbet > > Acked-by: Randy Dunlap > > Acked-by: Dave Airlie > > Acked-by: Kees Cook > > Acked-by: SeongJae Park > > Signed-off-by: Olof Johansson > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > --- > > Changes since v1 [1] > > - Drop inclusive-terminology.rst, it is in the lore archives if the > > arguments are needed for future debates, but otherwise no > > pressing > > need to carry it in the tree (Linus, James) Acked-by: James Bottomley > Where did Linus publicly state this was unnecessary? https://lists.linuxfoundation.org/pipermail/tech-board-discuss/2020-July/000412.html James
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 4:05 AM Joe Perches wrote:
>
> On Wed, 2020-07-08 at 00:23 -0700, Dan Williams wrote:
> > Linux maintains a coding-style and its own idiomatic set of terminology.
> > Update the style guidelines to recommend replacements for the terms
> > master/slave and blacklist/whitelist.
> >
> > Link:
> > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> > Cc: Jonathan Corbet
> > Acked-by: Randy Dunlap
> > Acked-by: Dave Airlie
> > Acked-by: Kees Cook
> > Acked-by: SeongJae Park
> > Signed-off-by: Olof Johansson
> > Signed-off-by: Chris Mason
> > Signed-off-by: Greg Kroah-Hartman
> > Signed-off-by: Dan Williams
> > ---
> > Changes since v1 [1]
> > - Drop inclusive-terminology.rst, it is in the lore archives if the
> > arguments are needed for future debates, but otherwise no pressing
> > need to carry it in the tree (Linus, James)
>
> Where did Linus publicly state this was unnecessary?
James suggested dropping the document, Linus agreed, I agreed.
>
> > diff --git a/Documentation/process/coding-style.rst
> > b/Documentation/process/coding-style.rst
> []
> > @@ -319,6 +319,19 @@ 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 'master/slave' (or
> > +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> > +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> > +'primary/replica', '{initiator,requester}/{target,responder}',
> > +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
> > +replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or
> > +'blocklist/passlist'.
>
> Adding a reference to SeongJae Park's introduction of
> scripts/deprecated_terms.txt or the like might help
> make this list unnecessary if more terms are added.
Per his last mail he's going to update his checker to refer to coding-style.
> > +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> > +or when updating code for an existing (as of 2020) hardware or protocol
> > +specification that mandates those terms. For new specifications
> > +translate specification usage of the terminology to the kernel coding
> > +standard where possible.
>
> I believe any existing code should not be changed,
> not just code that is required to be maintained
> for userspace.
We have existing practices around coding-style changes that can be
applied here. Some subsystems are open to modernizing their code with
respect to the latest coding style recommendations and others,
especially those with ancient drivers don't want the churn. So, I
would hold these cleanups to the same standard.
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 1:22 AM Kees Cook wrote:
>
> On Wed, Jul 08, 2020 at 12:23:59AM -0700, Dan Williams wrote:
> > Linux maintains a coding-style and its own idiomatic set of terminology.
> > Update the style guidelines to recommend replacements for the terms
> > master/slave and blacklist/whitelist.
> >
> > Link:
> > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> > Cc: Jonathan Corbet
> > Acked-by: Randy Dunlap
> > Acked-by: Dave Airlie
> > Acked-by: Kees Cook
> > Acked-by: SeongJae Park
> > Signed-off-by: Olof Johansson
> > Signed-off-by: Chris Mason
> > Signed-off-by: Greg Kroah-Hartman
> > Signed-off-by: Dan Williams
> > ---
> > Changes since v1 [1]
> > - Drop inclusive-terminology.rst, it is in the lore archives if the
> > arguments are needed for future debates, but otherwise no pressing
> > need to carry it in the tree (Linus, James)
> >
> > - Update the recommended terms to include replacement for 'master' and
> > 'whitelist' (Kees, Andy)
> >
> > - Add 'target' as a replacement (Andy)
> >
> > - Add 'device' as a replacement (Mark)
> >
> > - Collect acks and signed-off-bys. Yes, the sign-offs are not reflective
> > of a submission chain, but I kept "Signed-off-by" if people offered
> > it.
>
> In that case, I will "upgrade" my Ack. ;)
>
> Signed-off-by: Kees Cook
>
> :)
Noted.
>
> > - Non-change: I did not add explicit language as to what to do with
> > existing usages. My personal inclination is to prioritize this
> > coding-style cleanup higher than others, but the coding-style document
> > has typically not indicated policy on how cleanups are handled by
> > subsystems. It will be a case by case effort and consideration.
>
> While I'd like to have published guidance on fixing existing language
> (which is already underway[1]), I agree: let's start here.
>
> > [...]
> > +For symbol names, avoid introducing new usage of 'master/slave' (or
>
> For symbol names, comments, documentation, and other language, avoid
> introducing ...
How about "symbol names and documentation" because I'm struggling to
think of an example of where this terminology would leak in outside
those broad categories.
> > +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> > +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> > +'primary/replica', '{initiator,requester}/{target,responder}',
>
> the main and primary should be merged, IMO:
>
> '{primary,main}/{secondary,replica,subordinate}'
Ok.
>
> > +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
>
> leader/performer does not track for me. Split it out?
>
> 'leader/follower', 'director/performer'
Sounds good.
> I have also seen:
>
> 'controller/worker'
Will add.
Thanks Kees.
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 12:23:59AM -0700, Dan Williams wrote: > Linux maintains a coding-style and its own idiomatic set of terminology. > Update the style guidelines to recommend replacements for the terms > master/slave and blacklist/whitelist. > > Link: > http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com > Cc: Jonathan Corbet > Acked-by: Randy Dunlap > Acked-by: Dave Airlie > Acked-by: Kees Cook > Acked-by: SeongJae Park > Signed-off-by: Olof Johansson > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Signed-off-by: Theodore Ts'o
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, 2020-07-08 at 00:23 -0700, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Cc: Jonathan Corbet
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: Kees Cook
> Acked-by: SeongJae Park
> Signed-off-by: Olof Johansson
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
> ---
> Changes since v1 [1]
> - Drop inclusive-terminology.rst, it is in the lore archives if the
> arguments are needed for future debates, but otherwise no pressing
> need to carry it in the tree (Linus, James)
Where did Linus publicly state this was unnecessary?
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
[]
> @@ -319,6 +319,19 @@ 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 'master/slave' (or
> +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> +'primary/replica', '{initiator,requester}/{target,responder}',
> +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
> +replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or
> +'blocklist/passlist'.
Adding a reference to SeongJae Park's introduction of
scripts/deprecated_terms.txt or the like might help
make this list unnecessary if more terms are added.
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
I believe any existing code should not be changed,
not just code that is required to be maintained
for userspace.
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 08/07/2020 06:42, Stephen Hemminger wrote: > On Tue, 7 Jul 2020 02:03:36 +0300 > Pavel Begunkov wrote: > >> On 07/07/2020 01:28, Steven Rostedt wrote: >>> On Tue, 7 Jul 2020 01:17:47 +0300 >>> Pavel Begunkov wrote: >>> Totally agree with you! But do we care then whether two _devices_ or _objects_ are slave-master? Can't see how it fundamentally differs. >>> >>> The term slave carries a lot more meaning than subordinate. I replied to >>> someone else but later realized that the person sent me their reply >>> offlist, so my reply to them was also offlist. What I told them was, >>> back in college (decades ago), when I first mentioned "master/slave" in >>> conversation (I think it was about hard drives), a person in that >>> conversation stated that those were not very nice terms to use. I blew >>> it off back then, but after listening to more people, I found that >>> using "slave" even to describe a device is not something that people >>> care to hear about. >> >> That's cultural, but honestly I've never seen such a person. I still >> don't understand, why having secondary or subordinate object belittling >> the owned side by not providing it the same rights and freedom is OK, >> but slave/master objects are not. Where is the line? >> >> >>> >>> And in actuality, does one device actually enslave another device? I >>> think that terminology is misleading to begin with. >> >> As mentioned, I do like good clear terminology, and if it conveys the idea >> better, etc., then it's worth to try. And IMHO that's the right reasoning >> that should be behind. Otherwise, for almost every word we can find a person >> seeing something subjectively offensive or at least bad in it. > > Wherever possible the kernel should use the same terminology as the current > standard in that area. Many of the master/slave references in the networking > code are for protocols based on IEEE 802 standards (unfortunately paywalled). > The current version of those standards do not use this kind of wording and the > standards committees are also actively working on inclusive language > statemets. > > As far as the use of master/slave for bonding, bridge, team etc, it > looks like Linux just invented using those terms since I don't see it > any other vendors implementations Cisco/Juniper/Arista/... Linux terms > are different than industry norms in networking, this is not a good > thing. But changing human expectations is hard. And that's a perfectly convincing argument for a change -- consistency makes it easier to work with specs and code. I've never said anything against. I care about arguments being logically sound, as yours are. And the author neither provides such, nor IMHO actually helps the issues it raised. -- Pavel Begunkov
Re: [Ksummit-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
Signed-off-by: Dan Carpenter regards, dan carpenter
Re: [Tech-board-discuss] [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 12:23:59AM -0700, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
Reviwed-by: Mark Brown
> +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
We could have controller as well as host.
signature.asc
Description: PGP signature
Re: Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Wed, 8 Jul 2020 00:12:03 -0700 Dan Williams wrote: > On Mon, Jul 6, 2020 at 11:56 PM SeongJae Park wrote: > > > > Hello, > > > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > > 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. > > > > I'm glad to see this patch. > > > > > > > > Cc: Jonathan Corbet > > > Cc: Kees Cook > > > Signed-off-by: Chris Mason > > > Signed-off-by: Greg Kroah-Hartman > > > Signed-off-by: Dan Williams > > > > Acked-by: SeongJae Park > > > > > --- > > > 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'. > > > > I have submitted a couple of patches for automated encouragement of the the > > inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, > > the > > version says only "please consider using 'denylist' and 'allowlist' instead > > of > > 'blacklist' and 'whitelist'" for now. I think we could add more terms in > > there > > based on this discussion. I could do that after this patch is merged, or > > you > > could do that yourself in the next spin of this patch. Please do whatever > > you > > feel comfort. > > > > [1] > > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 > > [2] > > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed > > > > Thank you for stepping up to take this on, much appreciated. > > I think I'll leave it to you to fixup checkpatch after the final > version of this patch is merged. It may be as simple as "See section 4 > 'Naming' in coding-style for suggested replacements". Agreed, I will do that :) Thanks, SeongJae Park
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 08, 2020 at 12:23:59AM -0700, Dan Williams wrote:
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Cc: Jonathan Corbet
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: Kees Cook
> Acked-by: SeongJae Park
> Signed-off-by: Olof Johansson
> Signed-off-by: Chris Mason
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
> ---
> Changes since v1 [1]
> - Drop inclusive-terminology.rst, it is in the lore archives if the
> arguments are needed for future debates, but otherwise no pressing
> need to carry it in the tree (Linus, James)
>
> - Update the recommended terms to include replacement for 'master' and
> 'whitelist' (Kees, Andy)
>
> - Add 'target' as a replacement (Andy)
>
> - Add 'device' as a replacement (Mark)
>
> - Collect acks and signed-off-bys. Yes, the sign-offs are not reflective
> of a submission chain, but I kept "Signed-off-by" if people offered
> it.
In that case, I will "upgrade" my Ack. ;)
Signed-off-by: Kees Cook
:)
> - Non-change: I did not add explicit language as to what to do with
> existing usages. My personal inclination is to prioritize this
> coding-style cleanup higher than others, but the coding-style document
> has typically not indicated policy on how cleanups are handled by
> subsystems. It will be a case by case effort and consideration.
While I'd like to have published guidance on fixing existing language
(which is already underway[1]), I agree: let's start here.
> [...]
> +For symbol names, avoid introducing new usage of 'master/slave' (or
For symbol names, comments, documentation, and other language, avoid
introducing ...
> +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> +'primary/replica', '{initiator,requester}/{target,responder}',
the main and primary should be merged, IMO:
'{primary,main}/{secondary,replica,subordinate}'
> +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
leader/performer does not track for me. Split it out?
'leader/follower', 'director/performer'
I have also seen:
'controller/worker'
Thanks!
-Kees
[1] https://lore.kernel.org/lkml/20200630174123.ga1906...@kroah.com/
https://lore.kernel.org/lkml/20200701171555.3198836-1-gre...@linuxfoundation.org/
--
Kees Cook
Re: [PATCH v2] CodingStyle: Inclusive Terminology
On Wed, Jul 8, 2020 at 12:40 AM Dan Williams wrote:
>
> Linux maintains a coding-style and its own idiomatic set of terminology.
> Update the style guidelines to recommend replacements for the terms
> master/slave and blacklist/whitelist.
>
> Link:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
> Cc: Jonathan Corbet
> Acked-by: Randy Dunlap
> Acked-by: Dave Airlie
> Acked-by: Kees Cook
> Acked-by: SeongJae Park
> Signed-off-by: Olof Johansson
> Signed-off-by: Chris Mason
Copy - paste error of Chris's address, should be .com of course.
> Signed-off-by: Greg Kroah-Hartman
> Signed-off-by: Dan Williams
> ---
> Changes since v1 [1]
> - Drop inclusive-terminology.rst, it is in the lore archives if the
> arguments are needed for future debates, but otherwise no pressing
> need to carry it in the tree (Linus, James)
>
> - Update the recommended terms to include replacement for 'master' and
> 'whitelist' (Kees, Andy)
>
> - Add 'target' as a replacement (Andy)
>
> - Add 'device' as a replacement (Mark)
>
> - Collect acks and signed-off-bys. Yes, the sign-offs are not reflective
> of a submission chain, but I kept "Signed-off-by" if people offered
> it.
>
> - Non-change: I did not add explicit language as to what to do with
> existing usages. My personal inclination is to prioritize this
> coding-style cleanup higher than others, but the coding-style document
> has typically not indicated policy on how cleanups are handled by
> subsystems. It will be a case by case effort and consideration.
>
> [1]:
> http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
>
> Documentation/process/coding-style.rst | 13 +
> 1 file changed, 13 insertions(+)
>
> diff --git a/Documentation/process/coding-style.rst
> b/Documentation/process/coding-style.rst
> index 2657a55c6f12..a5b61e9005ac 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -319,6 +319,19 @@ 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 'master/slave' (or
> +'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
> +replacements for 'master/slave' are: 'main/{secondary,subordinate}',
> +'primary/replica', '{initiator,requester}/{target,responder}',
> +'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
> +replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or
> +'blocklist/passlist'.
> +
> +Exceptions for introducing new usage is to maintain a userspace ABI/API,
> +or when updating code for an existing (as of 2020) hardware or protocol
> +specification that mandates those terms. For new specifications
> +translate specification usage of the terminology to the kernel coding
> +standard where possible.
>
> 5) Typedefs
> ---
>
[PATCH v2] CodingStyle: Inclusive Terminology
Linux maintains a coding-style and its own idiomatic set of terminology.
Update the style guidelines to recommend replacements for the terms
master/slave and blacklist/whitelist.
Link:
http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
Cc: Jonathan Corbet
Acked-by: Randy Dunlap
Acked-by: Dave Airlie
Acked-by: Kees Cook
Acked-by: SeongJae Park
Signed-off-by: Olof Johansson
Signed-off-by: Chris Mason
Signed-off-by: Greg Kroah-Hartman
Signed-off-by: Dan Williams
---
Changes since v1 [1]
- Drop inclusive-terminology.rst, it is in the lore archives if the
arguments are needed for future debates, but otherwise no pressing
need to carry it in the tree (Linus, James)
- Update the recommended terms to include replacement for 'master' and
'whitelist' (Kees, Andy)
- Add 'target' as a replacement (Andy)
- Add 'device' as a replacement (Mark)
- Collect acks and signed-off-bys. Yes, the sign-offs are not reflective
of a submission chain, but I kept "Signed-off-by" if people offered
it.
- Non-change: I did not add explicit language as to what to do with
existing usages. My personal inclination is to prioritize this
coding-style cleanup higher than others, but the coding-style document
has typically not indicated policy on how cleanups are handled by
subsystems. It will be a case by case effort and consideration.
[1]:
http://lore.kernel.org/r/159389297140.2210796.13590142254668787525.st...@dwillia2-desk3.amr.corp.intel.com
Documentation/process/coding-style.rst | 13 +
1 file changed, 13 insertions(+)
diff --git a/Documentation/process/coding-style.rst
b/Documentation/process/coding-style.rst
index 2657a55c6f12..a5b61e9005ac 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -319,6 +319,19 @@ 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 'master/slave' (or
+'slave' independent of 'master') and 'blacklist/whitelist'. Recommended
+replacements for 'master/slave' are: 'main/{secondary,subordinate}',
+'primary/replica', '{initiator,requester}/{target,responder}',
+'host/{device,proxy}', or 'leader/{performer,follower}'. Recommended
+replacements for 'blacklist/whitelist' are: 'denylist/allowlist' or
+'blocklist/passlist'.
+
+Exceptions for introducing new usage is to maintain a userspace ABI/API,
+or when updating code for an existing (as of 2020) hardware or protocol
+specification that mandates those terms. For new specifications
+translate specification usage of the terminology to the kernel coding
+standard where possible.
5) Typedefs
---
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 11:56 PM SeongJae Park wrote: > > Hello, > > On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams > 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. > > I'm glad to see this patch. > > > > > Cc: Jonathan Corbet > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > Acked-by: SeongJae Park > > > --- > > 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'. > > I have submitted a couple of patches for automated encouragement of the the > inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, the > version says only "please consider using 'denylist' and 'allowlist' instead of > 'blacklist' and 'whitelist'" for now. I think we could add more terms in > there > based on this discussion. I could do that after this patch is merged, or you > could do that yourself in the next spin of this patch. Please do whatever you > feel comfort. > > [1] > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 > [2] > https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed > Thank you for stepping up to take this on, much appreciated. I think I'll leave it to you to fixup checkpatch after the final version of this patch is merged. It may be as simple as "See section 4 'Naming' in coding-style for suggested replacements".
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 02:03:36 +0300 Pavel Begunkov wrote: > On 07/07/2020 01:28, Steven Rostedt wrote: > > On Tue, 7 Jul 2020 01:17:47 +0300 > > Pavel Begunkov wrote: > > > >> Totally agree with you! But do we care then whether two _devices_ or > >> _objects_ > >> are slave-master? Can't see how it fundamentally differs. > > > > The term slave carries a lot more meaning than subordinate. I replied to > > someone else but later realized that the person sent me their reply > > offlist, so my reply to them was also offlist. What I told them was, > > back in college (decades ago), when I first mentioned "master/slave" in > > conversation (I think it was about hard drives), a person in that > > conversation stated that those were not very nice terms to use. I blew > > it off back then, but after listening to more people, I found that > > using "slave" even to describe a device is not something that people > > care to hear about. > > That's cultural, but honestly I've never seen such a person. I still > don't understand, why having secondary or subordinate object belittling > the owned side by not providing it the same rights and freedom is OK, > but slave/master objects are not. Where is the line? > > > > > > And in actuality, does one device actually enslave another device? I > > think that terminology is misleading to begin with. > > As mentioned, I do like good clear terminology, and if it conveys the idea > better, etc., then it's worth to try. And IMHO that's the right reasoning > that should be behind. Otherwise, for almost every word we can find a person > seeing something subjectively offensive or at least bad in it. Wherever possible the kernel should use the same terminology as the current standard in that area. Many of the master/slave references in the networking code are for protocols based on IEEE 802 standards (unfortunately paywalled). The current version of those standards do not use this kind of wording and the standards committees are also actively working on inclusive language statemets. As far as the use of master/slave for bonding, bridge, team etc, it looks like Linux just invented using those terms since I don't see it any other vendors implementations Cisco/Juniper/Arista/... Linux terms are different than industry norms in networking, this is not a good thing. But changing human expectations is hard.
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
> Blacklist most definitely has a negative connotation in technical use. > You blacklist devices that don't work properly, you blacklist drivers > that don't work for your hardware, you blacklist domains that are > sending spam or trying to mount network attacks on your servers. Things > on the blacklist are "bad" in one way or the other, that's the reason > they're on it. > Of course, we put "bad" things on a blacklist. But in computing, only technical things, not black people. What I meant with "blacklist has no negative connotation" was that when we use the word "blacklist", nobody actually thinks about people or skin color. Blocking bad IP addresses or faulty devices is surely non-offensive. If you argue that instead of this, what we really care about is "black" things generally meaning something "bad", then forbidding "blacklist" will not get us any closer to our goal. This is because we have a hundred other "black" phrases in our language: black economy, black sheep, black market, to blacken, a blackleg, a blackguard, a black mark ... only a couple of examples from the top of my head. My point is we will never get rid of the bad connotations in "black". "Black" is always going to assume and remain something "unwanted", even after 2020. This is why I think this whole campaign of removing "blacklist" is utterly ridiculous and ineffective. The real problem is that a group of people have been marked and labeled with such a negative word. If we want to remove the negative association from black people, we should stop calling them black. That'd be productive in the long run, since afro-americans then wouldn't be associated with something "bad" anymore. But all the supporters of the campaign keep calling them something ba" by calling them black, and hope to make a difference by banning 2 or 3 totally unrelated phrases out of probably 50. The whole campaign is pointless and rides on emotion and media attention instead of rational thinking. I support avoiding references to master, slave, and to slavery in general. I oppose avoiding blacklist. Raschko T.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 01:54:23AM -0700, Kees Cook wrote: > On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > > Kees Cook wrote: > > > I have struggled with this as well. The parts of speech change, and my > > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > > weird. > > > > > And just using "allowed" and "denied" doesn't impart whether it refers > > > to a _single_ instance or a _list_ of instances. > > > > > But that's all fine. The change is easy to do and is more descriptive > > > even if I can't find terms that don't collide with my internal grammar > > > checker. ;) > > > > But why. In English many times a verb when it comes before the noun means > > an adjective, or an adjective like, describing some traits of the noun. > > This is kind of my problem being a native English speaker: I can't > entirely describe _why_ a grammar construct feels wrong. :( > > > Example: > > I work - work is a verb here. > > I used the work bench. - Work is saying something about the type of bench, > > an adjective. Same as you would say "I used the green bench". > > Right, so the verb-noun being used as a noun is find, just as adj-noun > is. To me, "add it to the allow-list" is entirely sensible just like > "set it on the work-bench." It's the "verbing" of a noun that trips me > up. > > "I will whitelist the syscall" -- sounds correct to me (same for > "it is whitelisted" or "it is in whitelisting mode"). > > "I will allow-list the syscall" -- sounds wrong to me (same for > "it is allow-listed" or "it is in allow-listing mode"). I suspect it's at least partly because "allow" and "list" are both verbs -- in fact, "list" is the actual verb in "I will allow-list it", and "allow" is being used to modify the verb "list". But because "allow" is usually a verb, the sentence sounds like there are two verbs in there when there should only be one. I expect our ears will get trained to accept that sentence once you encounter "allowlist" often enough.
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 02:48:25AM +0200, Tibor Raschko wrote: > > More generally etymological arguments are just not super relevant here > > anyway, the issues people have are around current perceptions rather > > than where things came from. > > This is where ignoring etymology in this case falls apart, claiming that the > current meaning is more important than the historical one. Yes it should be > more > important, but it suggests that the current meaning is negative, which it is > not. In computer science (context!) these words do not have any negative > perception or connotation, and people in this field know this. Yes, outsiders > might not know this and could misunderstand them. But since when do experts in > computer science (or in any field of science for the matter) care if a layman > can correctly understand the field's technical terms? We never did and never > will, except in this particular case for some odd reason. > > Be honest: "blacklist" is a technical term where the actual meaning has no > negative connotation despite what people outside the field might think. But > apparently we don't care about the actual meaning. We also don't care about > the > historical meaning or etymology. We only care about... well if not about the > meaning in the past or present, then I don't know what. Looking good in the > media? Blacklist most definitely has a negative connotation in technical use. You blacklist devices that don't work properly, you blacklist drivers that don't work for your hardware, you blacklist domains that are sending spam or trying to mount network attacks on your servers. Things on the blacklist are "bad" in one way or the other, that's the reason they're on it.
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 05:45:42PM +0300, Mike Rapoport wrote:
> On Tue, Jul 07, 2020 at 09:41:47AM -0400, Steven Rostedt wrote:
> > On Tue, 7 Jul 2020 01:54:23 -0700
> > Kees Cook wrote:
> >
> > > "I will whitelist the syscall" -- sounds correct to me (same for
> > > "it is whitelisted" or "it is in whitelisting mode").
> > >
> > > "I will allow-list the syscall" -- sounds wrong to me (same for
> > > "it is allow-listed" or "it is in allow-listing mode").
> >
> > That's because we can't just make "allow-list" a drop in replacement
> > for "whitelist" as I too (native English speaker) find it awkward. But
> > then we don't need to make it a drop in replacement.
> >
> > "I will whitelist the syscall" will become "I will add the syscall to
> > the allow-list", which sounds perfectly fine, and even better than
> > saying "I will add the syscall to the whitelist".
>
> I will allow the syscall?
Kind of, but it's this change to verb-noun from adj-noun that confuses the
resulting language: the verb form of the verb-noun doesn't distinguish
between its stand-alone action ("allowed") or its combined action
("allow-list-ed") in the same way that the verb form of the adj-noun does
(the verbed adj-noun is its own word). To me to looks like "allowed" and
"whitelisted" mean distinct things (as in, a single allowance vs being
added to the persistent list of allowances).
So "I will allow this system call once" and "I will allow all instances
of this syscall", or we just get used to using the verb-noun as a whole,
and embrace "I allowlisted the syscall."
But yes, as I and others come back to: it's fine. We'll just use different
surrounding constructs to avoid confusion. But it is an odd characteristic
of English's grammar (or lack of appropriately descriptive adjectives) to
not have a drop-in replacement. (Which is where I think the master/slave
replacements fair far better -- the whitelist replacement is more complex,
but it's mostly just English glitchiness.)
--
Kees Cook
RE: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
> -Original Message- > From: Steven Rostedt > > On Tue, 7 Jul 2020 09:49:21 +0300 > Mike Rapoport wrote: > > > > But that's all fine. The change is easy to do and is more descriptive > > > even if I can't find terms that don't collide with my internal grammar > > > checker. ;) > > > > How about yeslist and nolist? ;-) > > I was thinking good-list / bad-list. > > /me that has been doing a lot of git bisect lately... I think it depends on the context. I'd prefer a grammatically awkward verb that described the action more specifically, than a grammatically nicer generic term. In other words, yes/no, good/bad don't mean that much to me, unless it's obvious from context what the effect will be. With something like allow/deny, I have a pretty clear mental model of what the code is going to do. -- Tim
RE: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
> -Original Message-
> From: Steven Rostedt
>
> On Tue, 7 Jul 2020 08:33:33 -0700
> Randy Dunlap wrote:
>
> > >> I was thinking good-list / bad-list.
> > >>
> > >> /me that has been doing a lot of git bisect lately...
> > >
> > > I think it depends on the context. I'd prefer a grammatically awkward
> > > verb that described
> > > the action more specifically, than a grammatically nicer generic term.
> > > In other words,
> > > yes/no, good/bad don't mean that much to me, unless it's obvious from
> > > context
> > > what the effect will be. With something like allow/deny, I have a pretty
> > > clear mental
> > > model of what the code is going to do.
> >
> > That matches what I was about to say:
> > Just using yes/no does not tell someone what they are saying yes or no
> > about.
> > It should be more descriptive, like allow/block.
>
> After doing two days worth of git bisect, good/bad is hardcoded in my head :-p
Maybe I have the same bias, because good/bad there doesn't bother me at all. ;-)
Here is some 'motivated reasoning' on my part...
In the git case, the good/bad terms describe the result status of the test, not
the action that git
is going to take based on that status. It's pretty clear from context that a
'good'
result will cause that commit and other commits to be added to the 'good' set.
I think what
git actually does in constructing the sets is a bit too magical to describe
with a simple
verb.
As an aside I just looked up 'git-bisect' documentation, and found it has
support
for changing the terms used ('git bisect terms ..') so you can use words like
'fast/slow'
or 'fixed/broken'. That's something I didn't know about. :-)
-- Tim
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 08:33:33 -0700 Randy Dunlap wrote: > >> I was thinking good-list / bad-list. > >> > >> /me that has been doing a lot of git bisect lately... > > > > I think it depends on the context. I'd prefer a grammatically awkward verb > > that described > > the action more specifically, than a grammatically nicer generic term. In > > other words, > > yes/no, good/bad don't mean that much to me, unless it's obvious from > > context > > what the effect will be. With something like allow/deny, I have a pretty > > clear mental > > model of what the code is going to do. > > That matches what I was about to say: > Just using yes/no does not tell someone what they are saying yes or no about. > It should be more descriptive, like allow/block. After doing two days worth of git bisect, good/bad is hardcoded in my head :-p -- Steve
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 7/7/20 8:24 AM, Bird, Tim wrote: > > >> -Original Message- >> From: Steven Rostedt >> >> On Tue, 7 Jul 2020 09:49:21 +0300 >> Mike Rapoport wrote: >> But that's all fine. The change is easy to do and is more descriptive even if I can't find terms that don't collide with my internal grammar checker. ;) >>> >>> How about yeslist and nolist? ;-) >> >> I was thinking good-list / bad-list. >> >> /me that has been doing a lot of git bisect lately... > > I think it depends on the context. I'd prefer a grammatically awkward verb > that described > the action more specifically, than a grammatically nicer generic term. In > other words, > yes/no, good/bad don't mean that much to me, unless it's obvious from context > what the effect will be. With something like allow/deny, I have a pretty > clear mental > model of what the code is going to do. That matches what I was about to say: Just using yes/no does not tell someone what they are saying yes or no about. It should be more descriptive, like allow/block. -- ~Randy
Re: [Ksummit-discuss] [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 09:41:47AM -0400, Steven Rostedt wrote: > On Tue, 7 Jul 2020 01:54:23 -0700 > Kees Cook wrote: > > > "I will whitelist the syscall" -- sounds correct to me (same for > > "it is whitelisted" or "it is in whitelisting mode"). > > > > "I will allow-list the syscall" -- sounds wrong to me (same for > > "it is allow-listed" or "it is in allow-listing mode"). > > That's because we can't just make "allow-list" a drop in replacement > for "whitelist" as I too (native English speaker) find it awkward. But > then we don't need to make it a drop in replacement. > > "I will whitelist the syscall" will become "I will add the syscall to > the allow-list", which sounds perfectly fine, and even better than > saying "I will add the syscall to the whitelist". I will allow the syscall? > -- Steve -- Sincerely yours, Mike.
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 01:54:23 -0700 Kees Cook wrote: > "I will whitelist the syscall" -- sounds correct to me (same for > "it is whitelisted" or "it is in whitelisting mode"). > > "I will allow-list the syscall" -- sounds wrong to me (same for > "it is allow-listed" or "it is in allow-listing mode"). That's because we can't just make "allow-list" a drop in replacement for "whitelist" as I too (native English speaker) find it awkward. But then we don't need to make it a drop in replacement. "I will whitelist the syscall" will become "I will add the syscall to the allow-list", which sounds perfectly fine, and even better than saying "I will add the syscall to the whitelist". -- Steve
Re: [Tech-board-discuss] [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 09:49:21 +0300 Mike Rapoport wrote: > > But that's all fine. The change is easy to do and is more descriptive > > even if I can't find terms that don't collide with my internal grammar > > checker. ;) > > How about yeslist and nolist? ;-) I was thinking good-list / bad-list. /me that has been doing a lot of git bisect lately... -- Steve
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > Kees Cook wrote: > > I have struggled with this as well. The parts of speech change, and my > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > weird. > But why. In English many times a verb when it comes before the noun means an > adjective, or an adjective like, describing some traits of the noun. I fear that if you are looking for logic or reason in English grammar you are on a path to disappointment. FWIW I share Kees' "that looks off" instinct with some of the usage of allow/deny. signature.asc Description: PGP signature
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 09:08:57PM -0700, Dan Williams wrote: > On Mon, Jul 6, 2020 at 12:16 PM Mark Brown wrote: > > This, especially the bit about "revelation of 2020", sounds a little > > off to me - I think it's that it's worryingly close to the frequently > > derided pattern where people recognise a problem that other people have > > been talking about for a while and treat it as something new. Perhaps a > > more neutrally worded reference to current events and/or our desire to > > improve instead? > I'd just as soon let this commentary live in the archives if people > need some more background. It's not like we have companion essays on > the other recommendations in coding-style, and we seem to be > converging on just amending coding-style. That's even better from my point of view. signature.asc Description: PGP signature
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, Jul 07, 2020 at 06:56:53AM +, Harrosh, Boaz wrote: > Kees Cook wrote: > > I have struggled with this as well. The parts of speech change, and my > > grammar senses go weird. whitelist = adjective noun. allow-list = verb > > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > > weird. > > > And just using "allowed" and "denied" doesn't impart whether it refers > > to a _single_ instance or a _list_ of instances. > > > But that's all fine. The change is easy to do and is more descriptive > > even if I can't find terms that don't collide with my internal grammar > > checker. ;) > > But why. In English many times a verb when it comes before the noun means an > adjective, or an adjective like, describing some traits of the noun. This is kind of my problem being a native English speaker: I can't entirely describe _why_ a grammar construct feels wrong. :( > Example: > I work - work is a verb here. > I used the work bench. - Work is saying something about the type of bench, an > adjective. Same as you would say "I used the green bench". Right, so the verb-noun being used as a noun is find, just as adj-noun is. To me, "add it to the allow-list" is entirely sensible just like "set it on the work-bench." It's the "verbing" of a noun that trips me up. "I will whitelist the syscall" -- sounds correct to me (same for "it is whitelisted" or "it is in whitelisting mode"). "I will allow-list the syscall" -- sounds wrong to me (same for "it is allow-listed" or "it is in allow-listing mode"). Similarly, "I will work-bench" sounds wrong to me as does "it is work-benched" or "it is in work-benching mode". > I am not an English native at all but allow-list sounds totally English to > me. (I guess the very correct English way is "allowed-list" where the past > tense may convert the verb to a noun. but allow-list sounds very good to me > as well. Say work-list as opposed to vacation-list do you need to say > worked-list? I don't think so.) > > run mate, running mate. cutting board. these are all examples of verbs used > as adjectives. Are they not English? What am I missing I would like to learn? "it is in allowing-list mode" sounds even worse. :) But other things require the tense follow the merged verb: "It's already in the allowed-list" sounds fine, where "It's already in the whitelist" had no tense since it lacked a verb. I haven't been able to find an comfortable adjective that means "allow"; "allowable-list" is just long. But, as mentioned earlier -- I have just switched to more descriptive and less weird (to me) sentences. "It is set to deny by default" (instead of "it's a whitelist") or "It's already in the allowed-list". *shrug* -- Kees Cook
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams 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 > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams > --- This is the right thing to do. Acked-by: Christian Brauner (Imho, I agree with Andy and the historical bits could probably be moved into the changelog.) > 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 > +` for details. > > 5) Typedefs > --- > diff --git a/Documentation/process/inclusive-terminology.rst > b/Documentation/process/inclusive-terminology.rst > new file mode 100644 > index ..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 ` 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 `? 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.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Kees Cook wrote: > I have struggled with this as well. The parts of speech change, and my > grammar senses go weird. whitelist = adjective noun. allow-list = verb > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > weird. > And just using "allowed" and "denied" doesn't impart whether it refers > to a _single_ instance or a _list_ of instances. > But that's all fine. The change is easy to do and is more descriptive > even if I can't find terms that don't collide with my internal grammar > checker. ;) But why. In English many times a verb when it comes before the noun means an adjective, or an adjective like, describing some traits of the noun. Example: I work - work is a verb here. I used the work bench. - Work is saying something about the type of bench, an adjective. Same as you would say "I used the green bench". I am not an English native at all but allow-list sounds totally English to me. (I guess the very correct English way is "allowed-list" where the past tense may convert the verb to a noun. but allow-list sounds very good to me as well. Say work-list as opposed to vacation-list do you need to say worked-list? I don't think so.) run mate, running mate. cutting board. these are all examples of verbs used as adjectives. Are they not English? What am I missing I would like to learn? Thanks Boaz
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
Hello, On Sat, 04 Jul 2020 13:02:51 -0700 Dan Williams 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. I'm glad to see this patch. > > Cc: Jonathan Corbet > Cc: Kees Cook > Signed-off-by: Chris Mason > Signed-off-by: Greg Kroah-Hartman > Signed-off-by: Dan Williams Acked-by: SeongJae Park > --- > 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'. I have submitted a couple of patches for automated encouragement of the the inclusive terms and those merged in the -next tree[1,2] now. Nonetheless, the version says only "please consider using 'denylist' and 'allowlist' instead of 'blacklist' and 'whitelist'" for now. I think we could add more terms in there based on this discussion. I could do that after this patch is merged, or you could do that yourself in the next spin of this patch. Please do whatever you feel comfort. [1] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=7d0bea01dec27195d95d929c1ee49a4a74dd6671 [2] https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/commit/?id=95a94258ceb27052f00b7e51588a128d20bf05ed Thanks, SeongJae Park
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 10:56:17PM -0700, Kees Cook wrote: > On Mon, Jul 06, 2020 at 09:29:46AM -0700, Andy Lutomirski wrote: > > Is most contexts where 'whitelist' or 'blacklist' might be used, a > > descriptive phrase could be used instead. For example, a seccomp > > filter could have a 'list of allowed syscalls' or a 'list of > > disallowed syscalls', and just lists could be the 'allowed' or > > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > > If a single word replacement for 'whitelist' or 'blacklist' is needed, > > 'allowlist', 'blocklist', or 'denylist' could be used. > > Yup. See: > https://lore.kernel.org/lkml/202007041703.51F4059CA@keescook/ > specifically the terminology for seccomp is already "allow-list" and > "deny-list": > https://github.com/mkerrisk/man-pages/commit/462ce23d491904a0b46252dc97c8cb42391c093e > (last year) > https://github.com/seccomp/libseccomp/commit/0e762521d604612bb4dca8867d4a428a5e6cae54 > (last month) > > > Second, I realize that I grew up thinking that 'whitelist' and > > 'blacklist' are the common terms for lists of things to be accepted > > and rejected and that this biases my perception of what sounds good, > > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > > off the tongue. Perhaps this language would be better: > > I have struggled with this as well. The parts of speech change, and my > grammar senses go weird. whitelist = adjective noun. allow-list = verb > noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is > weird. > > And just using "allowed" and "denied" doesn't impart whether it refers > to a _single_ instance or a _list_ of instances. > > But that's all fine. The change is easy to do and is more descriptive > even if I can't find terms that don't collide with my internal grammar > checker. ;) How about yeslist and nolist? ;-) > -- > Kees Cook > ___ > Ksummit-discuss mailing list > ksummit-disc...@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss -- Sincerely yours, Mike.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 06, 2020 at 09:29:46AM -0700, Andy Lutomirski wrote: > Is most contexts where 'whitelist' or 'blacklist' might be used, a > descriptive phrase could be used instead. For example, a seccomp > filter could have a 'list of allowed syscalls' or a 'list of > disallowed syscalls', and just lists could be the 'allowed' or > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > If a single word replacement for 'whitelist' or 'blacklist' is needed, > 'allowlist', 'blocklist', or 'denylist' could be used. Yup. See: https://lore.kernel.org/lkml/202007041703.51F4059CA@keescook/ specifically the terminology for seccomp is already "allow-list" and "deny-list": https://github.com/mkerrisk/man-pages/commit/462ce23d491904a0b46252dc97c8cb42391c093e (last year) https://github.com/seccomp/libseccomp/commit/0e762521d604612bb4dca8867d4a428a5e6cae54 (last month) > Second, I realize that I grew up thinking that 'whitelist' and > 'blacklist' are the common terms for lists of things to be accepted > and rejected and that this biases my perception of what sounds good, > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > off the tongue. Perhaps this language would be better: I have struggled with this as well. The parts of speech change, and my grammar senses go weird. whitelist = adjective noun. allow-list = verb noun. verbing the adj/noun combo feels okay, but verbing a verb/noun is weird. And just using "allowed" and "denied" doesn't impart whether it refers to a _single_ instance or a _list_ of instances. But that's all fine. The change is easy to do and is more descriptive even if I can't find terms that don't collide with my internal grammar checker. ;) -- Kees Cook
Re: [PATCH] CodingStyle: Inclusive Terminology
On Sat, Jul 4, 2020 at 5:41 PM Kees Cook wrote: > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams 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 > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > (nit: isn't this a Co-developed-by chain, not a SoB chain?) > > Acked-by: Kees Cook > > Comments below... > > > --- > > 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'. > > Keeping "master" in a "master/slave" pairing (i.e. replacing only > "slave") seems incomplete to me. If "master" is paired with "slave", it > should be replaced too. Potential examples: 'primary', 'leader', 'principle', > 'controller', 'sender', 'initial'. Yes, this matches Andy's feedback, will add. > Similarly, for "whitelist/blacklist", "whitelist" needs to replaced when > "blacklist" has been. For example, seccomp documentation[1] uses > "allow-list" and "deny-list". > > [1] https://man7.org/linux/man-pages/man2/seccomp.2.html Oh, good to know will make that change. > > +Exceptions for introducing new usage is to maintain a userspace ABI, or > > and API? True, yes, the intent was "don't break userspace" for terminology replacement. > > > +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 > > +` for details. > > Let's add: > > Where possible, old instances of this language should be replaced when > it is not tied to external specifications nor userspace ABI/API. Sounds good to me. > > > > > 5) Typedefs > > --- > > diff --git a/Documentation/process/inclusive-terminology.rst > > b/Documentation/process/inclusive-terminology.rst > > new file mode 100644 > > index ..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 ` recommends > > +avoiding usage of 'slave' and 'blacklist' in new additions to the Linux > > +kernel. > > ... usage of 'master/slave', 'slave', 'whitelist/blacklist', and > 'blacklist' in the Linux kernel. Yes, but as I'm reading this thread backwards I've already agreed to just push the coding-style change in isolation. > > > + > > +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 `? It does so > > +because a common coding style maximizes the efficiency
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:07 AM Mike Rapoport wrote: > > Hi Chris, > > On Mon, Jul 06, 2020 at 12:45:34PM +, Chris Mason via Ksummit-discuss > wrote: > > On 5 Jul 2020, at 0:55, Willy Tarreau wrote: > > > > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > > >> +Non-inclusive terminology has that same distracting effect which is > > >> why > > >> +it is a style issue for Linux, it injures developer efficiency. > > > > > > I'm personally thinking that for a non-native speaker it's already > > > difficult to find the best term to describe something, but having to > > > apply an extra level of filtering on the found words to figure whether > > > they are allowed by the language police is even more difficult. > > > > Since our discussions are public, we’ve always had to deal with > > comments from people outside the community on a range of topics. But > > inside the kernel, it’s just a group of developers trying to help each > > other produce the best quality of code. We’ve got a long history > > together and in general I think we’re pretty good at assuming good > > intent. > > I don't think anybody doubts your intentions. But they say, the road to > hell is paved with good intentions. > > I had a "privilege" to live in the USSR and back there Newspeak was not a > fiction but a reality. > > And despite the good intent, I have a really strong feeling that this > could be a step in a wrong direction... I've experienced some professional training classes for visiting other countries and they tell you helpful things like "avoid making jokes about X" or "Y topic is sensitive". It's not about censoring it's more about how to keep discussion focused on the job at hand. So I'm hoping this is more of the mundane advice of "what's the best way to communicate my point efficiently to the widest possible audience" and not a "step in a wrong direction"... time will tell.
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 12:16 PM Mark Brown wrote: > > On Sat, Jul 04, 2020 at 01:02:51PM -0700, Dan Williams wrote: > > > +'blacklist'. Recommended replacements for 'slave' are: 'secondary', > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > I'd second the suggestion of device as an option here. Sure, will do. I'm assuming you're thinking of cases where 'slave' is used in isolation without a paired relative term? If not, please clarify. > > > +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, > > More generally etymological arguments are just not super relevant here > anyway, the issues people have are around current perceptions rather > than where things came from. > > > +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. > > This, especially the bit about "revelation of 2020", sounds a little > off to me - I think it's that it's worryingly close to the frequently > derided pattern where people recognise a problem that other people have > been talking about for a while and treat it as something new. Perhaps a > more neutrally worded reference to current events and/or our desire to > improve instead? I'd just as soon let this commentary live in the archives if people need some more background. It's not like we have companion essays on the other recommendations in coding-style, and we seem to be converging on just amending coding-style.
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 11:30 AM Shuah Khan wrote: > > On 7/4/20 2:02 PM, Dan Williams 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. > > > > Hi Dan, > > Thanks for taking the time to work on this patch and updating the > coding-style.rst with the with inclusive terminology guidelines and > adding a new document outlining the scope. > > The suggestions you made will help us adapt inclusive terminology > for the current times, and also help us move toward terms that are > intuitive and easier to understand keeping our global developer > community in mind. > > Allowlist/denylist terms are intuitive and action based which have a > globally uniform meaning. > > Terms such as "whitelist" etc are contextual, hence assume contextual > knowledge on the part of the reader. > > A couple comments below: > > > Cc: Jonathan Corbet > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > --- > > 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'. > > allowlist and blocklist or denylist are lot more intuitive than > white/black in any case. Yes, that was interesting to me when I first grappled with this. The replacements are more direct. I was going to go with blocklist/passlist as the common shorthand recommendation, but if a subsystem picks allowlist/denylist as a local custom that's fine too. [..] > Please add my Signed-off-by: Shuah Khan > or Acked-by: Shuah Khan Thanks Shuah.
Re: [Ksummit-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Mon, Jul 6, 2020 at 9:30 AM Andy Lutomirski wrote: > > On Sat, Jul 4, 2020 at 1:19 PM Dan Williams 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 > > Cc: Kees Cook > > Signed-off-by: Chris Mason > > Signed-off-by: Greg Kroah-Hartman > > Signed-off-by: Dan Williams > > --- > > 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' > > Can you put whitelist in the list, too? Yes, will do. I had left it out mistakenly thinking it would help focus the discussion, but the replacements don't make sense without including the replacements for whitelist. > > >. Recommended replacements for 'slave' are: 'secondary', > > +'subordinate', 'replica', 'responder', 'follower', 'proxy', or > > +'performer'. > > Should 'target' be in this list? Yes. > Should there be some mention of "master" to go along with "slave"? > This could be complicated -- as has been noted in this thread, the > word "master" has quite a few meanings, several of which are not > related to slavery or to any form of control, and that the meanings > associated with "master" and its cognates in other languages vary. Yes, I'll at least expand this with the paired terminology for each of the replacements of 'slave'. > > > Recommended replacements for blacklist are: 'blocklist' or > > +'denylist'. > > As someone who has written seccomp code and described the result as a > "whitelist" or "blacklist" in the past, I have a couple of comments. > > First, shouldn't whitelist be in the list? I find it surprising to > put 'blacklist' in the blocklist but to omit whitelist. > > Second, I realize that I grew up thinking that 'whitelist' and > 'blacklist' are the common terms for lists of things to be accepted > and rejected and that this biases my perception of what sounds good, > but writing a seccomp "denylist" or "blocklist" doesn't seem to roll > off the tongue. Perhaps this language would be better: > > Is most contexts where 'whitelist' or 'blacklist' might be used, a > descriptive phrase could be used instead. For example, a seccomp > filter could have a 'list of allowed syscalls' or a 'list of > disallowed syscalls', and just lists could be the 'allowed' or > 'accepted' lists and the 'disallowed', 'rejected', or 'blocked' lists. > If a single word replacement for 'whitelist' or 'blacklist' is needed, > 'allowlist', 'blocklist', or 'denylist' could be used. That makes practical sense to me. Now that I look at this I think the recommendation for the shorthand replacement should only be one style option, lets say "blocklist/passlist" because it's not as amenable to context sensitive replacements as "slave" and benefits from a standard single shorthand. > > > > @@ -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 ` 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. > > Should this type of historical note be in the document or in the changelog?
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
> More generally etymological arguments are just not super relevant here > anyway, the issues people have are around current perceptions rather > than where things came from. This is where ignoring etymology in this case falls apart, claiming that the current meaning is more important than the historical one. Yes it should be more important, but it suggests that the current meaning is negative, which it is not. In computer science (context!) these words do not have any negative perception or connotation, and people in this field know this. Yes, outsiders might not know this and could misunderstand them. But since when do experts in computer science (or in any field of science for the matter) care if a layman can correctly understand the field's technical terms? We never did and never will, except in this particular case for some odd reason. Be honest: "blacklist" is a technical term where the actual meaning has no negative connotation despite what people outside the field might think. But apparently we don't care about the actual meaning. We also don't care about the historical meaning or etymology. We only care about... well if not about the meaning in the past or present, then I don't know what. Looking good in the media?
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
> The suggestions you made will help us adapt inclusive terminology > for the current times, and also help us move toward terms that are > intuitive and easier to understand keeping our global developer > community in mind. > Allowlist/denylist terms are intuitive and action based which have a > globally uniform meaning. Nobody has a problem understanding "blacklist" and "whitelist". These are universally understood words even outside of computing. Claiming that we need clearer alternatives is smoke and mirrors. > Terms such as "whitelist" etc are contextual, hence assume contextual > knowledge on the part of the reader. We are talking about the source code of and interacting with an operating system kernel. Naturally, most things here are contextual and require domain knowledge to be understood correctly. Not requiring contextual knowledge when reading the kernel sources doesn't sound like a realistic argument. Raschko T.
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On 07/07/2020 01:28, Steven Rostedt wrote: > On Tue, 7 Jul 2020 01:17:47 +0300 > Pavel Begunkov wrote: > >> Totally agree with you! But do we care then whether two _devices_ or >> _objects_ >> are slave-master? Can't see how it fundamentally differs. > > The term slave carries a lot more meaning than subordinate. I replied to > someone else but later realized that the person sent me their reply > offlist, so my reply to them was also offlist. What I told them was, > back in college (decades ago), when I first mentioned "master/slave" in > conversation (I think it was about hard drives), a person in that > conversation stated that those were not very nice terms to use. I blew > it off back then, but after listening to more people, I found that > using "slave" even to describe a device is not something that people > care to hear about. That's cultural, but honestly I've never seen such a person. I still don't understand, why having secondary or subordinate object belittling the owned side by not providing it the same rights and freedom is OK, but slave/master objects are not. Where is the line? > > And in actuality, does one device actually enslave another device? I > think that terminology is misleading to begin with. As mentioned, I do like good clear terminology, and if it conveys the idea better, etc., then it's worth to try. And IMHO that's the right reasoning that should be behind. Otherwise, for almost every word we can find a person seeing something subjectively offensive or at least bad in it. -- Pavel Begunkov
Re: [Tech-board-discuss] [PATCH] CodingStyle: Inclusive Terminology
On Tue, 7 Jul 2020 01:17:47 +0300 Pavel Begunkov wrote: > Totally agree with you! But do we care then whether two _devices_ or _objects_ > are slave-master? Can't see how it fundamentally differs. The term slave carries a lot more meaning than subordinate. I replied to someone else but later realized that the person sent me their reply offlist, so my reply to them was also offlist. What I told them was, back in college (decades ago), when I first mentioned "master/slave" in conversation (I think it was about hard drives), a person in that conversation stated that those were not very nice terms to use. I blew it off back then, but after listening to more people, I found that using "slave" even to describe a device is not something that people care to hear about. And in actuality, does one device actually enslave another device? I think that terminology is misleading to begin with. -- Steve
