diff mbox series

[6/6] Documentation/gpu: Add DC glossary

Message ID 20211125153830.1352994-7-Rodrigo.Siqueira@amd.com (mailing list archive)
State New, archived
Headers show
Series Expand display core documentation | expand

Commit Message

Rodrigo Siqueira Jordao Nov. 25, 2021, 3:38 p.m. UTC 
In the DC driver, we have multiple acronyms that are not obvious most of
the time. This commit introduces a DC glossary in order to make it
easier to navigate through our driver.

Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
---
 Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
 Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257 ++++++++++++++++++++
 2 files changed, 258 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst

Comments

Alex Deucher Nov. 29, 2021, 8:08 p.m. UTC | #1 
On Thu, Nov 25, 2021 at 10:40 AM Rodrigo Siqueira
<Rodrigo.Siqueira@amd.com> wrote:
>
> In the DC driver, we have multiple acronyms that are not obvious most of
> the time. This commit introduces a DC glossary in order to make it
> easier to navigate through our driver.
>
> Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> ---
>  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
>  Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257 ++++++++++++++++++++
>  2 files changed, 258 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
>
> diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> index 2e45e83d9a2a..15405c43786a 100644
> --- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> @@ -26,4 +26,4 @@ table of content:
>     amdgpu-dcn-overview.rst
>     amdgpu-dm.rst
>     amdgpu-dc-debug.rst
> -
> +   dc-glossary.rst
> diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> new file mode 100644
> index 000000000000..48698fc1799f
> --- /dev/null
> +++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> @@ -0,0 +1,257 @@
> +===========
> +DC Glossary
> +===========
> +
> +.. glossary::
> +
> +    ABM
> +      Adaptive Backlight Modulation
> +
> +    APU
> +      Accelerated Processing Unit
> +
> +    ASIC
> +      Application-Specific Integrated Circuit
> +
> +    ASSR
> +      Alternate Scrambler Seed Reset
> +
> +    AZ
> +      Azalia (HD audio DMA engine)
> +
> +    BPC
> +      Bits Per Colour/Component
> +
> +    BPP
> +      Bits Per Pixel
> +
> +    Clocks
> +      * PCLK: Pixel Clock
> +      * SYMCLK: Symbol Clock
> +      * SOCCLK: GPU Engine Clock
> +      * DISPCLK: Display Clock
> +      * DPPCLK: DPP Clock
> +      * DCFCLK: Display Controller Fabric Clock
> +      * REFCLK: Real Time Reference Clock
> +      * PPLL: Pixel PLL
> +      * FCLK: Fabric Clock
> +      * MCLK: Memory Clock
> +      * CPLIB: Content Protection Library

CPLIB is not a clock.  It should be split out as its own item.

> +
> +    CRC
> +      Cyclic Redundancy Check
> +
> +    CRTC
> +      Cathode Ray Tube Controller - commonly called "Controller" - Generates
> +      raw stream of pixels, clocked at pixel clock
> +
> +    CVT
> +      Coordinated Video Timings
> +
> +    DAL
> +      Display Abstraction layer
> +
> +    DC (Software)
> +      Display Core
> +
> +    DC (Hardware)
> +      Display Controller
> +
> +    DCC
> +      Delta Colour Compression
> +
> +    DCE
> +      Display Controller Engine
> +
> +    DCHUB
> +      Display Controller Hub
> +
> +    ARB
> +      Arbiter
> +
> +    VTG
> +      Vertical Timing Generator
> +
> +    DCN
> +      Display Core Next
> +
> +    DCCG
> +      Display Clock Generator block
> +
> +    DDC
> +      Display Data Channel
> +
> +    DFS
> +      Digital Frequency Synthesizer
> +
> +    DIO
> +      Display IO
> +
> +    DPP
> +      Display Pipes and Planes
> +
> +    DSC
> +      Display Stream Compression (Reduce the amount of bits to represent pixel
> +      count while at the same pixel clock)
> +
> +    dGPU
> +      discrete GPU
> +
> +    DMIF
> +      Display Memory Interface
> +
> +    DML
> +      Display Mode Library
> +
> +    DMCU
> +      Display Micro Controller Unit
> +
> +    DMCUB
> +      Display Micro-Controller Unit, version B

Make Micro Controller vs. Micro-Controller consistent for these.

> +
> +    DPCD
> +      DisplayPort Configuration Data
> +
> +    DPM(S)
> +      Display Power Management (Signaling)
> +
> +    DRR
> +      Dynamic Refresh Rate
> +
> +    DWB
> +      Display writeback
> +
> +    ECP
> +      Enhanced Content Protection
> +
> +    FB
> +      Frame Buffer
> +
> +    FBC
> +      Frame Buffer Compression
> +
> +    FEC
> +      Forward Error Correction
> +
> +    FRL
> +      Fixed Rate Link
> +
> +    GCO
> +      Graphical Controller Object
> +
> +    GMC
> +      Graphic Memory Controller
> +
> +    GSL
> +      Global Swap Lock
> +
> +    iGPU
> +      integrated GPU
> +
> +    IH
> +      Interrupt Handler
> +
> +    ISR
> +      Interrupt Service Request
> +
> +    ISV
> +      Independent Software Vendor
> +
> +    KMD
> +      Kernel Mode Driver
> +
> +    LB
> +      Line Buffer
> +
> +    LFC
> +      Low Framerate Compensation
> +
> +    LTTPR
> +      Link Training Tunable Phy Repeater
> +
> +    LUT
> +      Lookup Table
> +
> +    MALL
> +      Memory Access at Last Level
> +
> +    MC
> +      Memory Controller
> +
> +    MPC
> +      Multiple pipes and plane combine
> +
> +    MPO
> +      Multi Plane Overlay
> +
> +    MST
> +      Multi Stream Transport
> +
> +    NBP State
> +      Northbridge Power State
> +
> +    NBIO
> +      North Bridge Input/Output
> +
> +    ODM
> +      Output Data Mapping
> +
> +    OPM
> +      Output Protection Manager
> +
> +    OPP
> +      Output Plane Processor
> +
> +    OPTC
> +      Output Pipe Timing Combiner
> +
> +    OTG
> +      Output Timing Generator
> +
> +    PCON
> +      Power Controller
> +
> +    PGFSM
> +      Power Gate Finite State Machine
> +
> +    PPLib
> +      PowerPlay Library

Maybe say that powerplay is the power management component.

> +
> +    PSR
> +      Panel Self Refresh
> +
> +    SCL
> +      Scaler
> +
> +    SDP
> +      Scalable Data Port
> +
> +    SMU
> +      System Management Unit
> +
> +    SLS
> +      Single Large Surface
> +
> +    SST
> +      Single Stream Transport
> +
> +    TMDS
> +      Transition-Minimized Differential Signaling
> +
> +    TMZ
> +      Trusted Memory Zone
> +
> +    TTU
> +      Time to Underflow
> +
> +    VRR
> +      Variable Refresh Rate
> +
> +    UVD
> +      Unified Video Decoder
> +
> +    VCE
> +      Video Compression Engine
> +
> +    VCN
> +      Video Codec Next
> --
> 2.25.1
>
Yann Dirson Nov. 29, 2021, 8:48 p.m. UTC | #2 
Hi Rodrigo,

That will really be helpful!

I know drawing the line is a difficult problem (and can even make things
harder when searching), but maybe it would make sense to keep generic
acronyms not specific to amdgpu in a separate list.  I bet a number of
them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
LUT), but still have value as not necessarily easy to look up.

Maybe "DC glossary" should just be "Glossary", since quite some entries
help to read adm/amdgpu/ too.  Which brings me to the result of my recent
searches as suggested entries:

 KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
 queue descriptor), EOP (still no clue :)

Maybe some more specific ones just to be spelled out in clear where they
are used ?  KCQ (compute queue?), KGQ (gfx queue?)

More suggestions inlined.

Best regards,
Christian König Nov. 30, 2021, 10:09 a.m. UTC | #3 
Am 29.11.21 um 21:48 schrieb ydirson@free.fr:
> Hi Rodrigo,
>
> That will really be helpful!
>
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
>
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
>
>   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>   queue descriptor), EOP (still no clue :)

End Of Pipe/Pipeline :)

This means that calculations are done, all caches are flushed and all 
memory is coherent again.

Usually related to an interrupt send or fence value written.

Christian.

>
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)
>
> More suggestions inlined.
>
> Best regards,
Alex Deucher Nov. 30, 2021, 2:39 p.m. UTC | #4 
On Mon, Nov 29, 2021 at 3:48 PM <ydirson@free.fr> wrote:
>
> Hi Rodrigo,
>
> That will really be helpful!
>
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
>
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
>
>  KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>  queue descriptor), EOP (still no clue :)
>
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)

Kernel Compute Queue and Kernel Graphics Queue.

Alex

>
> More suggestions inlined.
>
> Best regards,
> --
> Yann
>
> > On Thu, Nov 25, 2021 at 10:40 AM Rodrigo Siqueira
> > <Rodrigo.Siqueira@amd.com> wrote:
> > >
> > > In the DC driver, we have multiple acronyms that are not obvious
> > > most of
> > > the time. This commit introduces a DC glossary in order to make it
> > > easier to navigate through our driver.
> > >
> > > Signed-off-by: Rodrigo Siqueira <Rodrigo.Siqueira@amd.com>
> > > ---
> > >  Documentation/gpu/amdgpu-dc/amdgpu-dc.rst   |   2 +-
> > >  Documentation/gpu/amdgpu-dc/dc-glossary.rst | 257
> > >  ++++++++++++++++++++
> > >  2 files changed, 258 insertions(+), 1 deletion(-)
> > >  create mode 100644 Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > >
> > > diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > index 2e45e83d9a2a..15405c43786a 100644
> > > --- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > +++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
> > > @@ -26,4 +26,4 @@ table of content:
> > >     amdgpu-dcn-overview.rst
> > >     amdgpu-dm.rst
> > >     amdgpu-dc-debug.rst
> > > -
> > > +   dc-glossary.rst
> > > diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > new file mode 100644
> > > index 000000000000..48698fc1799f
> > > --- /dev/null
> > > +++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
> > > @@ -0,0 +1,257 @@
> > > +===========
> > > +DC Glossary
> > > +===========
> > > +
> > > +.. glossary::
> > > +
> > > +    ABM
> > > +      Adaptive Backlight Modulation
> > > +
> > > +    APU
> > > +      Accelerated Processing Unit
> > > +
> > > +    ASIC
> > > +      Application-Specific Integrated Circuit
> > > +
> > > +    ASSR
> > > +      Alternate Scrambler Seed Reset
> > > +
> > > +    AZ
> > > +      Azalia (HD audio DMA engine)
> > > +
> > > +    BPC
> > > +      Bits Per Colour/Component
> > > +
> > > +    BPP
> > > +      Bits Per Pixel
> > > +
> > > +    Clocks
> > > +      * PCLK: Pixel Clock
> > > +      * SYMCLK: Symbol Clock
> > > +      * SOCCLK: GPU Engine Clock
> > > +      * DISPCLK: Display Clock
> > > +      * DPPCLK: DPP Clock
> > > +      * DCFCLK: Display Controller Fabric Clock
> > > +      * REFCLK: Real Time Reference Clock
> > > +      * PPLL: Pixel PLL
> > > +      * FCLK: Fabric Clock
> > > +      * MCLK: Memory Clock
> > > +      * CPLIB: Content Protection Library
> >
> > CPLIB is not a clock.  It should be split out as its own item.
> >
> > > +
> > > +    CRC
> > > +      Cyclic Redundancy Check
> > > +
> > > +    CRTC
> > > +      Cathode Ray Tube Controller - commonly called "Controller" -
> > > Generates
> > > +      raw stream of pixels, clocked at pixel clock
> > > +
> > > +    CVT
> > > +      Coordinated Video Timings
> > > +
> > > +    DAL
> > > +      Display Abstraction layer
>
> I recall this as the old name for DC, maybe this should be mentioned ?
>
> > > +
> > > +    DC (Software)
> > > +      Display Core
> > > +
> > > +    DC (Hardware)
> > > +      Display Controller
> > > +
> > > +    DCC
> > > +      Delta Colour Compression
> > > +
> > > +    DCE
> > > +      Display Controller Engine
> > > +
> > > +    DCHUB
> > > +      Display Controller Hub
> > > +
> > > +    ARB
> > > +      Arbiter
> > > +
> > > +    VTG
> > > +      Vertical Timing Generator
> > > +
> > > +    DCN
> > > +      Display Core Next
> > > +
> > > +    DCCG
> > > +      Display Clock Generator block
> > > +
> > > +    DDC
> > > +      Display Data Channel
> > > +
> > > +    DFS
> > > +      Digital Frequency Synthesizer
> > > +
> > > +    DIO
> > > +      Display IO
> > > +
> > > +    DPP
> > > +      Display Pipes and Planes
> > > +
> > > +    DSC
> > > +      Display Stream Compression (Reduce the amount of bits to
> > > represent pixel
> > > +      count while at the same pixel clock)
> > > +
> > > +    dGPU
> > > +      discrete GPU
> > > +
> > > +    DMIF
> > > +      Display Memory Interface
> > > +
> > > +    DML
> > > +      Display Mode Library
> > > +
> > > +    DMCU
> > > +      Display Micro Controller Unit
> > > +
> > > +    DMCUB
> > > +      Display Micro-Controller Unit, version B
> >
> > Make Micro Controller vs. Micro-Controller consistent for these.
> >
> > > +
> > > +    DPCD
> > > +      DisplayPort Configuration Data
> > > +
> > > +    DPM(S)
> > > +      Display Power Management (Signaling)
> > > +
> > > +    DRR
> > > +      Dynamic Refresh Rate
> > > +
> > > +    DWB
> > > +      Display writeback
> > > +
> > > +    ECP
> > > +      Enhanced Content Protection
> > > +
> > > +    FB
> > > +      Frame Buffer
> > > +
> > > +    FBC
> > > +      Frame Buffer Compression
> > > +
> > > +    FEC
> > > +      Forward Error Correction
> > > +
> > > +    FRL
> > > +      Fixed Rate Link
> > > +
> > > +    GCO
> > > +      Graphical Controller Object
> > > +
> > > +    GMC
> > > +      Graphic Memory Controller
> > > +
> > > +    GSL
> > > +      Global Swap Lock
> > > +
> > > +    iGPU
> > > +      integrated GPU
> > > +
> > > +    IH
> > > +      Interrupt Handler
> > > +
> > > +    ISR
> > > +      Interrupt Service Request
> > > +
> > > +    ISV
> > > +      Independent Software Vendor
> > > +
> > > +    KMD
> > > +      Kernel Mode Driver
> > > +
> > > +    LB
> > > +      Line Buffer
> > > +
> > > +    LFC
> > > +      Low Framerate Compensation
> > > +
> > > +    LTTPR
> > > +      Link Training Tunable Phy Repeater
> > > +
> > > +    LUT
> > > +      Lookup Table
> > > +
> > > +    MALL
> > > +      Memory Access at Last Level
> > > +
> > > +    MC
> > > +      Memory Controller
> > > +
> > > +    MPC
> > > +      Multiple pipes and plane combine
> > > +
> > > +    MPO
> > > +      Multi Plane Overlay
> > > +
> > > +    MST
> > > +      Multi Stream Transport
> > > +
> > > +    NBP State
> > > +      Northbridge Power State
> > > +
> > > +    NBIO
> > > +      North Bridge Input/Output
> > > +
> > > +    ODM
> > > +      Output Data Mapping
> > > +
> > > +    OPM
> > > +      Output Protection Manager
> > > +
> > > +    OPP
> > > +      Output Plane Processor
> > > +
> > > +    OPTC
> > > +      Output Pipe Timing Combiner
> > > +
> > > +    OTG
> > > +      Output Timing Generator
> > > +
> > > +    PCON
> > > +      Power Controller
> > > +
> > > +    PGFSM
> > > +      Power Gate Finite State Machine
> > > +
> > > +    PPLib
> > > +      PowerPlay Library
> >
> > Maybe say that powerplay is the power management component.
> >
> > > +
> > > +    PSR
> > > +      Panel Self Refresh
> > > +
> > > +    SCL
> > > +      Scaler
> > > +
> > > +    SDP
> > > +      Scalable Data Port
> > > +
> > > +    SMU
> > > +      System Management Unit
> > > +
> > > +    SLS
> > > +      Single Large Surface
> > > +
> > > +    SST
> > > +      Single Stream Transport
> > > +
> > > +    TMDS
> > > +      Transition-Minimized Differential Signaling
> > > +
> > > +    TMZ
> > > +      Trusted Memory Zone
> > > +
> > > +    TTU
> > > +      Time to Underflow
> > > +
> > > +    VRR
> > > +      Variable Refresh Rate
> > > +
> > > +    UVD
> > > +      Unified Video Decoder
> > > +
> > > +    VCE
> > > +      Video Compression Engine
> > > +
> > > +    VCN
> > > +      Video Codec Next
> > > --
> > > 2.25.1
> > >
> >
Rodrigo Siqueira Jordao Nov. 30, 2021, 3:53 p.m. UTC | #5 
On 2021-11-29 3:48 p.m., ydirson@free.fr wrote:
> Hi Rodrigo,
> 
> That will really be helpful!
> 
> I know drawing the line is a difficult problem (and can even make things
> harder when searching), but maybe it would make sense to keep generic
> acronyms not specific to amdgpu in a separate list.  I bet a number of
> them would be useful in the scope of other drm drivers (e.g. CRTC, DCC,
> MST), and some are not restricted to the drm subsystem at all (e.g. FEC,
> LUT), but still have value as not necessarily easy to look up.
> 
> Maybe "DC glossary" should just be "Glossary", since quite some entries
> help to read adm/amdgpu/ too.  Which brings me to the result of my recent
> searches as suggested entries:
> 
>   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD (hardware
>   queue descriptor), EOP (still no clue :)
> 
> Maybe some more specific ones just to be spelled out in clear where they
> are used ?  KCQ (compute queue?), KGQ (gfx queue?)
> 
> More suggestions inlined.
> 
> Best regards,
> 

Hi all,

I'll address all the highlighted problems in the V2. Thanks a lot for 
all the feedback.

Yann,
For the generic acronyms, how about keeping it in this patch for now? 
After it gets merged, I can prepare a new documentation patch that 
creates a glossary for DRM where I move the generic acronyms to the DRM 
documentation. I prefer this approach to keep the improvement small and 
manageable.

Best Regards
Siqueira
Yann Dirson Nov. 30, 2021, 7:55 p.m. UTC | #6 
----- Mail original -----
> De: "Rodrigo Siqueira Jordao" <rjordrigo@amd.com>
> À: ydirson@free.fr, "Rodrigo Siqueira" <Rodrigo.Siqueira@amd.com>, "Christian König" <christian.koenig@amd.com>,
> "Alex Deucher" <alexander.deucher@amd.com>
> Cc: "Harry Wentland" <Harry.Wentland@amd.com>, "Linux Doc Mailing List" <linux-doc@vger.kernel.org>, "Mark Yacoub"
> <markyacoub@chromium.org>, "Michel Dänzer" <michel@daenzer.net>, "Bas Nieuwenhuizen" <bas@basnieuwenhuizen.nl>,
> "Roman Li" <roman.li@amd.com>, "amd-gfx list" <amd-gfx@lists.freedesktop.org>, "Roman Gilg" <subdiff@gmail.com>,
> "Marek Olšák" <marek.olsak@amd.com>, "Pekka Paalanen" <ppaalanen@gmail.com>, "Aurabindo Pillai"
> <aurabindo.pillai@amd.com>, "nicholas choi" <nicholas.choi@amd.com>, "Maling list - DRI developers"
> <dri-devel@lists.freedesktop.org>, "Simon Ser" <contact@emersion.fr>, "Alex Deucher" <alexdeucher@gmail.com>, "Sean
> Paul" <seanpaul@chromium.org>, "Qingqing Zhuo" <qingqing.zhuo@amd.com>, "Bhawanpreet Lakha"
> <bhawanpreet.lakha@amd.com>, "Nicholas Kazlauskas" <nicholas.kazlauskas@amd.com>
> Envoyé: Mardi 30 Novembre 2021 16:53:55
> Objet: Re: [PATCH 6/6] Documentation/gpu: Add DC glossary
> 
> 
> 
> On 2021-11-29 3:48 p.m., ydirson@free.fr wrote:
> > Hi Rodrigo,
> > 
> > That will really be helpful!
> > 
> > I know drawing the line is a difficult problem (and can even make
> > things
> > harder when searching), but maybe it would make sense to keep
> > generic
> > acronyms not specific to amdgpu in a separate list.  I bet a number
> > of
> > them would be useful in the scope of other drm drivers (e.g. CRTC,
> > DCC,
> > MST), and some are not restricted to the drm subsystem at all (e.g.
> > FEC,
> > LUT), but still have value as not necessarily easy to look up.
> > 
> > Maybe "DC glossary" should just be "Glossary", since quite some
> > entries
> > help to read adm/amdgpu/ too.  Which brings me to the result of my
> > recent
> > searches as suggested entries:
> > 
> >   KIQ (Kernel Interface Queue), MQD (memory queue descriptor), HQD
> >   (hardware
> >   queue descriptor), EOP (still no clue :)
> > 
> > Maybe some more specific ones just to be spelled out in clear where
> > they
> > are used ?  KCQ (compute queue?), KGQ (gfx queue?)
> > 
> > More suggestions inlined.
> > 
> > Best regards,
> > 
> 
> Hi all,
> 
> I'll address all the highlighted problems in the V2. Thanks a lot for
> all the feedback.
> 
> Yann,
> For the generic acronyms, how about keeping it in this patch for now?
> After it gets merged, I can prepare a new documentation patch that
> creates a glossary for DRM where I move the generic acronyms to the
> DRM
> documentation. I prefer this approach to keep the improvement small
> and
> manageable.

Sure, especially as the Right Solution(tm) is not necessarily obvious :)

One thing I thought about is that a context could be specified together
with terms.  Like "BPP (graphics)", "FEC (CS)", "DMCUB (amdgpu)".  Well,
"CS" may not be a good choice but you get the idea: that would keep all
terms together and keep it easy for the reader.

That way it could be easily be generalized at some point by just moving
it to a generic kernel level - provided the solution suits the doc
community at large.

Best regards,
diff mbox series

Patch

diff --git a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
index 2e45e83d9a2a..15405c43786a 100644
--- a/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
+++ b/Documentation/gpu/amdgpu-dc/amdgpu-dc.rst
@@ -26,4 +26,4 @@  table of content:
    amdgpu-dcn-overview.rst
    amdgpu-dm.rst
    amdgpu-dc-debug.rst
-
+   dc-glossary.rst
diff --git a/Documentation/gpu/amdgpu-dc/dc-glossary.rst b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
new file mode 100644
index 000000000000..48698fc1799f
--- /dev/null
+++ b/Documentation/gpu/amdgpu-dc/dc-glossary.rst
@@ -0,0 +1,257 @@ 
+===========
+DC Glossary
+===========
+
+.. glossary::
+
+    ABM
+      Adaptive Backlight Modulation
+
+    APU
+      Accelerated Processing Unit
+
+    ASIC
+      Application-Specific Integrated Circuit
+
+    ASSR
+      Alternate Scrambler Seed Reset
+
+    AZ
+      Azalia (HD audio DMA engine)
+
+    BPC
+      Bits Per Colour/Component
+
+    BPP
+      Bits Per Pixel
+
+    Clocks
+      * PCLK: Pixel Clock
+      * SYMCLK: Symbol Clock
+      * SOCCLK: GPU Engine Clock
+      * DISPCLK: Display Clock
+      * DPPCLK: DPP Clock
+      * DCFCLK: Display Controller Fabric Clock
+      * REFCLK: Real Time Reference Clock
+      * PPLL: Pixel PLL
+      * FCLK: Fabric Clock
+      * MCLK: Memory Clock
+      * CPLIB: Content Protection Library
+
+    CRC
+      Cyclic Redundancy Check
+
+    CRTC
+      Cathode Ray Tube Controller - commonly called "Controller" - Generates
+      raw stream of pixels, clocked at pixel clock
+
+    CVT
+      Coordinated Video Timings
+
+    DAL
+      Display Abstraction layer
+
+    DC (Software)
+      Display Core
+
+    DC (Hardware)
+      Display Controller
+
+    DCC
+      Delta Colour Compression
+
+    DCE
+      Display Controller Engine
+
+    DCHUB
+      Display Controller Hub
+
+    ARB
+      Arbiter
+
+    VTG
+      Vertical Timing Generator
+
+    DCN
+      Display Core Next
+
+    DCCG
+      Display Clock Generator block
+
+    DDC
+      Display Data Channel
+
+    DFS
+      Digital Frequency Synthesizer
+
+    DIO
+      Display IO
+
+    DPP
+      Display Pipes and Planes
+
+    DSC
+      Display Stream Compression (Reduce the amount of bits to represent pixel
+      count while at the same pixel clock)
+
+    dGPU
+      discrete GPU
+
+    DMIF
+      Display Memory Interface
+
+    DML
+      Display Mode Library
+
+    DMCU
+      Display Micro Controller Unit
+
+    DMCUB
+      Display Micro-Controller Unit, version B
+
+    DPCD
+      DisplayPort Configuration Data
+
+    DPM(S)
+      Display Power Management (Signaling)
+
+    DRR
+      Dynamic Refresh Rate
+
+    DWB
+      Display writeback
+
+    ECP
+      Enhanced Content Protection
+
+    FB
+      Frame Buffer
+
+    FBC
+      Frame Buffer Compression
+
+    FEC
+      Forward Error Correction
+
+    FRL
+      Fixed Rate Link
+
+    GCO
+      Graphical Controller Object
+
+    GMC
+      Graphic Memory Controller
+
+    GSL
+      Global Swap Lock
+
+    iGPU
+      integrated GPU
+
+    IH
+      Interrupt Handler
+
+    ISR
+      Interrupt Service Request
+
+    ISV
+      Independent Software Vendor
+
+    KMD
+      Kernel Mode Driver
+
+    LB
+      Line Buffer
+
+    LFC
+      Low Framerate Compensation
+
+    LTTPR
+      Link Training Tunable Phy Repeater
+
+    LUT
+      Lookup Table
+
+    MALL
+      Memory Access at Last Level
+
+    MC
+      Memory Controller
+
+    MPC
+      Multiple pipes and plane combine
+
+    MPO
+      Multi Plane Overlay
+
+    MST
+      Multi Stream Transport
+
+    NBP State
+      Northbridge Power State
+
+    NBIO
+      North Bridge Input/Output
+
+    ODM
+      Output Data Mapping
+
+    OPM
+      Output Protection Manager
+
+    OPP
+      Output Plane Processor
+
+    OPTC
+      Output Pipe Timing Combiner
+
+    OTG
+      Output Timing Generator
+
+    PCON
+      Power Controller
+
+    PGFSM
+      Power Gate Finite State Machine
+
+    PPLib
+      PowerPlay Library
+
+    PSR
+      Panel Self Refresh
+
+    SCL
+      Scaler
+
+    SDP
+      Scalable Data Port
+
+    SMU
+      System Management Unit
+
+    SLS
+      Single Large Surface
+
+    SST
+      Single Stream Transport
+
+    TMDS
+      Transition-Minimized Differential Signaling
+
+    TMZ
+      Trusted Memory Zone
+
+    TTU
+      Time to Underflow
+
+    VRR
+      Variable Refresh Rate
+
+    UVD
+      Unified Video Decoder
+
+    VCE
+      Video Compression Engine
+
+    VCN
+      Video Codec Next