Skip to contentSkip to conversation

drm/i915: add register macro definition style guide

PATCH In review Jani Nikula 3 participants 10 messages Aug 10, 2017

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

v2 cover drm/i915: add register macro definition style guide

This is v2 of [1], with minor tweaks and bolting the document into the Sphinx build.

BR,
Jani.

[1] http://patchwork.freedesktop.org/patch/msgid/[email protected]

Jani Nikula (3):
Documentation/i915: remove sphinx conversion artefact drm/i915: enum i915_power_well_id is not proper kernel-doc drm/i915: add register macro definition style guide

 Documentation/gpu/i915.rst      | 14 ++++++-
 drivers/gpu/drm/i915/i915_reg.h | 93 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 105 insertions(+), 2 deletions(-)
Signature · 6 lines
2.11.0

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#1 lore raw

PATCH v2 1/3 Documentation/i915: remove sphinx conversion artefact

Remove old warning about docproc directive that's not supported in the Sphinx toolchain.

---
 Documentation/gpu/i915.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/gpu/i915.rst +0 -2
index 46875c2bcc31..32c32b89e2e5 100644
@@ -480,5 +480,3 @@ specific details than found in the more high-level sections.
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
-
-.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c
Signature · 6 lines
2.11.0

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#5 lore raw

PATCH v2 2/3 drm/i915: enum i915_power_well_id is not proper kernel-doc

In reply to Jani Nikula

Revert to a normal comment, as the enum isn't properly documented anyway.

---
 drivers/gpu/drm/i915/i915_reg.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/i915/i915_reg.h +1 -1
index 56df86ef5a4d..3b42ba9fa473 100644
@@ -1127,7 +1127,7 @@ static inline bool i915_mmio_reg_valid(i915_reg_t reg)
 #define   DP_SSS_RESET(pipe)			_DP_SSS(0x2, (pipe))
 #define   DP_SSS_PWR_GATE(pipe)			_DP_SSS(0x3, (pipe))
 
-/**
+/*
  * i915_power_well_id:
  *
  * Platform specific IDs used to look up power wells and - except for custom
Signature · 6 lines
2.11.0

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#7 lore raw

PATCH v2 3/3 drm/i915: add register macro definition style guide

In reply to Jani Nikula

This is not to try to force a new style; this is my interpretation of what the most common existing style is.

With hopes I don't need to answer so many questions about style going forward.

Start a new style section in the i915 document to bolt the register style guide into.

v2: vertical alignment, incorporate to kernel-doc, and more

---
 Documentation/gpu/i915.rst      | 14 +++++++
 drivers/gpu/drm/i915/i915_reg.h | 91 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
Documentation/gpu/i915.rst +14 -0
index 32c32b89e2e5..2e7ee0313c1c 100644
@@ -480,3 +480,17 @@ specific details than found in the more high-level sections.
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
+
+Style
+=====
+
+The drm/i915 driver codebase has some style rules in addition to (and, in some
+cases, deviating from) the kernel coding style.
+
+Register macro definition style
+-------------------------------
+
+The style guide for ``i915_reg.h``.
+
+.. kernel-doc:: drivers/gpu/drm/i915/i915_reg.h
+   :doc: The i915 register macro definition style guide
drivers/gpu/drm/i915/i915_reg.h +91 -0

97 lines not on this page · raw message

Signature · 6 lines
2.11.0

_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#8 lore raw

✗ Fi.CI.BAT: failure for drm/i915: add register macro definition style guide (rev2)

In reply to Jani Nikula
== Series Details ==

== Series Details ==

Series: drm/i915: add register macro definition style guide (rev2)
URL : https://patchwork.freedesktop.org/series/28370/
State : failure

== Summary ==

Series 28370v2 drm/i915: add register macro definition style guide
https://patchwork.freedesktop.org/api/1.0/series/28370/revisions/2/mbox/

Test gem_exec_nop:

        Subgroup basic-parallel:
                pass       -> INCOMPLETE (fi-byt-j1900)
Test kms_cursor_legacy:
        Subgroup basic-busy-flip-before-cursor-atomic:
                fail       -> PASS       (fi-snb-2600) fdo#100215

fdo#100215 https://bugs.freedesktop.org/show_bug.cgi?id=100215

fi-bdw-5557u     total:279  pass:268  dwarn:0   dfail:0   fail:0   skip:11  time:438s
fi-bdw-gvtdvm    total:279  pass:265  dwarn:0   dfail:0   fail:0   skip:14  time:419s
fi-blb-e6850     total:279  pass:224  dwarn:1   dfail:0   fail:0   skip:54  time:363s
fi-bsw-n3050     total:279  pass:243  dwarn:0   dfail:0   fail:0   skip:36  time:501s
fi-bxt-j4205     total:279  pass:260  dwarn:0   dfail:0   fail:0   skip:19  time:485s
fi-byt-j1900     total:67   pass:57   dwarn:0   dfail:0   fail:0   skip:9  
fi-byt-n2820     total:279  pass:251  dwarn:0   dfail:0   fail:0   skip:28  time:514s
fi-glk-2a        total:279  pass:260  dwarn:0   dfail:0   fail:0   skip:19  time:578s
fi-hsw-4770      total:279  pass:263  dwarn:0   dfail:0   fail:0   skip:16  time:432s
fi-hsw-4770r     total:279  pass:263  dwarn:0   dfail:0   fail:0   skip:16  time:410s
fi-ilk-650       total:279  pass:229  dwarn:0   dfail:0   fail:0   skip:50  time:416s
fi-ivb-3520m     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:516s
fi-ivb-3770      total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:480s
fi-kbl-7500u     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:459s
fi-kbl-7560u     total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:564s
fi-kbl-r         total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:577s
fi-pnv-d510      total:279  pass:223  dwarn:1   dfail:0   fail:0   skip:55  time:522s
fi-skl-6260u     total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:447s
fi-skl-6700k     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:645s
fi-skl-6770hq    total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:466s
fi-skl-gvtdvm    total:279  pass:266  dwarn:0   dfail:0   fail:0   skip:13  time:424s
fi-skl-x1585l    total:279  pass:268  dwarn:0   dfail:0   fail:0   skip:11  time:465s
fi-snb-2520m     total:279  pass:251  dwarn:0   dfail:0   fail:0   skip:28  time:551s
fi-snb-2600      total:279  pass:250  dwarn:0   dfail:0   fail:0   skip:29  time:411s

0f3edcc5d40749f2ddddd26f5ada55a145e20350 drm-tip: 2017y-08m-10d-11h-21m-35s UTC integration manifest 22c6121825a3 drm/i915: add register macro definition style guide
fcb595e35f95 drm/i915: enum i915_power_well_id is not proper kernel-doc
351d78b35d17 Documentation/i915: remove sphinx conversion artefact

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_5366/
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx

Reviewed-by on v2 2/3
#6 lore raw

Re: [PATCH v2 2/3] drm/i915: enum i915_power_well_id is not proper kernel-doc

In reply to Jani Nikula
Quoted 13 lines · Jani Nikula

Revert to a normal comment, as the enum isn't properly documented anyway.

---
 drivers/gpu/drm/i915/i915_reg.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
drivers/gpu/drm/i915/i915_reg.h +0 -0
index 56df86ef5a4d..3b42ba9fa473 100644

drivers/gpu/drm/i915/i915_reg.h static inline bool i915_mmio_reg_valid(i915_reg_t reg) · line 1131

Quoted 6 lines
drivers/gpu/drm/i915/i915_reg.h +1 -1
@@ -1127,7 +1127,7 @@ static inline bool i915_mmio_reg_valid(i915_reg_t reg)
 #define   DP_SSS_RESET(pipe)                   _DP_SSS(0x2, (pipe))
 #define   DP_SSS_PWR_GATE(pipe)                        _DP_SSS(0x3, (pipe))
 
-/**
+/*
  * i915_power_well_id:

this part would definitely deserve a space on the doc, but in the current way it is I agree
that it better to remove.

Quoted 5 lines
drivers/gpu/drm/i915/i915_reg.h +0 -1
  *
  * Platform specific IDs used to look up power wells and - except for custom
--

2.11.0

Signature · 6 lines
Rodrigo Vivi
Blog: http://blog.vivi.eng.br
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#2 lore raw

Re: [PATCH v2 1/3] Documentation/i915: remove sphinx conversion artefact

In reply to Jani Nikula
Quoted 2 lines · Jani Nikula

Remove old warning about docproc directive that's not supported in the Sphinx toolchain.

I got confused... the warning is not supported by sphinx or docproc?

Quoted 19 lines
---
 Documentation/gpu/i915.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/gpu/i915.rst +0 -3
index 46875c2bcc31..32c32b89e2e5 100644
@@ -480,5 +480,3 @@ specific details than found in the more high-level sections.
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
-
-.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c
--

2.11.0

Signature · 6 lines
Rodrigo Vivi
Blog: http://blog.vivi.eng.br
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#3 lore raw

Re: [PATCH v2 1/3] Documentation/i915: remove sphinx conversion artefact

Quoted 5 lines · Rodrigo Vivi
Quoted 2 lines · Jani Nikula

Remove old warning about docproc directive that's not supported in the Sphinx toolchain.

I got confused... the warning is not supported by sphinx or docproc?

There used to be a docproc directive !C to ensure all (documented?) functions in the specified file were used in the docbook build. The docbook -> sphinx conversion retained those as commented out warnings in the rst source. I don't think we'll have similar functionality in sphinx anytime soon. So just nuke it.

BR,
Jani.

Quoted 20 lines
Quoted 20 lines
---
 Documentation/gpu/i915.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/gpu/i915.rst +0 -3
index 46875c2bcc31..32c32b89e2e5 100644
@@ -480,5 +480,3 @@ specific details than found in the more high-level sections.
 
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
-
-.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c
--

2.11.0

Signature · 5 lines
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Reviewed-by
#4 lore raw

Re: [PATCH v2 1/3] Documentation/i915: remove sphinx conversion artefact

Quoted 5 lines · Jani Nikula
Quoted 4 lines · Rodrigo Vivi
Quoted 2 lines · Jani Nikula

Remove old warning about docproc directive that's not supported in the Sphinx toolchain.

Quoted 7 lines
Quoted 1 line

I got confused... the warning is not supported by sphinx or docproc?

There used to be a docproc directive !C to ensure all (documented?) functions in the specified file were used in the docbook build. The docbook -> sphinx conversion retained those as commented out warnings in the rst source. I don't think we'll have similar functionality in sphinx anytime soon. So just nuke it.

Oh I see... makes sense

Quoted 27 lines

BR,
Jani.

Quoted 13 lines
Quoted 13 lines
---
 Documentation/gpu/i915.rst | 2 --
 1 file changed, 2 deletions(-)
Documentation/gpu/i915.rst +0 -0
index 46875c2bcc31..32c32b89e2e5 100644
@@ -480,5 +480,3 @@ specific details than found in the more high-level sections.
 
Quoted 7 lines
Quoted 7 lines
Documentation/gpu/i915.rst +0 -3
 .. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
    :internal:
-
-.. WARNING: DOCPROC directive not supported: !Cdrivers/gpu/drm/i915/i915_irq.c
--

2.11.0

--
Jani Nikula, Intel Open Source Technology Center

Signature · 6 lines
Rodrigo Vivi
Blog: http://blog.vivi.eng.br
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx
#9 lore raw

Re: ✗ Fi.CI.BAT: failure for drm/i915: add register macro definition style guide (rev2)

In reply to Patchwork
Quoted 6 lines · Patchwork

== Series Details ==

Series: drm/i915: add register macro definition style guide (rev2)
URL : https://patchwork.freedesktop.org/series/28370/
State : failure

Quoted 8 lines

== Summary ==

Series 28370v2 drm/i915: add register macro definition style guide
https://patchwork.freedesktop.org/api/1.0/series/28370/revisions/2/mbox/

Test gem_exec_nop:

        Subgroup basic-parallel:
                pass       -> INCOMPLETE (fi-byt-j1900)

Pushed, thanks for the review. I took a leap of faith and decided comment and documentation changes didn't blow up the byt.

BR,
Jani.

Quoted 39 lines

Test kms_cursor_legacy:

        Subgroup basic-busy-flip-before-cursor-atomic:
                fail       -> PASS       (fi-snb-2600) fdo#100215

fdo#100215 https://bugs.freedesktop.org/show_bug.cgi?id=100215

fi-bdw-5557u     total:279  pass:268  dwarn:0   dfail:0   fail:0   skip:11  time:438s
fi-bdw-gvtdvm    total:279  pass:265  dwarn:0   dfail:0   fail:0   skip:14  time:419s
fi-blb-e6850     total:279  pass:224  dwarn:1   dfail:0   fail:0   skip:54  time:363s
fi-bsw-n3050     total:279  pass:243  dwarn:0   dfail:0   fail:0   skip:36  time:501s
fi-bxt-j4205     total:279  pass:260  dwarn:0   dfail:0   fail:0   skip:19  time:485s
fi-byt-j1900     total:67   pass:57   dwarn:0   dfail:0   fail:0   skip:9  
fi-byt-n2820     total:279  pass:251  dwarn:0   dfail:0   fail:0   skip:28  time:514s
fi-glk-2a        total:279  pass:260  dwarn:0   dfail:0   fail:0   skip:19  time:578s
fi-hsw-4770      total:279  pass:263  dwarn:0   dfail:0   fail:0   skip:16  time:432s
fi-hsw-4770r     total:279  pass:263  dwarn:0   dfail:0   fail:0   skip:16  time:410s
fi-ilk-650       total:279  pass:229  dwarn:0   dfail:0   fail:0   skip:50  time:416s
fi-ivb-3520m     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:516s
fi-ivb-3770      total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:480s
fi-kbl-7500u     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:459s
fi-kbl-7560u     total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:564s
fi-kbl-r         total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:577s
fi-pnv-d510      total:279  pass:223  dwarn:1   dfail:0   fail:0   skip:55  time:522s
fi-skl-6260u     total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:447s
fi-skl-6700k     total:279  pass:261  dwarn:0   dfail:0   fail:0   skip:18  time:645s
fi-skl-6770hq    total:279  pass:269  dwarn:0   dfail:0   fail:0   skip:10  time:466s
fi-skl-gvtdvm    total:279  pass:266  dwarn:0   dfail:0   fail:0   skip:13  time:424s
fi-skl-x1585l    total:279  pass:268  dwarn:0   dfail:0   fail:0   skip:11  time:465s
fi-snb-2520m     total:279  pass:251  dwarn:0   dfail:0   fail:0   skip:28  time:551s
fi-snb-2600      total:279  pass:250  dwarn:0   dfail:0   fail:0   skip:29  time:411s

0f3edcc5d40749f2ddddd26f5ada55a145e20350 drm-tip: 2017y-08m-10d-11h-21m-35s UTC integration manifest 22c6121825a3 drm/i915: add register macro definition style guide
fcb595e35f95 drm/i915: enum i915_power_well_id is not proper kernel-doc
351d78b35d17 Documentation/i915: remove sphinx conversion artefact

== Logs ==

For more details see: https://intel-gfx-ci.01.org/tree/drm-tip/Patchwork_5366/

Signature · 5 lines
Jani Nikula, Intel Open Source Technology Center
_______________________________________________
Intel-gfx mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/intel-gfx