[Intel-gfx] [PATCH 3/3] drm/i915: Add soft-pinning API for execbuffer

[Jesse Barnes]

On 11/06/2015 05:38 AM, Chris Wilson wrote:
> On Thu, Nov 05, 2015 at 10:17:56AM -0800, Jesse Barnes wrote:
>> On 11/05/2015 09:51 AM, Kristian Høgsberg wrote:
>>> On Tue, Oct 6, 2015 at 3:53 AM, Chris Wilson <chris at chris-wilson.co.uk> wrote:
>>>> Userspace can pass in an offset that it presumes the object is located
>>>> at. The kernel will then do its utmost to fit the object into that
>>>> location. The assumption is that userspace is handling its own object
>>>> locations (for example along with full-ppgtt) and that the kernel will
>>>> rarely have to make space for the user's requests.
>>>
>>> I know the commit message isn't documentation, but the phrase "do its
>>> utmost" makes me uncomfortable. I'd like to be explicit about what
>>> might make it fail (should only be pinned fbs in case of aliased ppgtt
>>> or userspace errors such as overlapping placements), or conversely,
>>> spell out when the flag can be expected to work (full ppgtt).
>>
>> Ooh yeah that would be good to add to the execbuf man page with the
>> softpin additions.  Oh wait, we don't have a man page for execbuf?
>> Someone should write one!
> 
> How about:
> 
>     This extends the DRM_I915_GEM_EXECBUFFER2 ioctl to do the following:
>     * if the user supplies a virtual address via the execobject->offset
>       *and* sets the EXEC_OBJECT_PINNED flag in execobject->flags, then
>       that object is placed at that offset in the address space selected
>       by the context specifier in execbuffer.
>     * the location must be aligned to the GTT page size, 4096 bytes
>     * as the object is placed exactly as specified, it may be used in this batch
>       without relocations pointing to it
>     
>     It may fail to do so if:
>     * EINVAL is returned if the object does not have a 4096 byte aligned
>       address
>     * the object conflicts with another pinned object (either pinned by
>       hardware in that address space, e.g. scanouts in the aliasing ppgtt)
>       or within the same batch.
>       EBUSY is returned if the location is pinned by hardware
>       EINVAL is returned if the location is already in use by the batch
>     * EINVAL is returned if the object conflicts with its own alignment (as meets
>       the hardware requirements) or if the placement of the object does not fit
>       within the address space
>     
>     All other execbuffer errors apply.

Looks great, now we just need an existing man page in which to integrate
this additional text.

Jesse