summaryrefslogtreecommitdiffstats
path: root/src/gallium/include
Commit message (Collapse)AuthorAgeFilesLines
* gallium: remove PIPE_CAP_MAX_COMBINED_SAMPLERSMarek Olšák2014-02-041-3/+0
| | | | | | | This can be derived from the shader caps. All GPUs from ATI/AMD, NVIDIA, and INTEL have separate texture slots for each shader stage.
* gallium: remove PIPE_CAP_SCALED_RESOLVEMarek Olšák2014-01-231-1/+0
| | | | | | | If any driver doesn't support this, it can use a blit after resolving the samples. Reviewed-by: Brian Paul <[email protected]>
* s/Tungsten Graphics/VMware/José Fonseca2014-01-1712-21/+21
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Tungsten Graphics Inc. was acquired by VMware Inc. in 2008. Leaving the old copyright name is creating unnecessary confusion, hence this change. This was the sed script I used: $ cat tg2vmw.sed # Run as: # # git reset --hard HEAD && find include scons src -type f -not -name 'sed*' -print0 | xargs -0 sed -i -f tg2vmw.sed # # Rename copyrights s/Tungsten Gra\(ph\|hp\)ics,\? [iI]nc\.\?\(, Cedar Park\)\?\(, Austin\)\?\(, \(Texas\|TX\)\)\?\.\?/VMware, Inc./g /Copyright/s/Tungsten Graphics\(,\? [iI]nc\.\)\?\(, Cedar Park\)\?\(, Austin\)\?\(, \(Texas\|TX\)\)\?\.\?/VMware, Inc./ s/TUNGSTEN GRAPHICS/VMWARE/g # Rename emails s/[email protected]/[email protected]/ s/[email protected]/[email protected]/g s/jrfonseca-at-tungstengraphics-dot-com/jfonseca-at-vmware-dot-com/ s/jrfonseca\[email protected]/[email protected]/g s/keithw\[email protected]/[email protected]/g s/[email protected]/[email protected]/g s/thomas-at-tungstengraphics-dot-com/thellstom-at-vmware-dot-com/ s/[email protected]/[email protected]/ # Remove dead links s@Tungsten Graphics (http://www.tungstengraphics.com)@Tungsten Graphics@g # C string src/gallium/state_trackers/vega/api_misc.c s/"Tungsten Graphics, Inc"/"VMware, Inc"/ Reviewed-by: Brian Paul <[email protected]>
* gallium: add bits for clipping points as tris (d3d-style)Roland Scheidegger2014-01-171-0/+1
| | | | | | | | | | | | | | | | | | | | | | OpenGL does whole-point clipping, that is a large point is either fully clipped or fully unclipped (the latter means it may extend beyond the viewport as long as the center is inside the viewport). d3d9 (d3d10 has no large points) however requires points to be clipped after they are expanded to a rectangle. (Note some IHVs are known to ignore GL rules at least with some hw/drivers.) Hence add a rasterizer bit indicating which way points should be clipped (some drivers probably will always ignore this), and add the draw interaction this requires. Drivers wanting to support this and using draw must support large points on their own as draw doesn't implement vp clipping on the expanded points (it potentially could but the complexity doesn't seem warranted), and the driver needs to do viewport scissoring on such points. Conflicts: src/gallium/drivers/llvmpipe/lp_context.c src/gallium/drivers/llvmpipe/lp_state_derived.c Reviewed-by: Jose Fonseca <[email protected]>
* swrast* (gallium, classic): add MESA_copy_sub_buffer support (v3)Dave Airlie2013-12-133-5/+9
| | | | | | | | | | | | | | | | | | | | | | | This patches add MESA_copy_sub_buffer support to the dri sw loader and then to gallium state tracker, llvmpipe, softpipe and other bits. It reuses the dri1 driver extension interface, and it updates the swrast loader interface for a new putimage which can take a stride. I've tested this with gnome-shell with a cogl hacked to reenable sub copies for llvmpipe and the one piglit test. I could probably split this patch up as well. v2: pass a pipe_box, to reduce the entrypoints, as per Jose's review, add to p_screen doc comments. v3: finish off winsys interfaces, add swrast classic support as well. Reviewed-by: Jose Fonseca <[email protected]> Signed-off-by: Dave Airlie <[email protected]> swrast: add support for copy_sub_buffer
* gallium: allow choosing which colorbuffers to clearMarek Olšák2013-12-121-4/+15
| | | | | | | | | | | | | | Required for glClearBuffer, which only clears one colorbuffer attachment. Example: If the first colorbuffer is float and the second one is int: pipe->clear(pipe, PIPE_CLEAR_COLOR0, float_clear_color, ...); pipe->clear(pipe, PIPE_CLEAR_COLOR1, int_clear_color, ...); This doesn't need any driver changes yet, because all drivers just use: if (flags & PIPE_CLEAR_COLOR) .. The drivers which support GL 3.0 will have to implement it properly though.
* llvmpipe: add plumbing for ARB_depth_clampMatthew McClure2013-12-111-0/+2
| | | | | | | | | | With this patch llvmpipe will adhere to the ARB_depth_clamp enabled state when clamping the fragment's zw value. To support this, the variant key now includes the depth_clamp state. key->depth_clamp is derived from pipe_rasterizer_state's (depth_clip == 0), thus depth clamp is only enabled when depth clip is disabled. Reviewed-by: Roland Scheidegger <[email protected]> Reviewed-by: José Fonseca <[email protected]>
* gallium/dri: Support DRI Image extension version 7Christopher James Halse Rogers2013-12-101-0/+2
| | | | | | | | | | | v2: Fix up queryImage return for ATTRIB_FD Use driver_descriptor.configuration to determine whether the driver supports DMA-BUF import/export. v3: Really, truly, fix up queryImage return for ATTRIB_FD Signed-off-by: Christopher James Halse Rogers <[email protected]> Reviewed-by: Thomas Hellstrom <[email protected]> Signed-off-by: Maarten Lankhorst <[email protected]>
* gallium/winsys/drm: Prepare for passing prime fds in winsys_handleChristopher James Halse Rogers2013-12-101-3/+6
| | | | | | Signed-off-by: Christopher James Halse Rogers <[email protected]> Reviewed-by: Thomas Hellstrom <[email protected]> Signed-off-by: Maarten Lankhorst <[email protected]>
* gallium: add support for AMD_vertex_shader_layerMarek Olšák2013-12-031-1/+2
|
* gallium: new shader cap bit for the amount of sampler viewsRoland Scheidegger2013-11-281-1/+2
| | | | | | | | | Ever since introducing separate sampler and sampler view max this was really missing. Every driver but llvmpipe reports the same number as number of samplers for now, so nothing should break. Reviewed-by: Jose Fonseca <[email protected]>
* gallium: fix build on GNU/kFreeBSDFabio Pedretti2013-11-061-1/+1
| | | | | | | Patch from Debian package Reviewed-by: Brian Paul <[email protected]> Reviewed-by: Andreas Boll <[email protected]>
* vl/h264: split fields into SPS/PPSChristian König2013-10-281-24/+64
| | | | | | Add alot of missing fields as well. Signed-off-by: Christian König <[email protected]>
* vl: add 400 chroma format as wellChristian König2013-10-281-0/+1
| | | | Signed-off-by: Christian König <[email protected]>
* implement NV_vdpau_interop v7Christian König2013-10-261-0/+49
| | | | | | | | | | | | | | | | | | | v2: Actually implement interop between the gallium state tracker and the VDPAU backend. v3: Make it also available in non legacy contexts, fix video buffer sharing. v4: deny interop if we don't have the same screen object v5: rebased on upstream changes v6: implemented VDPAUGetSurfaceivNV, improved error handling, unregister all surfaces in VDPAUFiniNV v7: squash merge with Mareks changes Signed-off-by: Christian König <[email protected]>
* gallium: add PIPE_CAP_MIXED_FRAMEBUFFER_SIZESIlia Mirkin2013-10-261-1/+2
| | | | | | | | | This CAP will determine whether ARB_framebuffer_object can be enabled. The nv30 driver does not allow mixing swizzled and linear zsbuf/cbuf textures. Signed-off-by: Ilia Mirkin <[email protected]> Signed-off-by: Marek Olšák <[email protected]>
* gallium: new, unified pipe_context::set_sampler_views() functionBrian Paul2013-10-231-15/+3
| | | | | | | | | | | | The new function replaces four old functions: set_fragment/vertex/ geometry/compute_sampler_views(). Note: at this time, it's expected that the 'start' parameter will always be zero. Reviewed-by: Roland Scheidegger <[email protected]> Reviewed-by: Marek Olšák <[email protected]> Tested-by: Emil Velikov <[email protected]>
* gallium: Add support for 32x32 muls with 64 bit resultsZack Rusin2013-10-091-1/+4
| | | | | | | | | | | | | | The code introduces two new 32bit integer multiplication opcodes which can be used to produce correct 64 bit results. GLSL, OpenCL and D3D10+ require them. We use two seperate opcodes, because they match the behavior of GLSL and OpenCL, are a lot easier to add than a single opcode with multiple destinations and because there's not much (any) difference wrt code-generation. Signed-off-by: Zack Rusin <[email protected]> Reviewed-by: José Fonseca <[email protected]> Reviewed-by: Roland Scheidegger <[email protected]> Reviewed-by: Brian Paul <[email protected]>
* gallium: remove old bind_*_sampler_states() functionsBrian Paul2013-10-031-15/+0
| | | | | The new bind_sampler_states() function takes a shader argument to specify the shader stage.
* gallium: add pipe_context::bind_sampler_states()Brian Paul2013-10-031-0/+5
| | | | | The bind_vertex/geometry/fragment/compute_sampler_states() functions will be replaced by a single functions.
* gallium: add flush_resource context functionMarek Olšák2013-09-201-0/+13
| | | | | | | | | r600g needs explicit flushing before DRI2 buffers are presented on the screen. v2: add (stub) implementations for all drivers, fix frontbuffer flushing v3: fix galahad Signed-off-by: Marek Olšák <[email protected]>
* gallium: comment that INSTANCEID doesn't include start_instanceMarek Olšák2013-09-131-1/+1
| | | | Reviewed-by: Christian König <[email protected]>
* st/dri: do not create a new context for msaa copyMaarten Lankhorst2013-09-111-1/+2
| | | | | | | | | | | | | | | | Commit b77316ad7594f st/dri: always copy new DRI front and back buffers to corresponding MSAA buffers introduced creating a pipe_context for every call to validate, which is not required because the callers have a context anyway. Only exception is egl_g3d_create_pbuffer_from_client_buffer, can someone test if it still works with NULL passed as context for validate? From examining the code I believe it does, but I didn't thoroughly test it. Signed-off-by: Maarten Lankhorst <[email protected]> Cc: 9.2 <[email protected]> Reviewed-by: Marek Olšák <[email protected]>
* util: don't use _fxsave() with MSVC 2010 or olderBrian Paul2013-09-101-0/+4
| | | | | | And update _MSC_VER comments in p_config.h Reviewed-by: Roland Scheidegger <[email protected]>
* gallium, intel: Implements new __DRI_IMAGE_USE_LINEAR and PIPE_BIND_LINEAR ↵Axel Davy2013-09-061-0/+4
| | | | | | flags to enforce no tiling. Signed-off-by: Axel Davy <[email protected]>
* gallium: Support PIPE_FORMAT_R10G10B10A2_UINT.José Fonseca2013-08-221-0/+1
| | | | | | Same as PIPE_FORMAT_B10G10R10A2_UINT but without the swizzling. Reviewed-by: Roland Scheidegger <[email protected]>
* vl: add entrypoint to is_video_format_supportedChristian König2013-08-191-1/+2
| | | | Signed-off-by: Christian König <[email protected]>
* vl: add entrypoint to get_video_paramChristian König2013-08-191-0/+1
| | | | Signed-off-by: Christian König <[email protected]>
* vl: rename pipe_video_decoder to pipe_video_codecChristian König2013-08-192-14/+14
| | | | Signed-off-by: Christian König <[email protected]>
* vl: rename enum pipe_video_codec to pipe_video_formatChristian König2013-08-192-11/+11
| | | | Signed-off-by: Christian König <[email protected]>
* vl: use a template for create_video_decoderChristian König2013-08-192-5/+2
| | | | Signed-off-by: Christian König <[email protected]>
* vl: Add support for max level query v2Rico Schüller2013-08-141-1/+2
| | | | | | | | | This patch adds the level query support to the video decoders and uses some more reasonable defaults. v2: (ck) add commit message Reviewed-by: Christian König <[email protected]>
* gallium: add new float comparison instructions returning integer masksRoland Scheidegger2013-08-131-1/+6
| | | | | | | | | | | | Newer graphic languages don't want messy float mask results but instead true "boolean" mask results for float comparisons. Otherwise just need to convert the floats back to integers. Need to keep the old opcodes however due to both legacy (gl and d3d9) needing them and because older hw can't really deal with integers. These new FSEQ/FSGE/FSLT/FSNE opcodes are part of integer API and hence must be supported if a driver claims to support glsl 1.30 (or PIPE_SHADER_CAP_INTEGERS). Reviewed-by: Zack Rusin <[email protected]>
* st/dri: add a new driconf option disable_shader_bit_encoding for UnigineMarek Olšák2013-07-301-0/+1
| | | | | | | Now Unigine Heaven 3.0 finally works with r600g. Reviewed-by: Kenneth Graunke <[email protected]> Reviewed-by: Brian Paul <[email protected]>
* mesa,glsl,st/dri: add a new driconf option force_glsl_version for UnigineMarek Olšák2013-07-301-2/+3
| | | | | | | | See documentation in mtypes.h. Reviewed-by: Kenneth Graunke <[email protected]> Reviewed-by: Brian Paul <[email protected]> Reviewed-by: Ian Romanick <[email protected]>
* st/dri: implement the driconf option force_s3tc_enable properlyMarek Olšák2013-07-301-0/+1
| | | | Reviewed-by: Brian Paul <[email protected]>
* st/dri: support the driconf option disable_blend_func_extendedMarek Olšák2013-07-301-2/+3
| | | | | | | This is needed for Unigine. Reviewed-by: Kenneth Graunke <[email protected]> Reviewed-by: Brian Paul <[email protected]>
* gallium: Add PIPE_CAP_ENDIANNESSTom Stellard2013-07-221-1/+11
| | | | | | Cc: [email protected] [ Francisco Jerez: Fix "PIPE_ENDIAN_SMALL" in the documentation, define PIPE_ENDIAN_NATIVE. ]
* llvmpipe: use MCJIT on ARM and AArch64Kyle McMartin2013-07-171-1/+8
| | | | | | | | MCJIT is the only supported LLVM JIT on AArch64 and ARM (the regular JIT has bit-rotted badly on ARM and doesn't exist on AArch64.) Signed-off-by: Kyle McMartin <[email protected]> Signed-off-by: Dave Airlie <[email protected]>
* tgsi: rename the TGSI fragment kill opcodesBrian Paul2013-07-121-2/+2
| | | | | | | | | | | | | | | | | | | | | TGSI_OPCODE_KIL and KILP had confusing names. The former was conditional kill (if any src component < 0). The later was unconditional kill. At one time KILP was supposed to work with NV-style condition codes/predicates but we never had that in TGSI. This patch renames both opcodes: TGSI_OPCODE_KIL -> KILL_IF (kill if src.xyzw < 0) TGSI_OPCODE_KILP -> KILL (unconditional kill) Note: I didn't just transpose the opcode names to help ensure that I didn't miss updating any code anywhere. I believe I've updated all the relevant code and comments but I'm not 100% sure that some drivers had this right in the first place. For example, the radeon driver might have llvm.AMDGPU.kill and llvm.AMDGPU.kilp mixed up. Driver authors should review their code. Reviewed-by: Jose Fonseca <[email protected]>
* mesa,glsl,gallium: remove GLSLSkipStrictMaxVaryingLimitCheck and dependenciesMarek Olšák2013-07-021-1/+0
| | | | | | Not needed with do_dead_builtin_varyings. Reviewed-by: Ian Romanick <[email protected]>
* gallium: Fix llvmpipe on big-endian machinesAdam Jackson2013-06-241-0/+22
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Squashed commit of the following: commit 0857a7e105bfcbc4d1431b2cc56612094c747ca3 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:07 2013 -0400 gallivm: Fix lp_build_rgba8_to_fi32_soa for big endian Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 0d65131649a8aa140e2db228ba779d685c4333e3 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:07 2013 -0400 gallivm: Fix big-endian machines This adds a bit-shift count to the format table, and adds the concept of vector or bitwise alignment on gathers. Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 9740bda9b7dc894b629ed38be9b51059ce90818f Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:07 2013 -0400 llvmpipe: Fix convert_to_blend_type on big-endian Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit ae037c2de0f029e4e99371c0de25560484f0d8df Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 util: Convert color pack to packed formats This fixes them on big-endian. Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 5b05ac0c89ae092ea8ba5bba9f739708d7396b5c Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 graw-xlib: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 51396e7d098cb6ff794391cf11afe4dbf86dbea0 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 format: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 417b60bc66eb450e68a92ab0e47f76e292b385e6 Author: Adam Jackson <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 st/dri: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 0934b2e022a5e0847d312c40734e2b44cac52fd8 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 st/xlib: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit a307ea3c3716a706963acce7966b5e405ba11db9 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 gbm: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 53eebdd253e1960a645ea278f31d7ef6a6cf4aeb Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 tests: Convert to packed formats Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 2f77fe3ee524945eacd546efcac34f7799fb3124 Author: Adam Jackson <[email protected]> Date: Tue Jun 18 13:07:37 2013 -0400 gallium: Document packed formats Signed-off-by: Adam Jackson <[email protected]> commit 1f1017159ce951f922210a430de9229f91f62714 Author: Richard Sandiford <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 gallium: Introduce 32-bit packed format names These are for interacting with buffers natively described in terms of bit shifts, like X11 visuals: uint32_t xyzw8888 = (x << 0) | (y << 8) | (z << 16) | (w << 24); Define these in terms of (endian-dependent) aliases to the array-style format names. Reviewed-by: Adam Jackson <[email protected]> Signed-off-by: Richard Sandiford <[email protected]> commit 6cc7ab1ee66ed668da78c1d951dfd7782b4e786a Author: Adam Jackson <[email protected]> Date: Mon Jun 3 12:10:32 2013 -0400 gallium: Document format name conventions v2: - Fix a channel name thinko (Michel Dänzer) - Elaborate on SCALED versus INT - Add links to DirectX and FOURCC docs Signed-off-by: Adam Jackson <[email protected]> commit df4d269e7fb62051a3c029b84147465001e5776e Author: Adam Jackson <[email protected]> Date: Tue Jun 18 12:25:06 2013 -0400 gallivm: Remove all notion of byte-swapping Signed-off-by: Adam Jackson <[email protected]> Signed-off-by: Adam Jackson <[email protected]>
* gallium: add condition parameter to render_conditionRoland Scheidegger2013-06-181-0/+2
| | | | | | | | | | | | | For conditional rendering this makes it possible to skip rendering if either the predicate is true or false, as supported by d3d10 (in fact previously it was sort of implied skip rendering if predicate is false for occlusion predicate, and true for so_overflow predicate). There's no cap bit for this as presumably all drivers could do it trivially (but this patch does not implement it for the drivers using true hw predicates, nvxx, r600, radeonsi, no change is expected for OpenGL functionality). Reviewed-by: Jose Fonseca <[email protected]>
* gallium/draw: add limits to the clip and cull distancesZack Rusin2013-06-131-0/+2
| | | | | | | | | | | There are strict limits on those registers. Define the maximums and use them instead of magic numbers. Also allows us to add some extra sanity checks. Suggested by Brian. Signed-off-by: Zack Rusin <[email protected]> Reviewed-by: Roland Scheidegger <[email protected]> Reviewed-by: Jose Fonseca <[email protected]>
* gallium: add a cull distance semanticZack Rusin2013-06-101-1/+2
| | | | | | | | | | | | | cull distance is analogous to clip distance. If a register is given this semantic, then the values in it are assumed to be a float32 distance to a plane. Primitives will be completely discarded if the plane distance for all of the vertices in the primitive are < 0. Signed-off-by: Zack Rusin <[email protected]> Reviewed-by: Jose Fonseca <[email protected]> Reviewed-by: Brian Paul <[email protected]> Reviewed-by: Roland Scheidegger <[email protected]>
* gallium: System z supportRichard Sandiford2013-06-051-1/+5
| | | | | | | | | The main change is to use MCJIT rather than the old JIT, which will never be supported for System z. The endianness part is by example since the patch was tested on a glibc system. Signed-off-by: Richard Sandiford <[email protected]> Signed-off-by: Brian Paul <[email protected]>
* gallium: add support for layered renderingRoland Scheidegger2013-06-011-1/+2
| | | | | | | | | | Since pipe_surface already has all the necessary fields no interface changes are necessary except adding a new shader semantic value (TGSI_SEMANTIC_LAYER). (Note that what GL knows as "gl_Layer" variable d3d10 is naming "RENDER_TARGET_ARRAY_INDEX".) v2: drop cap bit (just tied to geometry shader), add docs.
* gallium: Add support for multiple viewportsZack Rusin2013-05-254-6/+13
| | | | | | | | | | | | Gallium supported only a single viewport/scissor combination. This commit changes the interface to allow us to add support for multiple viewports/scissors. Signed-off-by: Zack Rusin <[email protected]> Reviewed-by: Marek Olšák <[email protected]> Reviewed-by: José Fonseca<[email protected]> Reviewed-by: Brian Paul <[email protected]> Reviewed-by: Roland Scheidegger <[email protected]>
* gallium: add PIPE_CAP_MAX_TEXTURE_BUFFER_SIZE for GLMarek Olšák2013-05-111-1/+2
| | | | | | v2: fix typo 65535 -> 65536 Reviewed-by: Brian Paul <[email protected]>
* gallium: fix type of flags in pipe_context::flush()Chia-I Wu2013-05-041-1/+3
| | | | | | | | | | | | | | | | It should be unsigned, not enum pipe_flush_flags. Fixed a build error: src/gallium/state_trackers/egl/android/native_android.cpp:426:29: error: invalid conversion from 'int' to 'pipe_flush_flags' [-fpermissive] v2: replace all occurrences of enum pipe_flush_flags by unsigned Signed-off-by: Chia-I Wu <[email protected]> Reviewed-by: Marek Olšák <[email protected]> [olv: document the parameter now that the type is unsigned]