drm: Fix comment doc for format_modifiers
Subsystems (2)
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
@@ -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
Quoted 4 lines · Andrzej Pietrasiewicz
To human readers
"array of struct
drm_formatmodifiers" is almost indistinguishable from "array of structdrm_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
structdrm_format_modifierdoes exist.And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passes an array of structs.Signed-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/gpu/drm/drm_plane.c +0
-0@@ -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
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_formatmodifiers" is almost indistinguishable from "array of structdrm_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
structdrm_format_modifierdoes exist.And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passes an array of structs.Signed-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/gpu/drm/drm_plane.c +0
-0@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *planeLooks 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_formatfoo[]. 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
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_formatmodifiers" is almost indistinguishable from "array of structdrm_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
structdrm_format_modifierdoes exist.And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passes an array of structs.Signed-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/gpu/drm/drm_plane.c +0
-0@@ -160,7 +160,7 @@ static int create_in_format_blob(struct drm_device *dev, struct drm_plane *planeLooks 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_formatfoo[]. 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
Hi Andrzej
Always good to have clear documentation.
Quoted 20 lines · Andrzej Pietrasiewicz
To human readers
"array of struct
drm_formatmodifiers" is almost indistinguishable from "array of structdrm_format_modifiers", especially given that structdrm_format_modifierdoes exist.And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passes an array of structs.Signed-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)drivers/gpu/drm/drm_plane.c +0
-0
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
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
@@ -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
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_formatmodifiers" is almost indistinguishable from "array of structdrm_format_modifiers", especially given that structdrm_format_modifierdoes 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_trather than an array of structs, but the first words of the comment suggest that it passesSigned-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)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 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
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_formatmodifiers" is almost indistinguishable from "array of structdrm_format_modifiers", especially given that structdrm_format_modifierdoes 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
Reviewed-by Ville Syrjälä <[email protected]>Quoted 29 lines
And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passesSigned-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)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 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
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_formatmodifiers" is almost indistinguishable from "array of structdrm_format_modifiers", especially given that structdrm_format_modifierdoes 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
Reviewed-by Ville Syrjälä <[email protected]>Quoted 29 lines
And indeed the parameter passes an array of
uint64_trather than an array of structs, but the first words of the comment suggest that it passesSigned-off-by Andrzej Pietrasiewicz <[email protected]>--- drivers/gpu/drm/drm_plane.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)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 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
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
@@ -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