Skip to contentSkip to conversation

drm: Fix comment doc for format_modifiers

PATCH In review Andrzej Pietrasiewicz 4 participants 10 messages Oct 2, 2019 – Oct 8, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 drm: Fix comment doc for format_modifiers

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..df05d8a0dd63 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of modifiers of struct drm_format terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 1 line
2.17.1
#1 lore raw
Quoted 4 lines · Andrzej Pietrasiewicz

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers",

Unless I'm blind those two *are* indistinguishable :P

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Quoted 17 lines

especially given that
struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +0 -0
index d6ad60ab0d38..df05d8a0dd63 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Looks like you have a broken version of git.

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane · line 163

Quoted 5 lines
drivers/gpu/drm/drm_plane.c +1 -1
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of modifiers of struct drm_format terminated by

Now it seems to be saying it's passing in struct drm_format foo[]. That doesn't seem right either.

Quoted 10 lines
drivers/gpu/drm/drm_plane.c +0 -0
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 6 lines
2.17.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Signature · 2 lines
Ville Syrjälä
Intel
#2 lore raw

Hi Ville,

W dniu 02.10.2019 o 18:18, Ville Syrjälä pisze:

Quoted 28 lines · Andrzej Pietrasiewicz
Quoted 4 lines

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers",

Unless I'm blind those two *are* indistinguishable :P

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Quoted 17 lines

especially given that
struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
  drivers/gpu/drm/drm_plane.c | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +0 -0
index d6ad60ab0d38..df05d8a0dd63 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Looks like you have a broken version of git.

Quoted 8 lines

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane · line 163

Quoted 5 lines
drivers/gpu/drm/drm_plane.c +1 -1
   * @funcs: callbacks for the new plane
   * @formats: array of supported formats (DRM_FORMAT\_\*)
   * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of modifiers of struct drm_format terminated by

Now it seems to be saying it's passing in struct drm_format foo[]. That doesn't seem right either.

Good point!

array of modifiers applied to struct drm_format?

Andrzej
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel

#3 lore raw
Quoted 37 lines · Andrzej Pietrasiewicz

Hi Ville,

W dniu 02.10.2019 o 18:18, Ville Syrjälä pisze:

Quoted 34 lines · Andrzej Pietrasiewicz
Quoted 4 lines

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers",

Unless I'm blind those two *are* indistinguishable :P

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Quoted 17 lines

especially given that
struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
  drivers/gpu/drm/drm_plane.c | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +0 -0
index d6ad60ab0d38..df05d8a0dd63 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane

Looks like you have a broken version of git.

Quoted 5 lines
drivers/gpu/drm/drm_plane.c +1 -1
   * @funcs: callbacks for the new plane
   * @formats: array of supported formats (DRM_FORMAT\_\*)
   * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of modifiers of struct drm_format terminated by
Quoted 6 lines
Quoted 2 lines

Now it seems to be saying it's passing in struct drm_format foo[]. That doesn't seem right either.

Good point!

array of modifiers applied to struct drm_format?

Not sure what this has to do with that struct?

I think I'd just make it "array of modifiers terminated by ..."

Signature · 6 lines
Ville Syrjälä
Intel
_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#4 lore raw
In reply to Andrzej Pietrasiewicz

Hi Andrzej

Always good to have clear documentation.

Quoted 20 lines · Andrzej Pietrasiewicz

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +0 -0
index d6ad60ab0d38..df05d8a0dd63 100644

drivers/gpu/drm/drm_plane.c static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane · line 164

Quoted 6 lines
drivers/gpu/drm/drm_plane.c +1 -1
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of modifiers of struct drm_format terminated by
  *                    DRM_FORMAT_MOD_INVALID

@format_modifiers is an array of DRM_FORMAT_* which are defined as:

#define fourcc_code(a, b, c, d) ((__u32)(a) | ((__u32)(b) << 8) | \
                                 ((__u32)(c) << 16) | ((__u32)(d) << 24))

But the array is a u64[] like this:
static const u64 tegra20_modifiers[] = {
DRM_FORMAT_MOD_LINEAR,
DRM_FORMAT_MOD_NVIDIA_TEGRA_TILED,
DRM_FORMAT_MOD_INVALID
};

So this is not struct drm_format.

Can you try to give it a shot more?

Sam

#5 lore raw

PATCH 1/1 drm: Fix comment doc for format_modifiers

To human readers

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs.

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..0d4f9172c0dd 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of format modifiers terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 6 lines
2.17.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Reviewed-by on v1 1/1
#6 lore raw
Quoted 1 line · Andrzej Pietrasiewicz

To human readers

The commit message is always for human readers, no need to point that out...

Quoted 4 lines

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

..but this paragraph still manages to 100% confuse this particular human.

The actual code changes lgtm, so with the commit message reworded this patch is

Quoted 29 lines

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..0d4f9172c0dd 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of format modifiers terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 6 lines
2.17.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Signature · 2 lines
Ville Syrjälä
Intel
#7 lore raw
Quoted 7 lines · Ville Syrjälä
Quoted 1 line · Andrzej Pietrasiewicz

To human readers

The commit message is always for human readers, no need to point that out...

Quoted 1 line
Quoted 5 lines
Quoted 3 lines

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

..but this paragraph still manages to 100% confuse this particular human.

There's an underscore instead of a space on the second line (s/drm_format modifiers/drm_format_modifiers/).

It should definitely be reworded to be much clearer.

Quoted 35 lines

The actual code changes lgtm, so with the commit message reworded this patch is

Quoted 29 lines

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..0d4f9172c0dd 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of format modifiers terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 6 lines
2.17.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
#8 lore raw
Quoted 8 lines · Eric Engestrom
Quoted 7 lines · Ville Syrjälä
Quoted 1 line · Andrzej Pietrasiewicz

To human readers

The commit message is always for human readers, no need to point that out...

Quoted 1 line
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines

"array of struct drm_format modifiers" is almost indistinguishable from "array of struct drm_format_modifiers", especially given that struct drm_format_modifier does exist.

..but this paragraph still manages to 100% confuse this particular human.

There's an underscore instead of a space on the second line (s/drm_format modifiers/drm_format_modifiers/).

OK, so I guess I really am blind.

Quoted 38 lines

It should definitely be reworded to be much clearer.

Quoted 35 lines

The actual code changes lgtm, so with the commit message reworded this patch is

Quoted 29 lines

And indeed the parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..0d4f9172c0dd 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of format modifiers terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 6 lines
2.17.1

_______________________________________________
dri-devel mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/dri-devel
Signature · 2 lines
Ville Syrjälä
Intel
#9 lore raw

PATCH 1/1 drm: Fix comment doc for format_modifiers

The parameter passes an array of uint64_t rather than an array of structs, but the first words of the comment suggest that it passes an array of structs - if the reader stops reading at the word "struct".

If the commit is read beyond that point the reader will likely confuse "drm_format<SPACE>modifiers" with "drm_format<UNDERSCORE>modifiers" and understand the meaning as "passing an array of elements which are of type struct drm_format_modifier". That is not correct.

Only if the reader is able to read the comment as
"array of struct drm_format<SPACE>modifiers" will they be close to the correct meaning. But still not quite there, because the modifiers do not influence struct drm_format in any way - it is not clear what "a modifier of a struct" would be.

The comment is changed to simply say that the parameter passes an array of format modifiers, which is the correct meaning.

---
 drivers/gpu/drm/drm_plane.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/drm_plane.c +1 -1
index d6ad60ab0d38..0d4f9172c0dd 100644
@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *plane
  * @funcs: callbacks for the new plane
  * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
- * @format_modifiers: array of struct drm_format modifiers terminated by
+ * @format_modifiers: array of format modifiers terminated by
  *                    DRM_FORMAT_MOD_INVALID
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
Signature · 1 line
2.17.1