summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/gpu.tmpl118
-rw-r--r--Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt12
-rw-r--r--Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt1
-rw-r--r--Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt3
-rw-r--r--Documentation/devicetree/bindings/display/msm/dsi.txt32
-rw-r--r--Documentation/devicetree/bindings/display/msm/hdmi.txt46
-rw-r--r--Documentation/devicetree/bindings/display/panel/lg,lp120up1.txt7
-rw-r--r--Documentation/devicetree/bindings/display/panel/urt,umsh-8596md.txt16
-rw-r--r--Documentation/devicetree/bindings/display/renesas,du.txt16
-rw-r--r--Documentation/devicetree/bindings/display/rockchip/inno_hdmi-rockchip.txt50
-rw-r--r--Documentation/dma-buf-sharing.txt40
11 files changed, 268 insertions, 73 deletions
diff --git a/Documentation/DocBook/gpu.tmpl b/Documentation/DocBook/gpu.tmpl
index a8669330b456..1692c4dd5487 100644
--- a/Documentation/DocBook/gpu.tmpl
+++ b/Documentation/DocBook/gpu.tmpl
@@ -1816,7 +1816,7 @@ void intel_crt_init(struct drm_device *dev)
<td valign="top" >Description/Restrictions</td>
</tr>
<tr>
- <td rowspan="37" valign="top" >DRM</td>
+ <td rowspan="42" valign="top" >DRM</td>
<td valign="top" >Generic</td>
<td valign="top" >“rotation”</td>
<td valign="top" >BITMASK</td>
@@ -2068,7 +2068,7 @@ void intel_crt_init(struct drm_device *dev)
<td valign="top" >property to suggest an Y offset for a connector</td>
</tr>
<tr>
- <td rowspan="3" valign="top" >Optional</td>
+ <td rowspan="8" valign="top" >Optional</td>
<td valign="top" >“scaling mode”</td>
<td valign="top" >ENUM</td>
<td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
@@ -2092,6 +2092,61 @@ void intel_crt_init(struct drm_device *dev)
<td valign="top" >TBD</td>
</tr>
<tr>
+ <td valign="top" >“DEGAMMA_LUT”</td>
+ <td valign="top" >BLOB</td>
+ <td valign="top" >0</td>
+ <td valign="top" >CRTC</td>
+ <td valign="top" >DRM property to set the degamma lookup table
+ (LUT) mapping pixel data from the framebuffer before it is
+ given to the transformation matrix. The data is an interpreted
+ as an array of struct drm_color_lut elements. Hardware might
+ choose not to use the full precision of the LUT elements nor
+ use all the elements of the LUT (for example the hardware
+ might choose to interpolate between LUT[0] and LUT[4]). </td>
+ </tr>
+ <tr>
+ <td valign="top" >“DEGAMMA_LUT_SIZE”</td>
+ <td valign="top" >RANGE | IMMUTABLE</td>
+ <td valign="top" >Min=0, Max=UINT_MAX</td>
+ <td valign="top" >CRTC</td>
+ <td valign="top" >DRM property to gives the size of the lookup
+ table to be set on the DEGAMMA_LUT property (the size depends
+ on the underlying hardware).</td>
+ </tr>
+ <tr>
+ <td valign="top" >“CTM”</td>
+ <td valign="top" >BLOB</td>
+ <td valign="top" >0</td>
+ <td valign="top" >CRTC</td>
+ <td valign="top" >DRM property to set the current
+ transformation matrix (CTM) apply to pixel data after the
+ lookup through the degamma LUT and before the lookup through
+ the gamma LUT. The data is an interpreted as a struct
+ drm_color_ctm.</td>
+ </tr>
+ <tr>
+ <td valign="top" >“GAMMA_LUT”</td>
+ <td valign="top" >BLOB</td>
+ <td valign="top" >0</td>
+ <td valign="top" >CRTC</td>
+ <td valign="top" >DRM property to set the gamma lookup table
+ (LUT) mapping pixel data after to the transformation matrix to
+ data sent to the connector. The data is an interpreted as an
+ array of struct drm_color_lut elements. Hardware might choose
+ not to use the full precision of the LUT elements nor use all
+ the elements of the LUT (for example the hardware might choose
+ to interpolate between LUT[0] and LUT[4]).</td>
+ </tr>
+ <tr>
+ <td valign="top" >“GAMMA_LUT_SIZE”</td>
+ <td valign="top" >RANGE | IMMUTABLE</td>
+ <td valign="top" >Min=0, Max=UINT_MAX</td>
+ <td valign="top" >CRTC</td>
+ <td valign="top" >DRM property to gives the size of the lookup
+ table to be set on the GAMMA_LUT property (the size depends on
+ the underlying hardware).</td>
+ </tr>
+ <tr>
<td rowspan="20" valign="top" >i915</td>
<td rowspan="2" valign="top" >Generic</td>
<td valign="top" >"Broadcast RGB"</td>
@@ -2886,52 +2941,8 @@ void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
</sect2>
<sect2>
<title>File Operations</title>
- <synopsis>const struct file_operations *fops</synopsis>
- <abstract>File operations for the DRM device node.</abstract>
- <para>
- Drivers must define the file operations structure that forms the DRM
- userspace API entry point, even though most of those operations are
- implemented in the DRM core. The <methodname>open</methodname>,
- <methodname>release</methodname> and <methodname>ioctl</methodname>
- operations are handled by
- <programlisting>
- .owner = THIS_MODULE,
- .open = drm_open,
- .release = drm_release,
- .unlocked_ioctl = drm_ioctl,
- #ifdef CONFIG_COMPAT
- .compat_ioctl = drm_compat_ioctl,
- #endif
- </programlisting>
- </para>
- <para>
- Drivers that implement private ioctls that requires 32/64bit
- compatibility support must provide their own
- <methodname>compat_ioctl</methodname> handler that processes private
- ioctls and calls <function>drm_compat_ioctl</function> for core ioctls.
- </para>
- <para>
- The <methodname>read</methodname> and <methodname>poll</methodname>
- operations provide support for reading DRM events and polling them. They
- are implemented by
- <programlisting>
- .poll = drm_poll,
- .read = drm_read,
- .llseek = no_llseek,
- </programlisting>
- </para>
- <para>
- The memory mapping implementation varies depending on how the driver
- manages memory. Pre-GEM drivers will use <function>drm_mmap</function>,
- while GEM-aware drivers will use <function>drm_gem_mmap</function>. See
- <xref linkend="drm-gem"/>.
- <programlisting>
- .mmap = drm_gem_mmap,
- </programlisting>
- </para>
- <para>
- No other file operation is supported by the DRM API.
- </para>
+!Pdrivers/gpu/drm/drm_fops.c file operations
+!Edrivers/gpu/drm/drm_fops.c
</sect2>
<sect2>
<title>IOCTLs</title>
@@ -3319,6 +3330,12 @@ int num_ioctls;</synopsis>
!Pdrivers/gpu/drm/i915/intel_csr.c csr support for dmc
!Idrivers/gpu/drm/i915/intel_csr.c
</sect2>
+ <sect2>
+ <title>Video BIOS Table (VBT)</title>
+!Pdrivers/gpu/drm/i915/intel_bios.c Video BIOS Table (VBT)
+!Idrivers/gpu/drm/i915/intel_bios.c
+!Idrivers/gpu/drm/i915/intel_bios.h
+ </sect2>
</sect1>
<sect1>
@@ -3460,6 +3477,7 @@ int num_ioctls;</synopsis>
</sect1>
<sect1>
<title>Public constants</title>
+!Finclude/linux/vga_switcheroo.h vga_switcheroo_handler_flags_t
!Finclude/linux/vga_switcheroo.h vga_switcheroo_client_id
!Finclude/linux/vga_switcheroo.h vga_switcheroo_state
</sect1>
@@ -3488,6 +3506,10 @@ int num_ioctls;</synopsis>
<title>Backlight control</title>
!Pdrivers/platform/x86/apple-gmux.c Backlight control
</sect2>
+ <sect2>
+ <title>Public functions</title>
+!Iinclude/linux/apple-gmux.h
+ </sect2>
</sect1>
</chapter>
diff --git a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt
index 56a961aa5061..9f97df4d5152 100644
--- a/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt
+++ b/Documentation/devicetree/bindings/display/brcm,bcm-vc4.txt
@@ -35,6 +35,12 @@ Optional properties for HDMI:
as an interrupt/status bit in the HDMI controller
itself). See bindings/pinctrl/brcm,bcm2835-gpio.txt
+Required properties for V3D:
+- compatible: Should be "brcm,bcm2835-v3d"
+- reg: Physical base address and length of the V3D's registers
+- interrupts: The interrupt number
+ See bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt
+
Example:
pixelvalve@7e807000 {
compatible = "brcm,bcm2835-pixelvalve2";
@@ -60,6 +66,12 @@ hdmi: hdmi@7e902000 {
clock-names = "pixel", "hdmi";
};
+v3d: v3d@7ec00000 {
+ compatible = "brcm,bcm2835-v3d";
+ reg = <0x7ec00000 0x1000>;
+ interrupts = <1 10>;
+};
+
vc4: gpu {
compatible = "brcm,bcm2835-vc4";
};
diff --git a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt
index 0e6f0c024858..22756b3dede2 100644
--- a/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt
+++ b/Documentation/devicetree/bindings/display/exynos/exynos_dsim.txt
@@ -6,6 +6,7 @@ Required properties:
"samsung,exynos4210-mipi-dsi" /* for Exynos4 SoCs */
"samsung,exynos4415-mipi-dsi" /* for Exynos4415 SoC */
"samsung,exynos5410-mipi-dsi" /* for Exynos5410/5420/5440 SoCs */
+ "samsung,exynos5422-mipi-dsi" /* for Exynos5422/5800 SoCs */
"samsung,exynos5433-mipi-dsi" /* for Exynos5433 SoCs */
- reg: physical base address and length of the registers set for the device
- interrupts: should contain DSI interrupt
diff --git a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt
index 27c3ce0db16a..c7c6b9af87ac 100644
--- a/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt
+++ b/Documentation/devicetree/bindings/display/exynos/samsung-fimd.txt
@@ -12,7 +12,8 @@ Required properties:
"samsung,exynos3250-fimd"; /* for Exynos3250/3472 SoCs */
"samsung,exynos4210-fimd"; /* for Exynos4 SoCs */
"samsung,exynos4415-fimd"; /* for Exynos4415 SoC */
- "samsung,exynos5250-fimd"; /* for Exynos5 SoCs */
+ "samsung,exynos5250-fimd"; /* for Exynos5250 SoCs */
+ "samsung,exynos5420-fimd"; /* for Exynos5420/5422/5800 SoCs */
- reg: physical base address and length of the FIMD registers set.
diff --git a/Documentation/devicetree/bindings/display/msm/dsi.txt b/Documentation/devicetree/bindings/display/msm/dsi.txt
index e7423bea1424..f5948c48b9a2 100644
--- a/Documentation/devicetree/bindings/display/msm/dsi.txt
+++ b/Documentation/devicetree/bindings/display/msm/dsi.txt
@@ -44,9 +44,34 @@ Optional properties:
- pinctrl-names: the pin control state names; should contain "default"
- pinctrl-0: the default pinctrl state (active)
- pinctrl-n: the "sleep" pinctrl state
-- port: DSI controller output port. This contains one endpoint subnode, with its
- remote-endpoint set to the phandle of the connected panel's endpoint.
- See Documentation/devicetree/bindings/graph.txt for device graph info.
+- port: DSI controller output port, containing one endpoint subnode.
+
+ DSI Endpoint properties:
+ - remote-endpoint: set to phandle of the connected panel's endpoint.
+ See Documentation/devicetree/bindings/graph.txt for device graph info.
+ - qcom,data-lane-map: this describes how the logical DSI lanes are mapped
+ to the physical lanes on the given platform. The value contained in
+ index n describes what logical data lane is mapped to the physical data
+ lane n (DATAn, where n lies between 0 and 3).
+
+ For example:
+
+ qcom,data-lane-map = <3 0 1 2>;
+
+ The above mapping describes that the logical data lane DATA3 is mapped to
+ the physical data lane DATA0, logical DATA0 to physical DATA1, logic DATA1
+ to phys DATA2 and logic DATA2 to phys DATA3.
+
+ There are only a limited number of physical to logical mappings possible:
+
+ "0123": Logic 0->Phys 0; Logic 1->Phys 1; Logic 2->Phys 2; Logic 3->Phys 3;
+ "3012": Logic 3->Phys 0; Logic 0->Phys 1; Logic 1->Phys 2; Logic 2->Phys 3;
+ "2301": Logic 2->Phys 0; Logic 3->Phys 1; Logic 0->Phys 2; Logic 1->Phys 3;
+ "1230": Logic 1->Phys 0; Logic 2->Phys 1; Logic 3->Phys 2; Logic 0->Phys 3;
+ "0321": Logic 0->Phys 0; Logic 3->Phys 1; Logic 2->Phys 2; Logic 1->Phys 3;
+ "1032": Logic 1->Phys 0; Logic 0->Phys 1; Logic 3->Phys 2; Logic 2->Phys 3;
+ "2103": Logic 2->Phys 0; Logic 1->Phys 1; Logic 0->Phys 2; Logic 3->Phys 3;
+ "3210": Logic 3->Phys 0; Logic 2->Phys 1; Logic 1->Phys 2; Logic 0->Phys 3;
DSI PHY:
Required properties:
@@ -131,6 +156,7 @@ Example:
port {
dsi0_out: endpoint {
remote-endpoint = <&panel_in>;
+ lanes = <0 1 2 3>;
};
};
};
diff --git a/Documentation/devicetree/bindings/display/msm/hdmi.txt b/Documentation/devicetree/bindings/display/msm/hdmi.txt
index 379ee2ea9a3d..b63f614e0c04 100644
--- a/Documentation/devicetree/bindings/display/msm/hdmi.txt
+++ b/Documentation/devicetree/bindings/display/msm/hdmi.txt
@@ -11,6 +11,7 @@ Required properties:
- reg: Physical base address and length of the controller's registers
- reg-names: "core_physical"
- interrupts: The interrupt signal from the hdmi block.
+- power-domains: Should be <&mmcc MDSS_GDSC>.
- clocks: device clocks
See ../clocks/clock-bindings.txt for details.
- qcom,hdmi-tx-ddc-clk-gpio: ddc clk pin
@@ -18,6 +19,8 @@ Required properties:
- qcom,hdmi-tx-hpd-gpio: hpd pin
- core-vdda-supply: phandle to supply regulator
- hdmi-mux-supply: phandle to mux regulator
+- phys: the phandle for the HDMI PHY device
+- phy-names: the name of the corresponding PHY device
Optional properties:
- qcom,hdmi-tx-mux-en-gpio: hdmi mux enable pin
@@ -27,15 +30,38 @@ Optional properties:
- pinctrl-0: the default pinctrl state (active)
- pinctrl-1: the "sleep" pinctrl state
+HDMI PHY:
+Required properties:
+- compatible: Could be the following
+ * "qcom,hdmi-phy-8660"
+ * "qcom,hdmi-phy-8960"
+ * "qcom,hdmi-phy-8974"
+ * "qcom,hdmi-phy-8084"
+ * "qcom,hdmi-phy-8996"
+- #phy-cells: Number of cells in a PHY specifier; Should be 0.
+- reg: Physical base address and length of the registers of the PHY sub blocks.
+- reg-names: The names of register regions. The following regions are required:
+ * "hdmi_phy"
+ * "hdmi_pll"
+ For HDMI PHY on msm8996, these additional register regions are required:
+ * "hdmi_tx_l0"
+ * "hdmi_tx_l1"
+ * "hdmi_tx_l3"
+ * "hdmi_tx_l4"
+- power-domains: Should be <&mmcc MDSS_GDSC>.
+- clocks: device clocks
+ See Documentation/devicetree/bindings/clocks/clock-bindings.txt for details.
+- core-vdda-supply: phandle to vdda regulator device node
+
Example:
/ {
...
- hdmi: qcom,hdmi-tx-8960@4a00000 {
+ hdmi: hdmi@4a00000 {
compatible = "qcom,hdmi-tx-8960";
reg-names = "core_physical";
- reg = <0x04a00000 0x1000>;
+ reg = <0x04a00000 0x2f0>;
interrupts = <GIC_SPI 79 0>;
power-domains = <&mmcc MDSS_GDSC>;
clock-names =
@@ -54,5 +80,21 @@ Example:
pinctrl-names = "default", "sleep";
pinctrl-0 = <&hpd_active &ddc_active &cec_active>;
pinctrl-1 = <&hpd_suspend &ddc_suspend &cec_suspend>;
+
+ phys = <&hdmi_phy>;
+ phy-names = "hdmi_phy";
+ };
+
+ hdmi_phy: phy@4a00400 {
+ compatible = "qcom,hdmi-phy-8960";
+ reg-names = "hdmi_phy",
+ "hdmi_pll";
+ reg = <0x4a00400 0x60>,
+ <0x4a00500 0x100>;
+ #phy-cells = <0>;
+ power-domains = <&mmcc MDSS_GDSC>;
+ clock-names = "slave_iface_clk";
+ clocks = <&mmcc HDMI_S_AHB_CLK>;
+ core-vdda-supply = <&pm8921_hdmi_mvs>;
};
};
diff --git a/Documentation/devicetree/bindings/display/panel/lg,lp120up1.txt b/Documentation/devicetree/bindings/display/panel/lg,lp120up1.txt
new file mode 100644
index 000000000000..8c5de692c55c
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/lg,lp120up1.txt
@@ -0,0 +1,7 @@
+LG 12.0" (1920x1280 pixels) TFT LCD panel
+
+Required properties:
+- compatible: should be "lg,lp120up1"
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/panel/urt,umsh-8596md.txt b/Documentation/devicetree/bindings/display/panel/urt,umsh-8596md.txt
new file mode 100644
index 000000000000..088a6cea5015
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/panel/urt,umsh-8596md.txt
@@ -0,0 +1,16 @@
+United Radiant Technology UMSH-8596MD-xT 7.0" WVGA TFT LCD panel
+
+Supported are LVDS versions (-11T, -19T) and parallel ones
+(-T, -1T, -7T, -20T).
+
+Required properties:
+- compatible: should be one of:
+ "urt,umsh-8596md-t",
+ "urt,umsh-8596md-1t",
+ "urt,umsh-8596md-7t",
+ "urt,umsh-8596md-11t",
+ "urt,umsh-8596md-19t",
+ "urt,umsh-8596md-20t".
+
+This binding is compatible with the simple-panel binding, which is specified
+in simple-panel.txt in this directory.
diff --git a/Documentation/devicetree/bindings/display/renesas,du.txt b/Documentation/devicetree/bindings/display/renesas,du.txt
index eccd4f4867b2..0d30e42e40be 100644
--- a/Documentation/devicetree/bindings/display/renesas,du.txt
+++ b/Documentation/devicetree/bindings/display/renesas,du.txt
@@ -8,6 +8,7 @@ Required Properties:
- "renesas,du-r8a7791" for R8A7791 (R-Car M2-W) compatible DU
- "renesas,du-r8a7793" for R8A7793 (R-Car M2-N) compatible DU
- "renesas,du-r8a7794" for R8A7794 (R-Car E2) compatible DU
+ - "renesas,du-r8a7795" for R8A7795 (R-Car H3) compatible DU
- reg: A list of base address and length of each memory resource, one for
each entry in the reg-names property.
@@ -24,7 +25,7 @@ Required Properties:
- clock-names: Name of the clocks. This property is model-dependent.
- R8A7779 uses a single functional clock. The clock doesn't need to be
named.
- - R8A779[0134] use one functional clock per channel and one clock per LVDS
+ - R8A779[01345] use one functional clock per channel and one clock per LVDS
encoder (if available). The functional clocks must be named "du.x" with
"x" being the channel numerical index. The LVDS clocks must be named
"lvds.x" with "x" being the LVDS encoder numerical index.
@@ -41,13 +42,14 @@ bindings specified in Documentation/devicetree/bindings/graph.txt.
The following table lists for each supported model the port number
corresponding to each DU output.
- Port 0 Port1 Port2
+ Port 0 Port1 Port2 Port3
-----------------------------------------------------------------------------
- R8A7779 (H1) DPAD 0 DPAD 1 -
- R8A7790 (H2) DPAD LVDS 0 LVDS 1
- R8A7791 (M2-W) DPAD LVDS 0 -
- R8A7793 (M2-N) DPAD LVDS 0 -
- R8A7794 (E2) DPAD 0 DPAD 1 -
+ R8A7779 (H1) DPAD 0 DPAD 1 - -
+ R8A7790 (H2) DPAD LVDS 0 LVDS 1 -
+ R8A7791 (M2-W) DPAD LVDS 0 - -
+ R8A7793 (M2-N) DPAD LVDS 0 - -
+ R8A7794 (E2) DPAD 0 DPAD 1 - -
+ R8A7795 (H3) DPAD HDMI 0 HDMI 1 LVDS
Example: R8A7790 (R-Car H2) DU
diff --git a/Documentation/devicetree/bindings/display/rockchip/inno_hdmi-rockchip.txt b/Documentation/devicetree/bindings/display/rockchip/inno_hdmi-rockchip.txt
new file mode 100644
index 000000000000..8096a29f9776
--- /dev/null
+++ b/Documentation/devicetree/bindings/display/rockchip/inno_hdmi-rockchip.txt
@@ -0,0 +1,50 @@
+Rockchip specific extensions to the Innosilicon HDMI
+================================
+
+Required properties:
+- compatible:
+ "rockchip,rk3036-inno-hdmi";
+- reg:
+ Physical base address and length of the controller's registers.
+- clocks, clock-names:
+ Phandle to hdmi controller clock, name should be "pclk"
+- interrupts:
+ HDMI interrupt number
+- ports:
+ Contain one port node with endpoint definitions as defined in
+ Documentation/devicetree/bindings/graph.txt.
+- pinctrl-0, pinctrl-name:
+ Switch the iomux of HPD/CEC pins to HDMI function.
+
+Example:
+hdmi: hdmi@20034000 {
+ compatible = "rockchip,rk3036-inno-hdmi";
+ reg = <0x20034000 0x4000>;
+ interrupts = <GIC_SPI 45 IRQ_TYPE_LEVEL_HIGH>;
+ clocks = <&cru PCLK_HDMI>;
+ clock-names = "pclk";
+ pinctrl-names = "default";
+ pinctrl-0 = <&hdmi_ctl>;
+ status = "disabled";
+
+ hdmi_in: port {
+ #address-cells = <1>;
+ #size-cells = <0>;
+ hdmi_in_lcdc: endpoint@0 {
+ reg = <0>;
+ remote-endpoint = <&lcdc_out_hdmi>;
+ };
+ };
+};
+
+&pinctrl {
+ hdmi {
+ hdmi_ctl: hdmi-ctl {
+ rockchip,pins = <1 8 RK_FUNC_1 &pcfg_pull_none>,
+ <1 9 RK_FUNC_1 &pcfg_pull_none>,
+ <1 10 RK_FUNC_1 &pcfg_pull_none>,
+ <1 11 RK_FUNC_1 &pcfg_pull_none>;
+ };
+ };
+
+};
diff --git a/Documentation/dma-buf-sharing.txt b/Documentation/dma-buf-sharing.txt
index 480c8de3c2c4..32ac32e773e1 100644
--- a/Documentation/dma-buf-sharing.txt
+++ b/Documentation/dma-buf-sharing.txt
@@ -257,17 +257,15 @@ Access to a dma_buf from the kernel context involves three steps:
Interface:
int dma_buf_begin_cpu_access(struct dma_buf *dmabuf,
- size_t start, size_t len,
enum dma_data_direction direction)
This allows the exporter to ensure that the memory is actually available for
cpu access - the exporter might need to allocate or swap-in and pin the
backing storage. The exporter also needs to ensure that cpu access is
- coherent for the given range and access direction. The range and access
- direction can be used by the exporter to optimize the cache flushing, i.e.
- access outside of the range or with a different direction (read instead of
- write) might return stale or even bogus data (e.g. when the exporter needs to
- copy the data to temporary storage).
+ coherent for the access direction. The direction can be used by the exporter
+ to optimize the cache flushing, i.e. access with a different direction (read
+ instead of write) might return stale or even bogus data (e.g. when the
+ exporter needs to copy the data to temporary storage).
This step might fail, e.g. in oom conditions.
@@ -322,14 +320,13 @@ Access to a dma_buf from the kernel context involves three steps:
3. Finish access
- When the importer is done accessing the range specified in begin_cpu_access,
- it needs to announce this to the exporter (to facilitate cache flushing and
- unpinning of any pinned resources). The result of any dma_buf kmap calls
- after end_cpu_access is undefined.
+ When the importer is done accessing the CPU, it needs to announce this to
+ the exporter (to facilitate cache flushing and unpinning of any pinned
+ resources). The result of any dma_buf kmap calls after end_cpu_access is
+ undefined.
Interface:
void dma_buf_end_cpu_access(struct dma_buf *dma_buf,
- size_t start, size_t len,
enum dma_data_direction dir);
@@ -353,7 +350,26 @@ Being able to mmap an export dma-buf buffer object has 2 main use-cases:
handles, too). So it's beneficial to support this in a similar fashion on
dma-buf to have a good transition path for existing Android userspace.
- No special interfaces, userspace simply calls mmap on the dma-buf fd.
+ No special interfaces, userspace simply calls mmap on the dma-buf fd, making
+ sure that the cache synchronization ioctl (DMA_BUF_IOCTL_SYNC) is *always*
+ used when the access happens. This is discussed next paragraphs.
+
+ Some systems might need some sort of cache coherency management e.g. when
+ CPU and GPU domains are being accessed through dma-buf at the same time. To
+ circumvent this problem there are begin/end coherency markers, that forward
+ directly to existing dma-buf device drivers vfunc hooks. Userspace can make
+ use of those markers through the DMA_BUF_IOCTL_SYNC ioctl. The sequence
+ would be used like following:
+ - mmap dma-buf fd
+ - for each drawing/upload cycle in CPU 1. SYNC_START ioctl, 2. read/write
+ to mmap area 3. SYNC_END ioctl. This can be repeated as often as you
+ want (with the new data being consumed by the GPU or say scanout device)
+ - munmap once you don't need the buffer any more
+
+ Therefore, for correctness and optimal performance, systems with the memory
+ cache shared by the GPU and CPU i.e. the "coherent" and also the
+ "incoherent" are always required to use SYNC_START and SYNC_END before and
+ after, respectively, when accessing the mapped address.
2. Supporting existing mmap interfaces in importers