X driver chapter...

1 files changed, 502 insertions, 29 deletions

diff --git a/linuxgraphicsdrivers.lyx b/linuxgraphicsdrivers.lyx
index d8f3900..9e7189b 100644
--- a/linuxgraphicsdrivers.lyx
+++ b/linuxgraphicsdrivers.lyx
@@ -1,5 +1,5 @@
-#LyX 1.6.4 created this file. For more info see http://www.lyx.org/
-\lyxformat 345
+#LyX 2.0.0beta1 created this file. For more info see http://www.lyx.org/
+\lyxformat 407
 \begin_document
 \begin_header
 \textclass book
@@ -59,18 +59,25 @@
 \begin_modules
 theorems-ams
 \end_modules
+\maintain_unincluded_children false
 \language american
 \inputencoding auto
+\fontencoding global
 \font_roman palatino
 \font_sans default
 \font_typewriter default
 \font_default_family default
+\use_xetex false
 \font_sc false
 \font_osf false
 \font_sf_scale 100
 \font_tt_scale 100
 
 \graphics default
+\default_output_format default
+\output_sync 0
+\bibtex_command default
+\index_command default
 \paperfontsize 10
 \spacing single
 \use_hyperref true
@@ -90,9 +97,18 @@ theorems-ams
 \use_geometry true
 \use_amsmath 1
 \use_esint 1
+\use_mhchem 1
+\use_mathdots 1
 \cite_engine basic
 \use_bibtopic false
+\use_indices false
 \paperorientation portrait
+\suppress_date false
+\use_refstyle 0
+\index Index
+\shortcut idx
+\color #008000
+\end_index
 \leftmargin 2.5cm
 \topmargin 2.5cm
 \rightmargin 1.7cm
@@ -108,8 +124,8 @@ theorems-ams
 \bullet 0 0 17 -1
 \tracking_changes false
 \output_changes false
-\author "" 
-\author "" 
+\html_math_output 0
+\html_be_strict false
 \end_header
 
 \begin_body
@@ -747,7 +763,7 @@ status open
 \lang english
 \begin_inset Tabular
 <lyxtabular version="3" rows="8" columns="5">
-<features>
+<features tabularvalignment="middle">
 <column alignment="center" valignment="top" width="0">
 <column alignment="center" valignment="top" width="0">
 <column alignment="center" valignment="top" width="0">
@@ -3215,6 +3231,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -4442,6 +4459,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -4971,6 +4989,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -5428,6 +5447,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -5481,28 +5501,332 @@ name "cha:X.Org-Drivers"
 \begin_layout Standard
 
 \lang english
-This chapter covers the implementation of a 2D acceleration inside X.Org.
+This chapter covers the implementation of a 2D driver inside X.Org.
+ There are multiple ways to implement a 2D X.Org driver: ShadowFB, XAA, EXA.
+ Another simple way of implementing X.Org support is through the xf86-video-fbdev
+ module.
+ This module implements X.Org on top of an existing, in-kernel framebuffer
+ driver.
+ It can be a 
+\begin_inset Quotes eld
+\end_inset
+
+good enough
+\begin_inset Quotes erd
+\end_inset
+
+ option if all you need is basic X compatibility.
 \end_layout
 
 \begin_layout Standard
 
 \lang english
-There are multiple ways to implement a 2D X.Org driver: ShadowFB, XAA, EXA.
- Another simple way of implementing X.Org support is through the FBDev module.
- This module implements X.Org on top of an existing, in-kernel framebuffer
- driver.
+http://www.x.org/wiki/DriverDevelopment
+\end_layout
+
+\begin_layout Section
+
+\lang english
+Creating a basic driver
 \end_layout
 
 \begin_layout Standard
 
 \lang english
-http://www.x.org/wiki/DriverDevelopment
+Mandatory entry points
 \end_layout
 
-\begin_layout Section
+\begin_layout Paragraph
+
+\lang english
+PreInit
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+Bool PreInit (ScrnInfoPtr pScreen, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+ScreenInit
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+This function gets called on startup.
+ It is responsible for setting up all per-screen state.
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+Bool ScreenInit(int scrnIndex, ScreenPtr screen, int argc, char **argv);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+EnterVT
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+This is called when VT switching back to the X server.
+ In a KMS-enabled X driver, this will only need to acquire the DRM master
+ bit and set the video mode.
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+Bool EnterVT(int scrnIndex, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+LeaveVT
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+This is called when switching away from the X server to another VT.
+ In a KMS-enabled X driver, this only needs to drop the DRM master bit.
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+/Bool LeaveVT(int scrnIndex, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+Optional functions (but very useful)
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+SwitchMode
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+Sets a video mode.
+\end_layout
+
+\begin_layout Standard
 
 \lang english
-Initializing a driver
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+Bool SwitchMode(int scrnIndex, DisplayModePtr mode, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+AdjustFrame
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+This function is used to initialize the Start Address - the first displayed
+ location in the video memory (randr 1.3 panning)
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+void AdjustFrame(int scrnIndex, int x, int y, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+FreeScreen
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+void FreeScreen(int scrnIndex, int flags);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
 \end_layout
 
 \begin_layout Section
@@ -5752,6 +6076,48 @@ Shadowfb acceleration.
 
 \end_layout
 
+\begin_layout Standard
+To implement shadowFB acceleration, a driver simply calls Bool ShadowFBInit(Scre
+enPtr pScreen, RefreshAreaFuncPtr refreshArea ).
+ refreshArea is a function pointer with the following profile:
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+\begin_inset ERT
+status open
+
+\begin_layout Plain Layout
+
+
+\backslash
+begin{lstlisting}{}
+\end_layout
+
+\begin_layout Plain Layout
+
+void RefreshAreaFuncPtr(ScrnInfoPtr pScreen, int numBoxes, BoxPtr pBox);
+\end_layout
+
+\begin_layout Plain Layout
+
+
+\backslash
+end{lstlisting}{}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The callback should refresh numBoxes contained in the pBox[] array.
+ It can be achieved either with a CPU copy to video memory or with a DMA
+ on the GPU.
+\end_layout
+
 \begin_layout Section
 
 \lang english
@@ -5800,13 +6166,33 @@ EXA is an interface inside X.Org implemented by drivers for 2D acceleration.
 \begin_layout Standard
 
 \lang english
-Here is a detail of the main EXA acceleration functions.
+EXA is implemented in the driver as a series of callbacks; the following
+ gives a detail of the EXA acceleration functions that a driver should implement
+; some of them like Composite() are optional.
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+Solid
 \end_layout
 
 \begin_layout Standard
 
 \lang english
-Solid - fill an area with a solid color (RGBA)
+Solid just fills an area with a solid color (RGBA).
+ Just like with all EXA callbacks, there are three main functions: the first
+ one is the Prepare() function which sets the graphics state required to
+ do solid fills.
+ The second one is the Solid() function which actually does the solid fill.
+ The last one is Done() which signals to the driver that the current series
+ of Solid() calls is over, so that it can restore graphics state and/or
+ flush required GPU states.
+\end_layout
+
+\begin_layout Standard
+Note that Solid() can be called many times in a row between a Prepare()
+ and Done() (the same applies to other EXA callbacks).
 \end_layout
 
 \begin_layout Standard
@@ -5900,10 +6286,19 @@ end{lstlisting}{}
 
 \end_layout
 
+\begin_layout Paragraph
+
+\lang english
+Copy
+\end_layout
+
 \begin_layout Standard
 
 \lang english
-Copy - copies a rectangle area from and to video memory
+Copy is a simple blit function; it copies a rectangle area in video memory
+ from one pixmap to another pixmap (possibly the same one).
+ Just like with Solid() it has a Prepare/Copy/Done triplet of callbacks,
+ and Copy() can be called many times in a row.
 \end_layout
 
 \begin_layout Standard
@@ -5998,19 +6393,43 @@ end{lstlisting}{}
 
 \end_layout
 
+\begin_layout Paragraph
+
+\lang english
+Composite
+\end_layout
+
 \begin_layout Standard
 
 \lang english
-Composite - optional interface used to achieve composite operations like
- blending.
+Composite is an optional interface used to achieve composite operations
+ like blending.
  This allows accelerating 2D desktop effects like blending, scaling, operations
  with masks...
+ All in all, the composite() hook is sufficient to implement a basic 2D
+ composite window manager (KDE and XFCE are examples of window compositors
+ indirectly using EXA trough the Render API to implement compositing).
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+If the driver doesn't support the required operation, it is free to return
+ false, in which case the EXA layer will call into the pixman library as
+ a software fallback.
+ Of course this will be done on the CPU as a fallback.
+\end_layout
+
+\begin_layout Paragraph
+
+\lang english
+UploadToScreen
 \end_layout
 
 \begin_layout Standard
 
 \lang english
-UploadToScreen - copies an area from system memory to video memory
+UploadToScreen copies an area from system memory to video memory
 \end_layout
 
 \begin_layout Standard
@@ -6044,10 +6463,16 @@ end{lstlisting}{}
 
 \end_layout
 
+\begin_layout Paragraph
+
+\lang english
+DowndloadFromScreen
+\end_layout
+
 \begin_layout Standard
 
 \lang english
-DowndloadFromScreen - copies an area from video memory to system memory
+DownloadFromScreen copies an area from video memory to system memory
 \end_layout
 
 \begin_layout Standard
@@ -6081,18 +6506,30 @@ end{lstlisting}{}
 
 \end_layout
 
+\begin_layout Paragraph
+
+\lang english
+PrepareAccess
+\end_layout
+
 \begin_layout Standard
 
 \lang english
-PrepareAccess - makes the pixmap accessible from the CPU.
+PrepareAccess makes the pixmap accessible from the CPU.
  This includes mapping it into memory, copying it from unmappable video
  memory, untiling the pixmap...
 \end_layout
 
+\begin_layout Paragraph
+
+\lang english
+FinishAccess
+\end_layout
+
 \begin_layout Standard
 
 \lang english
-FinishAccess - is called once the pixmap is done being accessed, and must
+FinishAccess is called once the pixmap is done being accessed, and must
  do the opposite of PrepareAccess.
 \end_layout
 
@@ -6103,6 +6540,28 @@ EXA Pixmap migration.
  EXA tries to be smart about pixmap migration, and will only migrate the
  parts of a pixmap that are required for an operation.
  Migration heuristics Greedy/Mixed/Driver.
+ Since fallbacks might require pixmap migration, it is not always better
+ to implement some of the composite interface.
+ For example if the usage pattern often calls operations A->B->C and only
+ B is GPU accelerated, A will be done on the CPU, B will trigger a migration
+ to GPU memory and will do the operation on the GPU, and C will trigger
+ a migration back to system memory and do the third operation on the CPU.
+ Since the overhead and cost of pixmap migration is so high, the end result
+ is probably slower than doing all three operations on the CPU, and therefore
+ the newly added composite() functionality actually results in a slowdown!
+\end_layout
+
+\begin_layout Standard
+
+\lang english
+As a side effect, it is often better to profile before implemnting specific
+ EXA composite() functions, and look at the common calling patterns; a very
+ common example is antialiased fonts (and they will show different calling
+ patterns if subpixel rendering is enabled or not).
+\end_layout
+
+\begin_layout Section
+Pixman
 \end_layout
 
 \begin_layout Standard
@@ -6114,6 +6573,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -6335,13 +6795,16 @@ status open
 \begin_inset Formula $\left[\begin{array}{c}
 R\\
 G\\
-B\end{array}\right]=\left[\begin{array}{ccc}
+B
+\end{array}\right]=\left[\begin{array}{ccc}
 1 & 0 & 1.13983\\
 1 & -0.39465 & -0.58060\\
-1 & 2.03211 & 0\end{array}\right]\left[\begin{array}{c}
+1 & 2.03211 & 0
+\end{array}\right]\left[\begin{array}{c}
 Y\\
 U\\
-V\end{array}\right]$
+V
+\end{array}\right]$
 \end_inset
 
 
@@ -6400,13 +6863,16 @@ status open
 \begin_inset Formula $\left[\begin{array}{c}
 R\\
 G\\
-B\end{array}\right]=\left[\begin{array}{ccc}
+B
+\end{array}\right]=\left[\begin{array}{ccc}
 1 & 0 & 1.13983\\
 1 & -0.39465 & -0.58060\\
-1 & 2.03211 & 0\end{array}\right]\left[\begin{array}{c}
+1 & 2.03211 & 0
+\end{array}\right]\left[\begin{array}{c}
 Y\\
 U\\
-V\end{array}\right]$
+V
+\end{array}\right]$
 \end_inset
 
 
@@ -6942,7 +7408,7 @@ status open
 \lang english
 \begin_inset Tabular
 <lyxtabular version="3" rows="6" columns="4">
-<features>
+<features tabularvalignment="middle">
 <column alignment="center" valignment="top" width="1.5cm">
 <column alignment="center" valignment="top" width="1.2cm">
 <column alignment="center" valignment="top" width="3.5cm">
@@ -7384,6 +7850,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8067,6 +8534,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8167,6 +8635,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8406,6 +8875,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8495,6 +8965,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8774,6 +9245,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"
@@ -8998,6 +9470,7 @@ hor_pos "c"
 has_inner_box 1
 inner_pos "t"
 use_parbox 0
+use_makebox 0
 width "100col%"
 special "none"
 height "1in"