AlexIndustrial/mesa
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs/isl: use hawkmoth instead of doxygen

Browse Source 
Use the hawkmoth c:auto* directives to incorporate isl documentation.

Convert @param style parameter descriptions to rst info field lists.
Add static stubs for generated headers. Fix a lot of references, in
particular the symbols are now in the Sphinx C domain, not C++
domain. Tweak syntax here and there.

Based on the earlier work by Erik Faye-Lund <kusmabite@gmail.com>

Reviewed-by: Erik Faye-Lund <erik.faye-lund@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/24507>
This commit is contained in:
Jani Nikula
2023-08-04 18:59:58 +03:00
committed by Marge Bot
parent eabd93bba8
commit ae74d486ad
12 changed files with 294 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/conf.py
View File

@@ -225,6 +225,8 @@ hawkmoth_clang = [
'-Iinclude/',
'-Isrc/',
'-Isrc/gallium/include/',
'-Isrc/intel/',
'-Isrc/mesa/',
'-DHAVE_STRUCT_TIMESPEC',
'-DHAVE_PTHREAD',
'-DHAVE_ENDIAN_H',

0
docs/header-stubs/genxml/genX_bits.h Normal file
View File

3
docs/header-stubs/intel/dev/intel_wa.h Normal file
View File

@@ -0,0 +1,3 @@
enum intel_workaround_id {
INTEL_WA_NUM
};

54
docs/isl/aux-surf-comp.rst
View File

@@ -8,7 +8,7 @@ more memory is allocated, the scheme allows us to reduce our over-all memory
bandwidth since the auxiliary data is much smaller than the main surface.
The simplest example of this is single-sample fast clears
(:cpp:enumerator:`isl_aux_usage::ISL_AUX_USAGE_CCS_D`) on Ivy Bridge through
(:c:enumerator:`isl_aux_usage.ISL_AUX_USAGE_CCS_D`) on Ivy Bridge through
Broadwell and later. For this scheme, the auxiliary surface stores a single
bit for each cache-line-pair in the main surface. If that bit is set, then the
entire cache line pair contains only the clear color as provided in the
@@ -43,12 +43,19 @@ Types of surface compression
Intel hardware has several different compression schemes that all work along
similar lines:
.. doxygenenum:: isl_aux_usage
.. doxygenfunction:: isl_aux_usage_has_fast_clears
.. doxygenfunction:: isl_aux_usage_has_compression
.. doxygenfunction:: isl_aux_usage_has_hiz
.. doxygenfunction:: isl_aux_usage_has_mcs
.. doxygenfunction:: isl_aux_usage_has_ccs
.. c:autoenum:: isl_aux_usage
:file: src/intel/isl/isl.h
:members:
.. c:autofunction:: isl_aux_usage_has_fast_clears
.. c:autofunction:: isl_aux_usage_has_compression
.. c:autofunction:: isl_aux_usage_has_hiz
.. c:autofunction:: isl_aux_usage_has_mcs
.. c:autofunction:: isl_aux_usage_has_ccs
Creating auxiliary surfaces
---------------------------
@@ -57,10 +64,13 @@ Each type of data compression requires some type of auxiliary data on the side.
For most, this involves a second auxiliary surface. ISL provides helpers for
creating each of these types of surfaces:
.. doxygenfunction:: isl_surf_get_hiz_surf
.. doxygenfunction:: isl_surf_get_mcs_surf
.. doxygenfunction:: isl_surf_supports_ccs
.. doxygenfunction:: isl_surf_get_ccs_surf
.. c:autofunction:: isl_surf_get_hiz_surf
.. c:autofunction:: isl_surf_get_mcs_surf
.. c:autofunction:: isl_surf_supports_ccs
.. c:autofunction:: isl_surf_get_ccs_surf
Compression state tracking
--------------------------
@@ -76,14 +86,20 @@ given surface.
To help drivers keep track of what all is going on and when resolves need to be
inserted, ISL provides a finite state machine which tracks the current state of
the main surface and auxiliary data and their relationship to each other. The
states are encoded with the :cpp:enum:`isl_aux_state` enum. ISL also provides
states are encoded with the :c:enum:`isl_aux_state` enum. ISL also provides
helper functions for operating the state machine and determining what aux op
(if any) is required to get to the right state for a given operation.
.. doxygenenum:: isl_aux_state
.. doxygenfunction:: isl_aux_state_has_valid_primary
.. doxygenfunction:: isl_aux_state_has_valid_aux
.. doxygenenum:: isl_aux_op
.. doxygenfunction:: isl_aux_prepare_access
.. doxygenfunction:: isl_aux_state_transition_aux_op
.. doxygenfunction:: isl_aux_state_transition_write
.. c:autoenum:: isl_aux_state
.. c:autofunction:: isl_aux_state_has_valid_primary
.. c:autofunction:: isl_aux_state_has_valid_aux
.. c:autoenum:: isl_aux_op
.. c:autofunction:: isl_aux_prepare_access
.. c:autofunction:: isl_aux_state_transition_aux_op
.. c:autofunction:: isl_aux_state_transition_write

14
docs/isl/ccs.rst
View File

@@ -14,9 +14,9 @@ powerful Sky Lake form.
The documentation for Ivy Bridge through Broadwell overloads the term MCS for
referring both to the *multisample control surface* used for multisample
compression and the control surface used for fast-clears. In ISL, the
:cpp:enumerator:`isl_aux_usage::ISL_AUX_USAGE_MCS` enum always refers to
:c:enumerator:`isl_aux_usage.ISL_AUX_USAGE_MCS` enum always refers to
multisample color compression while the
:cpp:enumerator:`isl_aux_usage::ISL_AUX_USAGE_CCS_` enums always refer to
:c:enumerator:`isl_aux_usage.ISL_AUX_USAGE_CCS_` enums always refer to
single-sampled color compression. Throughout this chapter and the rest of the
ISL documentation, we will use the term "color control surface", abbreviated
CCS, to denote the control surface used for both fast-clears and color
@@ -143,10 +143,10 @@ itself. The way ISL does CCS layout calculations is by a very careful and
subtle application of its normal surface layout code.
Above, we described the CCS data layout as mapping of address bits. In
ISL, this is represented by :cpp:enumerator:`isl_tiling::ISL_TILING_CCS`. The
ISL, this is represented by :c:enumerator:`isl_tiling.ISL_TILING_CCS`. The
logical and physical tile dimensions corresponding to the above mapping.
We also have special :cpp:enum:`isl_format` enums for CCS. These formats are 1
We also have special :c:enum:`isl_format` enums for CCS. These formats are 1
bit-per-pixel on Ivy Bridge through Broadwell and 2 bits-per-pixel on Skylake
and above to correspond to the 1 and 2-bit values represented in the CCS data.
They have a block size (similar to a block compressed format such as BC or
@@ -154,10 +154,10 @@ ASTC) which says what area (in surface elements) in the main surface is covered
by a single CCS element (1 or 2-bit). Because this depends on the main surface
tiling and format, we have several different CCS formats.
Once the appropriate :cpp:enum:`isl_format` has been selected, computing the
Once the appropriate :c:enum:`isl_format` has been selected, computing the
size and layout of a CCS surface is as simple as passing the same surface
creation parameters to :cpp:func:`isl_surf_init_s` as were used to create the
primary surface only with :cpp:enumerator:`isl_tiling::ISL_TILING_CCS` and the
creation parameters to :c:func:`isl_surf_init_s` as were used to create the
primary surface only with :c:enumerator:`isl_tiling.ISL_TILING_CCS` and the
correct CCS format. This not only results in a correctly sized surface but
most other ISL helpers for things such as computing offsets into surfaces work
correctly as well.

68
docs/isl/formats.rst
View File

@@ -3,7 +3,7 @@ Surface Formats
A surface format describes the encoding of color information into the actual
data stored in memory. Surface formats in isl are specified via the
:cpp:enum:`isl_format` enum. A complete list of surface formats is included at
:c:enum:`isl_format` enum. A complete list of surface formats is included at
the end of this chapter.
In general, a surface format definition consists of two parts: encoding and
@@ -19,9 +19,11 @@ data is unsigned normalized where the range of an unsigned integer of a
particular size is mapped linearly onto the interval [0, 1]. While normalized
is certainly the most common representation for color data, not all data is
color data, and not all values are nicely bounded. The possible data encodings
are specified by :cpp:enum:`isl_base_type`:
are specified by :c:enum:`isl_base_type`:
.. doxygenenum:: isl_base_type
.. c:autoenum:: isl_base_type
:file: src/intel/isl/isl.h
:members:
Data Layout
-----------
@@ -170,27 +172,27 @@ target.
Surface Format Introspection API
--------------------------------
ISL provides an API for introspecting the :cpp:enum:`isl_format` enum and
ISL provides an API for introspecting the :c:enum:`isl_format` enum and
getting various bits of information about a format. ISL provides helpers for
introspecting both the data layout of an :cpp:enum:`isl_format` and the
introspecting both the data layout of an :c:enum:`isl_format` and the
capabilities of that format for a particular piece of Intel hardware.
Format Layout Introspection
^^^^^^^^^^^^^^^^^^^^^^^^^^^
To get the layout of a given :cpp:enum:`isl_format`, call
:cpp:func:`isl_format_get_layout`:
To get the layout of a given :c:enum:`isl_format`, call
:c:func:`isl_format_get_layout`:
.. doxygenfunction:: isl_format_get_layout
.. c:autofunction:: isl_format_get_layout
.. doxygenstruct:: isl_format_layout
.. c:autostruct:: isl_format_layout
:members:
.. doxygenstruct:: isl_channel_layout
.. c:autostruct:: isl_channel_layout
:members:
There are also quite a few helpers for many of the common cases that allow you
to avoid using :cpp:struct:`isl_format_layout` manually. There are a lot of
to avoid using :c:struct:`isl_format_layout` manually. There are a lot of
them so we won't include a full list here. Look at isl.h for more details.
Hardware Format Support Introspection
@@ -202,27 +204,39 @@ formats. However, for the purposes of code cleanliness, the table is not
exposed directly and, instead, hardware support information is exposed via
a set of helper functions:
.. doxygenfunction:: isl_format_supports_rendering
.. doxygenfunction:: isl_format_supports_alpha_blending
.. doxygenfunction:: isl_format_supports_sampling
.. doxygenfunction:: isl_format_supports_filtering
.. doxygenfunction:: isl_format_supports_vertex_fetch
.. doxygenfunction:: isl_format_supports_typed_writes
.. doxygenfunction:: isl_format_supports_typed_reads
.. doxygenfunction:: isl_format_supports_ccs_d
.. doxygenfunction:: isl_format_supports_ccs_e
.. doxygenfunction:: isl_format_supports_multisampling
.. doxygenfunction:: isl_formats_are_ccs_e_compatible
.. c:autofunction:: isl_format_supports_rendering
.. c:autofunction:: isl_format_supports_alpha_blending
.. c:autofunction:: isl_format_supports_sampling
.. c:autofunction:: isl_format_supports_filtering
.. c:autofunction:: isl_format_supports_vertex_fetch
.. c:autofunction:: isl_format_supports_typed_writes
:file: src/intel/isl/isl_format.c
.. c:autofunction:: isl_format_supports_typed_reads
.. c:autofunction:: isl_format_supports_ccs_d
.. c:autofunction:: isl_format_supports_ccs_e
.. c:autofunction:: isl_format_supports_multisampling
.. c:autofunction:: isl_formats_are_ccs_e_compatible
Surface Format Enums
--------------------
Everything in ISL is done in terms of the :cpp:enum:`isl_format` enum. However,
Everything in ISL is done in terms of the :c:enum:`isl_format` enum. However,
for the sake of interacting with other parts of Mesa, we provide a helper for
converting a :cpp:enum:`pipe_format` to an :cpp:enum:`isl_format`:
converting a :c:enum:`pipe_format` to an :c:enum:`isl_format`:
.. doxygenfunction:: isl_format_for_pipe_format
.. c:autofunction:: isl_format_for_pipe_format
The :cpp:enum:`isl_format` enum is as follows:
The :c:enum:`isl_format` enum is as follows:
.. doxygenenum:: isl_format
.. c:autoenum:: isl_format
:members:

10
docs/isl/hiz.rst
View File

@@ -26,10 +26,10 @@ rendering, things are pretty straightforward: you need one HiZ surface for each
main surface slice. With layered rendering, however, we have to be a bit more
clever because we need a "real" array surface at each LOD. ISL solves this
with a special miptree layout for layered rendering
:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` which lays
:c:enumerator:`isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` which lays
out the surface as a miptree of layered images instead of an array of miptrees.
See the docs for
:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` for a nice
:c:enumerator:`isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` for a nice
description along with an ASCII art diagram of the layout.
Also, neither ``3DSTATE_STENCIL_BUFFER`` nor ``3DSTATE_HIER_DEPTH_BUFFER`` have
@@ -39,16 +39,16 @@ pulled from ``3DSTATE_DEPTH_BUFFER``. When you combine this with the lack of
LOD, this means that, technically, we have a full-sized single-LOD stencil or
HiZ surface at each miplevel of which only the upper left-hand corner of each
array slice ever gets used. The net effect of this is that, in
:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ`, all LODs
:c:enumerator:`isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ`, all LODs
share the same QPitch even though it's horribly wasteful. This is actually
pretty convenient for ISL because we only have the one
:cpp:member:`isl_surf::array_pitch_el_rows` field.
:c:member:`isl_surf.array_pitch_el_rows` field.
Due to difficulties with plumbing relocation deltas through ISL's
depth/stencil/hiz emit interface, we can't handle this all automatically in
ISL. Instead, it's left up to the driver to do this offsetting. ISL does
provide helpers for computing the offsets and they work fine with
:cpp:enumerator:`isl_dim_layout::ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` so all that's
:c:enumerator:`isl_dim_layout.ISL_DIM_LAYOUT_GFX6_STENCIL_HIZ` so all that's
really required is to call the ISL helper and add the computed offset to the
HiZ or stencil buffer address. The following is an excerpt from BLORP where we
do this as an example:

5
docs/isl/index.rst
View File

@@ -16,7 +16,8 @@ Chery.
ccs
hiz
The core representation of a surface in ISL is :cpp:struct:`isl_surf`.
The core representation of a surface in ISL is :c:struct:`isl_surf`.
.. doxygenstruct:: isl_surf
.. c:autostruct:: isl_surf
:file: src/intel/isl/isl.h
:members:

27
docs/isl/tiling.rst
View File

@@ -73,13 +73,16 @@ ISL Representation
------------------
The structure of any given tiling format is represented by ISL using the
:cpp:enum:`isl_tiling` enum and the :cpp:struct:`isl_tile_info` structure:
:c:enum:`isl_tiling` enum and the :c:struct:`isl_tile_info` structure:
.. doxygenenum:: isl_tiling
.. c:autoenum:: isl_tiling
:file: src/intel/isl/isl.h
:members:
.. doxygenfunction:: isl_tiling_get_info
.. c:autofunction:: isl_tiling_get_info
:file: src/intel/isl/isl.c
.. doxygenstruct:: isl_tile_info
.. c:autostruct:: isl_tile_info
:members:
The ``isl_tile_info`` structure has two different sizes for a tile: a logical
@@ -97,11 +100,11 @@ image in bytes given a width and height in elements is as follows:
uint32_t size = height_tl * tile_info.phys_extent_el.h * row_pitch;
It is very important to note that there is no direct conversion between
:cpp:member:`isl_tile_info::logical_extent_el` and
:cpp:member:`isl_tile_info::phys_extent_B`. It is tempting to assume that the
:c:member:`isl_tile_info.logical_extent_el` and
:c:member:`isl_tile_info.phys_extent_B`. It is tempting to assume that the
logical and physical heights are the same and simply divide the width of
:cpp:member:`isl_tile_info::phys_extent_B` by the size of the format (which is
what the PRM does) to get :cpp:member:`isl_tile_info::logical_extent_el` but
:c:member:`isl_tile_info.phys_extent_B` by the size of the format (which is
what the PRM does) to get :c:member:`isl_tile_info.logical_extent_el` but
this is not at all correct. Some tiling formats have logical and physical
heights that differ and so no such calculation will work in general. The
easiest case study for this is W-tiling. From the Sky Lake PRM Vol. 2d,
@@ -302,10 +305,10 @@ the tile are given by the table below:
=========================================== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== ===========
Tiling 11 10 9 8 7 6 5 4 3 2 1 0
=========================================== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== ===========
:cpp:enumerator:`isl_tiling::ISL_TILING_X` :math:`v_2` :math:`v_1` :math:`v_0` :math:`u_8` :math:`u_7` :math:`u_6` :math:`u_5` :math:`u_4` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
:cpp:enumerator:`isl_tiling::ISL_TILING_Y0` :math:`u_6` :math:`u_5` :math:`u_4` :math:`v_4` :math:`v_3` :math:`v_2` :math:`v_1` :math:`v_0` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
:cpp:enumerator:`isl_tiling::ISL_TILING_W` :math:`u_5` :math:`u_4` :math:`u_3` :math:`v_5` :math:`v_4` :math:`v_3` :math:`v_2` :math:`u_2` :math:`v_1` :math:`u_1` :math:`v_0` :math:`u_0`
:cpp:enumerator:`isl_tiling::ISL_TILING_4` :math:`v_4` :math:`v_3` :math:`u_6` :math:`v_2` :math:`u_5` :math:`u_4` :math:`v_1` :math:`v_0` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
:c:enumerator:`isl_tiling.ISL_TILING_X` :math:`v_2` :math:`v_1` :math:`v_0` :math:`u_8` :math:`u_7` :math:`u_6` :math:`u_5` :math:`u_4` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
:c:enumerator:`isl_tiling.ISL_TILING_Y0` :math:`u_6` :math:`u_5` :math:`u_4` :math:`v_4` :math:`v_3` :math:`v_2` :math:`v_1` :math:`v_0` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
:c:enumerator:`isl_tiling.ISL_TILING_W` :math:`u_5` :math:`u_4` :math:`u_3` :math:`v_5` :math:`v_4` :math:`v_3` :math:`v_2` :math:`u_2` :math:`v_1` :math:`u_1` :math:`v_0` :math:`u_0`
:c:enumerator:`isl_tiling.ISL_TILING_4` :math:`v_4` :math:`v_3` :math:`u_6` :math:`v_2` :math:`u_5` :math:`u_4` :math:`v_1` :math:`v_0` :math:`u_3` :math:`u_2` :math:`u_1` :math:`u_0`
=========================================== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== =========== ===========
Constructing the mapping this way makes a lot of sense when you think about

18
docs/isl/units.rst
View File

@@ -30,10 +30,10 @@ rows of samples. For block-compressed images, this meant it had to be
a multiple of the block height. On Skylake, it changed to always being in rows
of elements so you have to divide the pitch in samples by the compression
block height. Since the old surface state code tries to store things in
hardware units, everyone who ever reads :cpp:expr:`brw_mipmap_tree::qpitch` has
hardware units, everyone who ever reads :c:expr:`brw_mipmap_tree.qpitch` has
to change their interpretation based on hardware generation and whether or not
the surface was block-compressed. In ISL, we have
:cpp:member:`isl_surf::array_pitch_el_rows` which, as the name says, is in rows
:c:member:`isl_surf.array_pitch_el_rows` which, as the name says, is in rows
of elements. On Broadwell and earlier, we have to multiply by the block size
of the texture when we finally fill out the hardware packet. However, the
consistency of always being in rows of elements makes any other users of the
@@ -49,16 +49,16 @@ implicitly in terms of pixels because this is what all of the APIs use.
The next unit in ISL's repertoire is **samples**. In a multisampled surface,
each pixel corresponds to some number of samples given by
:cpp:member:`isl_surf::samples`. The exact layout of the samples depends on
the value of :cpp:member:`isl_surf::msaa_layout`. If the layout is
:cpp:enumerator:`ISL_MSAA_LAYOUT_ARRAY` then each logical array in the surface
corresponds to :cpp:member:`isl_surf::samples` actual slices
:c:member:`isl_surf.samples`. The exact layout of the samples depends on
the value of :c:member:`isl_surf.msaa_layout`. If the layout is
:c:enumerator:`ISL_MSAA_LAYOUT_ARRAY` then each logical array in the surface
corresponds to :c:member:`isl_surf.samples` actual slices
in the resulting surface, one per array slice. If the layout is
:cpp:enumerator:`ISL_MSAA_LAYOUT_INTERLEAVED` then each pixel corresponds to a
:c:enumerator:`ISL_MSAA_LAYOUT_INTERLEAVED` then each pixel corresponds to a
2x1, 2x2, 4x2, or 4x4 grid of samples. In order to aid in calculations, one of
the first things ISL does is to compute :cpp:member:`isl_surf::phys_level0_sa`
the first things ISL does is to compute :c:member:`isl_surf.phys_level0_sa`
which gives the dimensions of the base miplevel of the surface in samples. The
type of :cpp:member:`isl_surf::phys_level0_sa` is :cpp:struct:`isl_extent4d`
type of :c:member:`isl_surf.phys_level0_sa` is :c:struct:`isl_extent4d`
which allows us to express both the array and interleaved cases. Most of the
calculations of how the different miplevels and array slices are laid out is
done in terms of samples.

14
src/intel/isl/isl.c
View File

@@ -617,13 +617,13 @@ tiling_max_mip_tail(enum isl_tiling tiling,
* Returns an isl_tile_info representation of the given isl_tiling when
* combined when used in the given configuration.
*
* @param[in] tiling The tiling format to introspect
* @param[in] dim The dimensionality of the surface being tiled
* @param[in] msaa_layout The layout of samples in the surface being tiled
* @param[in] format_bpb The number of bits per surface element (block) for
* the surface being tiled
* @param[in] samples The samples in the surface being tiled
* @param[out] tile_info Return parameter for the tiling information
* :param tiling: |in| The tiling format to introspect
* :param dim: |in| The dimensionality of the surface being tiled
* :param msaa_layout: |in| The layout of samples in the surface being tiled
* :param format_bpb: |in| The number of bits per surface element (block) for
* the surface being tiled
* :param samples: |in| The samples in the surface being tiled
* :param tile_info: |out| Return parameter for the tiling information
*/
void
isl_tiling_get_info(enum isl_tiling tiling,

316
src/intel/isl/isl.h
View File

@@ -56,7 +56,7 @@ struct brw_image_param;
#ifndef ISL_GFX_VER
/**
* @brief Get the hardware generation of isl_device.
* Get the hardware generation of isl_device.
*
* You can define this as a compile-time constant in the CFLAGS. For example,
* `gcc -DISL_GFX_VER(dev)=9 ...`.
@@ -427,7 +427,7 @@ enum ENUM_PACKED isl_base_type {
*
* Though stored as an integer, the data is interpreted as a floating-point
* number in the range [0, 1] where the conversion from the in-memory
* representation to float is given by \f$\frac{x}{2^{bits} - 1}\f$.
* representation to float is given by :math:`\frac{x}{2^{bits} - 1}`.
*/
ISL_UNORM,
@@ -437,7 +437,7 @@ enum ENUM_PACKED isl_base_type {
* Though stored as an integer, the data is interpreted as a floating-point
* number in the range [-1, 1] where the conversion from the in-memory
* representation to float is given by
* \f$max\left(\frac{x}{2^{bits - 1} - 1}, -1\right)\f$.
* :math:`max\left(\frac{x}{2^{bits - 1} - 1}, -1\right)`.
*/
ISL_SNORM,
@@ -451,14 +451,12 @@ enum ENUM_PACKED isl_base_type {
* the mantissa. The available bit sizes for unsigned floats are as
* follows:
*
* \rst
* ===== ========= =========
* Bits Mantissa Exponent
* ===== ========= =========
* 11 6 5
* 10 5 5
* ===== ========= =========
* \endrst
*
* In particular, both unsigned floating-point formats are identical to
* IEEE float16 except that the sign bit and the bottom mantissa bits are
@@ -471,7 +469,6 @@ enum ENUM_PACKED isl_base_type {
* Signed floating-point data is represented as standard IEEE floats with
* the usual number of mantissa and exponent bits
*
* \rst
* ===== ========= =========
* Bits Mantissa Exponent
* ===== ========= =========
@@ -479,7 +476,6 @@ enum ENUM_PACKED isl_base_type {
* 32 23 8
* 16 10 5
* ===== ========= =========
* \endrst
*/
ISL_SFLOAT,
@@ -667,7 +663,7 @@ enum isl_dim_layout {
* For details, see the G35 PRM >> Volume 1: Graphics Core >> Section
* 6.17.5: 3D Surfaces.
*
* @invariant isl_surf::phys_level0_sa::array_len == 1
* :invariant: isl_surf::phys_level0_sa::array_len == 1
*/
ISL_DIM_LAYOUT_GFX4_3D,
@@ -755,7 +751,7 @@ enum isl_aux_usage {
* the clear color. Exact details about the data stored in the MCS and how
* it maps samples to slices is documented in the PRMs.
*
* @invariant isl_surf::samples > 1
* :invariant: :c:member:`isl_surf.samples` > 1
*/
ISL_AUX_USAGE_MCS,
@@ -768,8 +764,8 @@ enum isl_aux_usage {
* On Skylake, this is increased to two bits per cache line pair with 0x0
* meaning resolved and 0x3 meaning clear.
*
* @invariant The surface is a color surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a color surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_CCS_D,
@@ -794,8 +790,8 @@ enum isl_aux_usage {
* Starting with Tigerlake, each CCS value is 4 bits per cache line pair in
* the main surface.
*
* @invariant The surface is a color surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a color surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_CCS_E,
@@ -807,8 +803,8 @@ enum isl_aux_usage {
* the feature is easier to find. In the 3DSTATE_3D_MODE packet, it is
* referred to as "Fast Clear Optimization (FCV)".
*
* @invariant The surface is a color surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a color surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_FCV_CCS_E,
@@ -819,8 +815,8 @@ enum isl_aux_usage {
* consume it in order to get end-to-end compression when the image comes
* from media decode.
*
* @invariant The surface is a color surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a color surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_MC,
@@ -833,8 +829,8 @@ enum isl_aux_usage {
* accelerating depth testing and not for actual compression. The
* CCS-compressed surface contains valid data at all times.
*
* @invariant The surface is a color surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a color surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_HIZ_CCS_WT,
@@ -848,7 +844,7 @@ enum isl_aux_usage {
* depth hardware is to do a full resolve which resolves both HiZ and CCS
* so the surface is in the pass-through state.
*
* @invariant The surface is a depth surface
* :invariant: The surface is a depth surface
*/
ISL_AUX_USAGE_HIZ_CCS,
@@ -858,8 +854,8 @@ enum isl_aux_usage {
* where the MCS is used for fast-clears and "identical samples"
* compression just like on Gfx7-11 but each plane is then CCS compressed.
*
* @invariant The surface is a depth surface
* @invariant isl_surf::samples > 1
* :invariant: The surface is a depth surface
* :invariant: :c:member:`isl_surf.samples` > 1
*/
ISL_AUX_USAGE_MCS_CCS,
@@ -868,8 +864,8 @@ enum isl_aux_usage {
* Introduced on Tigerlake, this is similar to CCS_E only used to compress
* stencil surfaces.
*
* @invariant The surface is a stencil surface
* @invariant isl_surf::samples == 1
* :invariant: The surface is a stencil surface
* :invariant: :c:member:`isl_surf.samples` == 1
*/
ISL_AUX_USAGE_STC_CCS,
};
@@ -888,6 +884,8 @@ enum isl_aux_usage {
* contains a complete description of the states and all valid and useful
* transitions except clear.
*
* ::
*
* Draw w/ Aux
* +----------+
* | |
@@ -966,12 +964,14 @@ enum isl_aux_usage {
* provides fast clear and partial resolve operations which work as described
* above.
*
* @note
* The state machine above isn't quite correct for CCS on TGL. There is a HW
* bug (or feature, depending on who you ask) which can cause blocks to enter
* the fast-clear state as a side-effect of a regular draw call. This means
* that a draw in the resolved or compressed without clear states takes you to
* the compressed with clear state, not the compressed without clear state.
* .. note::
*
* The state machine above isn't quite correct for CCS on TGL. There is a
* HW bug (or feature, depending on who you ask) which can cause blocks to
* enter the fast-clear state as a side-effect of a regular draw call. This
* means that a draw in the resolved or compressed without clear states
* takes you to the compressed with clear state, not the compressed without
* clear state.
*/
enum isl_aux_state {
#ifdef IN_UNIT_TEST
@@ -1385,9 +1385,9 @@ struct isl_channel_layout {
*
* Each format has 3D block extent (width, height, depth). The block extent of
* compressed formats is that of the format's compression block. For example,
* the block extent of `ISL_FORMAT_ETC2_RGB8` is `(w=4, h=4, d=1)`. The block
* extent of uncompressed pixel formats, such as `ISL_FORMAT_R8G8B8A8_UNORM`,
* is `(w=1, h=1, d=1)`.
* the block extent of ``ISL_FORMAT_ETC2_RGB8`` is ``(w=4, h=4, d=1)``. The block
* extent of uncompressed pixel formats, such as ``ISL_FORMAT_R8G8B8A8_UNORM``,
* is ``(w=1, h=1, d=1)``.
*/
struct isl_format_layout {
/** Format */
@@ -1402,7 +1402,9 @@ struct isl_format_layout {
/** Block depth, in pixels */
uint8_t bd;
/***/
union {
/***/
struct {
/** Red channel */
struct isl_channel_layout r;
@@ -1429,6 +1431,7 @@ struct isl_format_layout {
enum isl_txc txc;
};
/***/
struct isl_tile_info {
/** Tiling represented by this isl_tile_info */
enum isl_tiling tiling;
@@ -1446,10 +1449,10 @@ struct isl_tile_info {
* surface elements so isl_tiling_get_info returns an isl_tile_info for a
* 32-bit element size. It is the responsibility of the caller to
* recognize that 32 != 96 ad adjust accordingly. For instance, to compute
* the width of a surface in tiles, you would do:
* the width of a surface in tiles, you would do::
*
* width_tl = DIV_ROUND_UP(width_el * (format_bpb / tile_info.format_bpb),
* tile_info.logical_extent_el.width);
* width_tl = DIV_ROUND_UP(width_el * (format_bpb / tile_info.format_bpb),
* tile_info.logical_extent_el.width);
*/
uint32_t format_bpb;
@@ -1481,7 +1484,7 @@ struct isl_tile_info {
* always used with ISL_FORMAT_R8) has a logical size of 64el x 64el but
* its physical size is 128B x 32rows, the same as a Y-tile.
*
* @see isl_surf::row_pitch_B
* See :c:member:`isl_surf.row_pitch_B`
*/
struct isl_extent2d phys_extent_B;
};
@@ -1509,16 +1512,16 @@ struct isl_drm_modifier_info {
/**
* @brief Input to surface initialization
*
* @invariant width >= 1
* @invariant height >= 1
* @invariant depth >= 1
* @invariant levels >= 1
* @invariant samples >= 1
* @invariant array_len >= 1
* :invariant: width >= 1
* :invariant: height >= 1
* :invariant: depth >= 1
* :invariant: levels >= 1
* :invariant: samples >= 1
* :invariant: array_len >= 1
*
* @invariant if 1D then height == 1 and depth == 1 and samples == 1
* @invariant if 2D then depth == 1
* @invariant if 3D then array_len == 1 and samples == 1
* :invariant: if 1D then height == 1 and depth == 1 and samples == 1
* :invariant: if 2D then depth == 1
* :invariant: if 3D then array_len == 1 and samples == 1
*/
struct isl_surf_init_info {
enum isl_surf_dim dim;
@@ -1531,15 +1534,15 @@ struct isl_surf_init_info {
uint32_t array_len;
uint32_t samples;
/** Lower bound for isl_surf::alignment, in bytes. */
/** Lower bound for :c:member:`isl_surf.alignment`, in bytes. */
uint32_t min_alignment_B;
/** Lower bound for where to start the miptail */
uint32_t min_miptail_start_level;
/**
* Exact value for isl_surf::row_pitch. Ignored if zero. isl_surf_init()
* will fail if this is misaligned or out of bounds.
* Exact value for :c:member:`isl_surf.row_pitch`. Ignored if zero.
* isl_surf_init() will fail if this is misaligned or out of bounds.
*/
uint32_t row_pitch_B;
@@ -1549,6 +1552,7 @@ struct isl_surf_init_info {
isl_tiling_flags_t tiling_flags;
};
/***/
struct isl_surf {
/** Dimensionality of the surface */
enum isl_surf_dim dim;
@@ -1556,7 +1560,7 @@ struct isl_surf {
/**
* Spatial layout of the surface in memory
*
* This is dependent on isl_surf::dim and hardware generation.
* This is dependent on :c:member:`isl_surf.dim` and hardware generation.
*/
enum isl_dim_layout dim_layout;
@@ -1605,7 +1609,7 @@ struct isl_surf {
/**
* Number of samples in the surface
*
* @invariant samples >= 1
* :invariant: samples >= 1
*/
uint32_t samples;
@@ -1926,7 +1930,7 @@ isl_sample_count_mask_t ATTRIBUTE_CONST
isl_device_get_sample_counts(struct isl_device *dev);
/**
* \return The isl_format_layout for the given isl_format
* :returns: The isl_format_layout for the given isl_format
*/
static inline const struct isl_format_layout * ATTRIBUTE_CONST
isl_format_get_layout(enum isl_format fmt)
@@ -1952,18 +1956,25 @@ isl_format_get_short_name(enum isl_format fmt)
return isl_format_get_name(fmt) + 11 /* ISL_FORMAT_ */;
}
/***/
enum isl_format isl_format_for_pipe_format(enum pipe_format pf);
/***/
bool isl_format_supports_rendering(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_alpha_blending(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_sampling(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_filtering(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_vertex_fetch(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_typed_writes(const struct intel_device_info *devinfo,
enum isl_format format);
bool isl_format_supports_typed_reads(const struct intel_device_info *devinfo,
@@ -1972,6 +1983,7 @@ bool isl_format_supports_ccs_d(const struct intel_device_info *devinfo,
enum isl_format format);
bool isl_format_supports_ccs_e(const struct intel_device_info *devinfo,
enum isl_format format);
/***/
bool isl_format_supports_multisampling(const struct intel_device_info *devinfo,
enum isl_format format);
bool isl_format_supports_typed_atomics(const struct intel_device_info *devinfo,
@@ -2203,15 +2215,15 @@ isl_tiling_from_i915_tiling(uint32_t tiling);
* Return an isl_aux_op needed to enable an access to occur in an
* isl_aux_state suitable for the isl_aux_usage.
*
* @note
* If the access will invalidate the main surface, this function should not be
* called and the isl_aux_op of NONE should be used instead. Otherwise, an
* extra (but still lossless) ambiguate may occur.
* .. note::
* If the access will invalidate the main surface, this function should not be
* called and the isl_aux_op of NONE should be used instead. Otherwise, an
* extra (but still lossless) ambiguate may occur.
*
* @invariant initial_state is possible with an isl_aux_usage compatible with
* the given usage. Two usages are compatible if it's possible to
* switch between them (e.g. CCS_E <-> CCS_D).
* @invariant fast_clear is false if the aux doesn't support fast clears.
* :invariant: initial_state is possible with an isl_aux_usage compatible with
* the given usage. Two usages are compatible if it's possible to
* switch between them (e.g. CCS_E <-> CCS_D).
* :invariant: fast_clear is false if the aux doesn't support fast clears.
*/
enum isl_aux_op
isl_aux_prepare_access(enum isl_aux_state initial_state,
@@ -2221,9 +2233,9 @@ isl_aux_prepare_access(enum isl_aux_state initial_state,
/**
* Return the isl_aux_state entered after performing an isl_aux_op.
*
* @invariant initial_state is possible with the given usage.
* @invariant op is possible with the given usage.
* @invariant op must not cause HW to read from an invalid aux.
* :invariant: initial_state is possible with the given usage.
* :invariant: op is possible with the given usage.
* :invariant: op must not cause HW to read from an invalid aux.
*/
enum isl_aux_state
isl_aux_state_transition_aux_op(enum isl_aux_state initial_state,
@@ -2233,14 +2245,15 @@ isl_aux_state_transition_aux_op(enum isl_aux_state initial_state,
/**
* Return the isl_aux_state entered after performing a write.
*
* @note
* full_surface should be true if the write covers the entire slice. Setting
* it to false in this case will still result in a correct (but imprecise) aux
* state.
* .. note::
*
* @invariant if usage is not ISL_AUX_USAGE_NONE, then initial_state is
* full_surface should be true if the write covers the entire slice. Setting
* it to false in this case will still result in a correct (but imprecise)
* aux state.
*
* :invariant: if usage is not ISL_AUX_USAGE_NONE, then initial_state is
* possible with the given usage.
* @invariant usage can be ISL_AUX_USAGE_NONE iff:
* :invariant: usage can be ISL_AUX_USAGE_NONE iff:
* * the main surface is valid, or
* * the main surface is being invalidated/replaced.
*/
@@ -2249,12 +2262,15 @@ isl_aux_state_transition_write(enum isl_aux_state initial_state,
enum isl_aux_usage usage,
bool full_surface);
/***/
bool
isl_aux_usage_has_fast_clears(enum isl_aux_usage usage);
/***/
bool
isl_aux_usage_has_compression(enum isl_aux_usage usage);
/***/
static inline bool
isl_aux_usage_has_hiz(enum isl_aux_usage usage)
{
@@ -2263,6 +2279,7 @@ isl_aux_usage_has_hiz(enum isl_aux_usage usage)
usage == ISL_AUX_USAGE_HIZ_CCS;
}
/***/
static inline bool
isl_aux_usage_has_mcs(enum isl_aux_usage usage)
{
@@ -2270,6 +2287,7 @@ isl_aux_usage_has_mcs(enum isl_aux_usage usage)
usage == ISL_AUX_USAGE_MCS_CCS;
}
/***/
static inline bool
isl_aux_usage_has_ccs(enum isl_aux_usage usage)
{
@@ -2290,6 +2308,7 @@ isl_aux_usage_has_ccs_e(enum isl_aux_usage usage)
usage == ISL_AUX_USAGE_FCV_CCS_E;
}
/***/
static inline bool
isl_aux_state_has_valid_primary(enum isl_aux_state state)
{
@@ -2298,6 +2317,7 @@ isl_aux_state_has_valid_primary(enum isl_aux_state state)
state == ISL_AUX_STATE_AUX_INVALID;
}
/***/
static inline bool
isl_aux_state_has_valid_aux(enum isl_aux_state state)
{
@@ -2527,10 +2547,10 @@ isl_surf_get_tile_info(const struct isl_surf *surf,
struct isl_tile_info *tile_info);
/**
* @param[in] surf The main surface
* @param[in] hiz_or_mcs_surf HiZ or MCS surface associated with the main
* surface
* @returns true if the given surface supports CCS.
* :param surf: |in| The main surface
* :param hiz_or_mcs_surf: |in| HiZ or MCS surface associated with the main
* surface
* :returns: true if the given surface supports CCS.
*/
bool
isl_surf_supports_ccs(const struct isl_device *dev,
@@ -2539,9 +2559,9 @@ isl_surf_supports_ccs(const struct isl_device *dev,
/** Constructs a HiZ surface for the given main surface.
*
* @param[in] surf The main surface
* @param[out] hiz_surf The HiZ surface to populate on success
* @returns false if the main surface cannot support HiZ.
* :param surf: |in| The main surface
* :param hiz_surf: |out| The HiZ surface to populate on success
* :returns: false if the main surface cannot support HiZ.
*/
bool
isl_surf_get_hiz_surf(const struct isl_device *dev,
@@ -2550,9 +2570,9 @@ isl_surf_get_hiz_surf(const struct isl_device *dev,
/** Constructs a MCS for the given main surface.
*
* @param[in] surf The main surface
* @param[out] mcs_surf The MCS to populate on success
* @returns false if the main surface cannot support MCS.
* :param surf: |in| The main surface
* :param mcs_surf: |out| The MCS to populate on success
* :returns: false if the main surface cannot support MCS.
*/
bool
isl_surf_get_mcs_surf(const struct isl_device *dev,
@@ -2561,27 +2581,27 @@ isl_surf_get_mcs_surf(const struct isl_device *dev,
/** Constructs a CCS for the given main surface.
*
* @note
* Starting with Tigerlake, the CCS is no longer really a surface. It's not
* laid out as an independent surface and isn't referenced by
* RENDER_SURFACE_STATE::"Auxiliary Surface Base Address" like other auxiliary
* compression surfaces. It's a blob of memory that's a 1:256 scale-down from
* the main surfaced that's attached side-band via a second set of page
* tables.
* .. note::
*
* Starting with Tigerlake, the CCS is no longer really a surface. It's not
* laid out as an independent surface and isn't referenced by
* RENDER_SURFACE_STATE::"Auxiliary Surface Base Address" like other
* auxiliary compression surfaces. It's a blob of memory that's a 1:256
* scale-down from the main surfaced that's attached side-band via a second
* set of page tables.
*
* @par
* In spite of this, it's sometimes useful to think of it as being a linear
* buffer-like surface, at least for the purposes of allocation. When invoked
* on Tigerlake or later, this function still works and produces such a linear
* surface.
*
* @param[in] surf The main surface
* @param[in] hiz_or_mcs_surf HiZ or MCS surface associated with the main
* surface
* @param[out] ccs_surf The CCS to populate on success
* @param row_pitch_B: The row pitch for the CCS in bytes or 0 if
* ISL should calculate the row pitch.
* @returns false if the main surface cannot support CCS.
* :param surf: |in| The main surface
* :param hiz_or_mcs_surf: |in| HiZ or MCS surface associated with the main
* surface
* :param ccs_surf: |out| The CCS to populate on success
* :param row_pitch_B: The row pitch for the CCS in bytes or 0 if
* ISL should calculate the row pitch.
* :returns: false if the main surface cannot support CCS.
*/
bool
isl_surf_get_ccs_surf(const struct isl_device *dev,
@@ -2748,9 +2768,9 @@ isl_surf_get_array_pitch(const struct isl_surf *surf)
* Calculate the offset, in units of surface samples, to a subimage in the
* surface.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_offset_sa(const struct isl_surf *surf,
@@ -2766,9 +2786,9 @@ isl_surf_get_image_offset_sa(const struct isl_surf *surf,
* Calculate the offset, in units of surface elements, to a subimage in the
* surface.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_offset_el(const struct isl_surf *surf,
@@ -2788,9 +2808,9 @@ isl_surf_get_image_offset_el(const struct isl_surf *surf,
* result to isl_tiling_get_intratile_offset_el, and converting the tile
* offsets to samples.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_offset_B_tile_sa(const struct isl_surf *surf,
@@ -2808,9 +2828,9 @@ isl_surf_get_image_offset_B_tile_sa(const struct isl_surf *surf,
* This is equivalent to calling isl_surf_get_image_offset_el, passing the
* result to isl_tiling_get_intratile_offset_el.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_offset_B_tile_el(const struct isl_surf *surf,
@@ -2830,9 +2850,9 @@ isl_surf_get_image_offset_B_tile_el(const struct isl_surf *surf,
* from other sub-images. The returned range is a half-open interval where
* all of the addresses within the subimage are < end_tile_B.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_range_B_tile(const struct isl_surf *surf,
@@ -2850,9 +2870,9 @@ isl_surf_get_image_range_B_tile(const struct isl_surf *surf,
*
* It is safe to call this function with surf == image_surf.
*
* @invariant level < surface levels
* @invariant logical_array_layer < logical array length of surface
* @invariant logical_z_offset_px < logical depth of surface at level
* :invariant: level < surface levels
* :invariant: logical_array_layer < logical array length of surface
* :invariant: logical_z_offset_px < logical depth of surface at level
*/
void
isl_surf_get_image_surf(const struct isl_device *dev,
@@ -2902,20 +2922,20 @@ isl_surf_get_uncompressed_surf(const struct isl_device *dev,
* given coordinate in tile space. The returned x/y/z/array offsets are
* guaranteed to lie within the tile.
*
* @param[in] tiling The tiling of the surface
* @param[in] bpb The size of the surface format in bits per
* block
* @param[in] array_pitch_el_rows The array pitch of the surface for flat 2D
* tilings such as ISL_TILING_Y0
* @param[in] total_x_offset_el The X offset in tile space, in elements
* @param[in] total_y_offset_el The Y offset in tile space, in elements
* @param[in] total_z_offset_el The Z offset in tile space, in elements
* @param[in] total_array_offset The array offset in tile space
* @param[out] tile_offset_B The returned byte offset to the tile
* @param[out] x_offset_el The X offset within the tile, in elements
* @param[out] y_offset_el The Y offset within the tile, in elements
* @param[out] z_offset_el The Z offset within the tile, in elements
* @param[out] array_offset The array offset within the tile
* :param tiling: |in| The tiling of the surface
* :param bpb: |in| The size of the surface format in bits per
* block
* :param array_pitch_el_rows: |in| The array pitch of the surface for flat 2D
* tilings such as ISL_TILING_Y0
* :param total_x_offset_el: |in| The X offset in tile space, in elements
* :param total_y_offset_el: |in| The Y offset in tile space, in elements
* :param total_z_offset_el: |in| The Z offset in tile space, in elements
* :param total_array_offset: |in| The array offset in tile space
* :param tile_offset_B: |out| The returned byte offset to the tile
* :param x_offset_el: |out| The X offset within the tile, in elements
* :param y_offset_el: |out| The Y offset within the tile, in elements
* :param z_offset_el: |out| The Z offset within the tile, in elements
* :param array_offset: |out| The array offset within the tile
*/
void
isl_tiling_get_intratile_offset_el(enum isl_tiling tiling,
@@ -2943,20 +2963,20 @@ isl_tiling_get_intratile_offset_el(enum isl_tiling tiling,
* given coordinate in tile space. The returned x/y/z/array offsets are
* guaranteed to lie within the tile.
*
* @param[in] tiling The tiling of the surface
* @param[in] bpb The size of the surface format in bits per
* block
* @param[in] array_pitch_el_rows The array pitch of the surface for flat 2D
* tilings such as ISL_TILING_Y0
* @param[in] total_x_offset_sa The X offset in tile space, in samples
* @param[in] total_y_offset_sa The Y offset in tile space, in samples
* @param[in] total_z_offset_sa The Z offset in tile space, in samples
* @param[in] total_array_offset The array offset in tile space
* @param[out] tile_offset_B The returned byte offset to the tile
* @param[out] x_offset_sa The X offset within the tile, in samples
* @param[out] y_offset_sa The Y offset within the tile, in samples
* @param[out] z_offset_sa The Z offset within the tile, in samples
* @param[out] array_offset The array offset within the tile
* :param tiling: |in| The tiling of the surface
* :param bpb: |in| The size of the surface format in bits per
* block
* :param array_pitch_el_rows: |in| The array pitch of the surface for flat 2D
* tilings such as ISL_TILING_Y0
* :param total_x_offset_sa: |in| The X offset in tile space, in samples
* :param total_y_offset_sa: |in| The Y offset in tile space, in samples
* :param total_z_offset_sa: |in| The Z offset in tile space, in samples
* :param total_array_offset: |in| The array offset in tile space
* :param tile_offset_B: |out| The returned byte offset to the tile
* :param x_offset_sa: |out| The X offset within the tile, in samples
* :param y_offset_sa: |out| The Y offset within the tile, in samples
* :param z_offset_sa: |out| The Z offset within the tile, in samples
* :param array_offset: |out| The array offset within the tile
*/
static inline void
isl_tiling_get_intratile_offset_sa(enum isl_tiling tiling,
@@ -3005,7 +3025,7 @@ isl_tiling_get_intratile_offset_sa(enum isl_tiling tiling,
}
/**
* @brief Get value of 3DSTATE_DEPTH_BUFFER.SurfaceFormat
* Get value of 3DSTATE_DEPTH_BUFFER.SurfaceFormat
*
* @pre surf->usage has ISL_SURF_USAGE_DEPTH_BIT
* @pre surf->format must be a valid format for depth surfaces
@@ -3015,8 +3035,7 @@ isl_surf_get_depth_format(const struct isl_device *dev,
const struct isl_surf *surf);
/**
* @brief performs a copy from linear to tiled surface
*
* Performs a copy from linear to tiled surface
*/
void
isl_memcpy_linear_to_tiled(uint32_t xt1, uint32_t xt2,
@@ -3028,8 +3047,7 @@ isl_memcpy_linear_to_tiled(uint32_t xt1, uint32_t xt2,
isl_memcpy_type copy_type);
/**
* @brief performs a copy from tiled to linear surface
*
* Performs a copy from tiled to linear surface
*/
void
isl_memcpy_tiled_to_linear(uint32_t xt1, uint32_t xt2,
@@ -3041,7 +3059,7 @@ isl_memcpy_tiled_to_linear(uint32_t xt1, uint32_t xt2,
isl_memcpy_type copy_type);
/**
* @brief computes the tile_w (in bytes) and tile_h (in rows) of
* Computes the tile_w (in bytes) and tile_h (in rows) of
* different tiling patterns.
*/
static inline void
@@ -3067,9 +3085,9 @@ isl_get_tile_dims(enum isl_tiling tiling, uint32_t cpp,
}
/**
* @brief Computes masks that may be used to select the bits of the X
* and Y coordinates that indicate the offset within a tile. If the BO is
* untiled, the masks are set to 0.
* Computes masks that may be used to select the bits of the X and Y
* coordinates that indicate the offset within a tile. If the BO is untiled,
* the masks are set to 0.
*/
static inline void
isl_get_tile_masks(enum isl_tiling tiling, uint32_t cpp,