390x/cpumodel: document S390FeatDef.bit not applicable
PATCH 1/1 390x/cpumodel: document S390FeatDef.bit not applicable
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains unused, iff the feature is of type S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.
Let's document this, and hopefully reduce the potential for confusion.
---
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
--- target/s390x/cpu_features.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
target/s390x/cpu_features.c +9 -2
@@ -23,6 +23,13 @@ .desc = _desc, \ } +/* +* For some feature types (e.g. S390_FEAT_TYPE_MISC) S390FeatDef.bit +* is not applicable, as there is no corresponding feature block. See +* s390_fill_feat_block() and it's usages. +*/ +#define FEAT_BIT_NA -1 +/* indexed by feature number for easy lookup */ static const S390FeatDef s390_features[] = {FEAT_INIT ("esan3" ,S390_FEAT_TYPE_STFL ,0 ,"Instructions marked as n3" ),
@@ -123,8 +130,8 @@ static const S390FeatDef s390_features[] = {FEAT_INIT ("ib" ,S390_FEAT_TYPE_SCLP_CPU ,42 ,"SIE: Intervention bypass facility" ),FEAT_INIT ("cei" ,S390_FEAT_TYPE_SCLP_CPU ,43 ,"SIE: Conditional-external-interception facility" ), -FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,0 ,"DAT-enhancement facility 2" ), -FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,0 ,"Collaborative-memory-management facility" ), +FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"DAT-enhancement facility 2" ), +FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"Collaborative-memory-management facility" ),FEAT_INIT ("plo-cl" ,S390_FEAT_TYPE_PLO ,0 ,"PLO Compare and load (32 bit in general registers)" ), FEAT_INIT("plo-clg", S390_FEAT_TYPE_PLO, 1, "PLO Compare and load (64 bit in parameter list)"),
Signature · 1 line
2.13.5
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 7 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Quoted 8 lines
Signed-off-by Halil Pasic <[email protected]>---
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than FEAT_MISC _not_ using .bit? If not, would it be better to at a comment to the FEAT_MISC definition?
Quoted 34 lines
--- target/s390x/cpu_features.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)target/s390x/cpu_features.c +9
-2@@ -23,6 +23,13 @@ .desc = _desc, \ } +/* +* For some feature types (e.g. S390_FEAT_TYPE_MISC) S390FeatDef.bit +* is not applicable, as there is no corresponding feature block. See +* s390_fill_feat_block() and it's usages. +*/ +#define FEAT_BIT_NA -1 +/* indexed by feature number for easy lookup */ static const S390FeatDef s390_features[] = {FEAT_INIT ("esan3" ,S390_FEAT_TYPE_STFL ,0 ,"Instructions marked as n3" ),@@ -123,8 +130,8 @@ static const S390FeatDef s390_features[] = {FEAT_INIT ("ib" ,S390_FEAT_TYPE_SCLP_CPU ,42 ,"SIE: Intervention bypass facility" ),FEAT_INIT ("cei" ,S390_FEAT_TYPE_SCLP_CPU ,43 ,"SIE: Conditional-external-interception facility" ), -FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,0 ,"DAT-enhancement facility 2" ), -FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,0 ,"Collaborative-memory-management facility" ), +FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"DAT-enhancement facility 2" ), +FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"Collaborative-memory-management facility" ),FEAT_INIT ("plo-cl" ,S390_FEAT_TYPE_PLO ,0 ,"PLO Compare and load (32 bit in general registers)" ), FEAT_INIT("plo-clg", S390_FEAT_TYPE_PLO, 1, "PLO Compare and load (64 bit in parameter list)"),
Quoted 20 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 10 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Quoted 8 lines
Quoted 5 lines
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?
Doubt it right now. I would sign the "overkill" part :)
Signature · 3 lines
Thanks, David / dhildenb
Quoted 23 lines · David Hildenbrand
Quoted 22 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 12 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Hi!
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
Quoted 28 lines · On Tue, 20 Feb 2018 17:04:19 +0100 Christian Borntraeger…
Quoted 27 lines · David Hildenbrand
Quoted 26 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 15 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Quoted 9 lines
Quoted 4 lines
Quoted 2 lines
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
I'd prefer a comment about FEAT_MISC usage rather than a magic value.
Quoted 34 lines · Cornelia Huck
Quoted 31 lines · On Tue, 20 Feb 2018 17:04:19 +0100 Christian Borntraeger…
Quoted 30 lines · David Hildenbrand
Quoted 28 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 7 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Quoted 8 lines
Signed-off-by Halil Pasic <[email protected]>---
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?
Quoted 9 lines
Quoted 6 lines
Quoted 1 line
Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
I'd prefer a comment about
FEAT_MISCusage rather than a magic value.
We can also add FEAT_INIT_MISC. And add a comment in the initializer.
Signature · 3 lines
Thanks, David / dhildenb
Quoted 9 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Will do.
Quoted 11 lines
Quoted 11 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Quoted 9 lines
Quoted 5 lines
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?
I think, that anything not using .bit is likely to get modeled as FEAT_MISC that is why I think a comment to where the FEAT_MISC features are defined is an option. I don't think commenting the definition of S390_FEAT_TYPE_MISC (that is the definition of enum S390FeatType) would help, as what looks weird is the definition of the features (that currently have all the .bit value 0, but that does not matter).
The point is we need to supply 'bit' to FEAT_INIT() because of formal reasons, even if it makes no sense to specify 'bit' for the given feature.
I've done what I've done because it seemed the most idiomatic solution (we used to call such 'special values' extremal elements in school). But I'm fine with commenting the definitions (look for [HERE] below).
Quoted 13 lines
Quoted 13 lines
--- target/s390x/cpu_features.c | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)target/s390x/cpu_features.c +0
-0@@ -23,6 +23,13 @@ .desc = _desc, \ }
Quoted 14 lines
Quoted 11 lines
target/s390x/cpu_features.c +7
-0+/* +* For some feature types (e.g. S390_FEAT_TYPE_MISC) S390FeatDef.bit +* is not applicable, as there is no corresponding feature block. See +* s390_fill_feat_block() and it's usages. +*/ +#define FEAT_BIT_NA -1 +/* indexed by feature number for easy lookup */ static const S390FeatDef s390_features[] = {FEAT_INIT ("esan3" ,S390_FEAT_TYPE_STFL ,0 ,"Instructions marked as n3" ),target/s390x/cpu_features.c static const S390FeatDef s390_features[] = { · line 132
Quoted 3 lines
target/s390x/cpu_features.c +0
-0@@ -123,8 +130,8 @@ static const S390FeatDef s390_features[] = {FEAT_INIT ("ib" ,S390_FEAT_TYPE_SCLP_CPU ,42 ,"SIE: Intervention bypass facility" ), FEAT_INIT("cei", S390_FEAT_TYPE_SCLP_CPU, 43, "SIE: Conditional-external-interception facility"),
[HERE]
Quoted 8 lines
Quoted 7 lines
target/s390x/cpu_features.c +2
-2-FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,0 ,"DAT-enhancement facility 2" ), -FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,0 ,"Collaborative-memory-management facility" ), +FEAT_INIT ("dateh2" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"DAT-enhancement facility 2" ), +FEAT_INIT ("cmm" ,S390_FEAT_TYPE_MISC ,FEAT_BIT_NA ,"Collaborative-memory-management facility" ),FEAT_INIT ("plo-cl" ,S390_FEAT_TYPE_PLO ,0 ,"PLO Compare and load (32 bit in general registers)" ), FEAT_INIT("plo-clg", S390_FEAT_TYPE_PLO, 1, "PLO Compare and load (64 bit in parameter list)"),
Quoted 42 lines · On Tue, 20 Feb 2018 17:08:52 +0100 David Hildenbrand <[email protected]> wrote:
Quoted 41 lines · Cornelia Huck
Quoted 37 lines · On Tue, 20 Feb 2018 17:04:19 +0100 Christian Borntraeger…
Quoted 23 lines · David Hildenbrand
Quoted 22 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 12 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Hi!
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
Quoted 5 lines
Quoted 2 lines
I'd prefer a comment about
FEAT_MISCusage rather than a magic value.We can also add
FEAT_INIT_MISC. And add a comment in the initializer.
That's what I like best.
Quoted 35 lines · David Hildenbrand
Quoted 34 lines · Cornelia Huck
Quoted 31 lines · On Tue, 20 Feb 2018 17:04:19 +0100 Christian Borntraeger…
Quoted 30 lines · David Hildenbrand
Quoted 28 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 7 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Quoted 8 lines
Signed-off-by Halil Pasic <[email protected]>---
Hi!
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?
Quoted 8 lines
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
I'd prefer a comment about
FEAT_MISCusage rather than a magic value.
As I said elsewhere such stuff used to be called 'extremal element' at the university. We used the term 'magic value' for hard coded constants. But the jargon can be different elsewhere.
Quoted 3 lines
Quoted 1 line
We can also add
FEAT_INIT_MISC. And add a comment in the initializer.
I don't care that much about aesthetics. FEAT_INT_MISC would have the benefit of making the definitions shorter. But whatever you decide on.
Quoted 45 lines · Cornelia Huck
Quoted 42 lines · On Tue, 20 Feb 2018 17:08:52 +0100 David Hildenbrand <[email protected]> wrote:
Quoted 41 lines · Cornelia Huck
Quoted 37 lines · On Tue, 20 Feb 2018 17:04:19 +0100 Christian Borntraeger…
Quoted 23 lines · David Hildenbrand
Quoted 22 lines · Cornelia Huck
Quoted 2 lines · On Tue, 20 Feb 2018 16:07:13 +0100 Halil Pasic <[email protected]> wrote:
The 'bit' field of the 'S390FeatDef' structure is not applicable to all it's instances. Currently a this field is not applicable, and remains
s/it's/its/
s/a this/this/
Quoted 12 lines
unused, iff the feature is of type
S390_FEAT_TYPE_MISC. Having the value 0 specified for multiple such feature definition was a little confusing, as it's a perfectly legit bit value, and as usually the value of the bit field is ought to be unique for each feature.Let's document this, and hopefully reduce the potential for confusion.
Signed-off-by Halil Pasic <[email protected]>---
Hi!
Quoted 8 lines
Quoted 6 lines
Quoted 3 lines
This may be an overkill. A comment where the misc features are defined would do to, but I think this is nicer. So I decided to try it with this approach first.
Is there likely to be anything else than
FEAT_MISC_not_ using .bit? If not, would it be better to at a comment to theFEAT_MISCdefinition?Doubt it right now. I would sign the "overkill" part :)
I can cconfirm that this code caused some questions and it took me some minutes to remember why 0 and 0 was ok. So I certainly want to have a comment of some form.
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
I'd prefer a comment about
FEAT_MISCusage rather than a magic value.We can also add
FEAT_INIT_MISC. And add a comment in the initializer.That's what I like best.
OK, seems we have a winner: I will redo this with
#define FEAT_INIT_MISC(_name, _desc) \
FEAT_INIT(_name, S390_FEAT_TYPE_MISC, 0, _desc)Everybody thanks for the comments.
Regards,
Halil