Documentation/kds.txt

   1 #
   2 # (C) COPYRIGHT 2012 ARM Limited. All rights reserved.
   3 #
   4 # This program is free software and is provided to you under the terms of the GNU General Public License version 2
   5 # as published by the Free Software Foundation, and any use by you of this program is subject to the terms of such GNU licence.
   6 #
   7 # A copy of the licence is included with the program, and can also be obtained from Free Software
   8 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
   9 #
  10 #
  11
  12
  13 ==============================
  14 kds - Kernel Dependency System
  15 ==============================
  16
  17 Introduction
  18 ------------
  19 kds provides a mechanism for clients to atomically lock down multiple abstract resources.
  20 This can be done either synchronously or asynchronously.
  21 Abstract resources is used to allow a set of clients to use kds to control access to any
  22 resource, an example is structured memory buffers.
  23
  24 kds supports that buffer is locked for exclusive access and sharing of buffers.
  25
  26 kds can be built as either a integrated feature of the kernel or as a module.
  27 It supports being compiled as a module both in-tree and out-of-tree.
  28
  29
  30 Concepts
  31 --------
  32 A core concept in kds is abstract resources.
  33 A kds resource is just an abstraction for some client object, kds doesn't care what it is.
  34 Typically EGL will consider UMP buffers as being a resource, thus each UMP buffer has
  35 a kds resource for synchronization to the buffer.
  36
  37 kds allows a client to create and destroy the abstract resource objects.
  38 A new resource object is made available asap (it is just a simple malloc with some initializations),
  39 while destroy it requires some external synchronization.
  40
  41 The other core concept in kds is consumer of resources.
  42 kds is requested to allow a client to consume a set of resources and the client will be notified when it can consume the resources.
  43
  44 Exclusive access allows only one client to consume a resource.
  45 Shared access permits multiple consumers to acceess a resource concurrently.
  46
  47
  48 APIs
  49 ----
  50 kds provides simple resource allocate and destroy functions.
  51 Clients use this to instantiate and control the lifetime of the resources kds manages.
  52
  53 kds provides two ways to wait for resources:
  54 - Asynchronous wait: the client specifies a function pointer to be called when wait is over
  55 - Synchronous wait: Function blocks until access is gained.
  56
  57 The synchronous API has a timeout for the wait.
  58 The call can early out if a signal is delivered.
  59
  60 After a client is done consuming the resource kds must be notified to release the resources and let some other client take ownership.
  61 This is done via resource set release call.
  62
  63 A Windows comparison:
  64 kds implements WaitForMultipleObjectsEx(..., bWaitAll = TRUE, ...) but also has an asynchronous version in addition.
  65 kds resources can be seen as being the same as NT object manager resources.
  66
  67 Internals
  68 ---------
  69 kds guarantees atomicity when a set of resources is operated on.
  70 This is implemented via a global resource lock which is taken by kds when it updates resource objects.
  71
  72 Internally a resource in kds is a linked list head with some flags.
  73
  74 When a consumer requests access to a set of resources it is queued on each of the resources.
  75 The link from the consumer to the resources can be triggered. Once all links are triggered
  76 the registered callback is called or the blocking function returns.
  77 A link is considered triggered if it is the first on the list of consumers of a resource,
  78 or if all the links ahead of it is marked as shared and itself is of the type shared.
  79
  80 When the client is done consuming the consumer object is removed from the linked lists of
  81 the resources and a potential new consumer becomes the head of the resources.
  82 As we add and remove consumers atomically across all resources we can guarantee that
  83 we never introduces a A->B + B->A type of loops/deadlocks.
  84
  85
  86 kbase/base implementation
  87 -------------------------
  88 A HW job needs access to a set of shared resources.
  89 EGL tracks this and encodes the set along with the atom in the ringbuffer.
  90 EGL allocates a (k)base dep object to represent the dependency to the set of resources and encodes that along with the list of resources.
  91 This dep object is use to create a dependency from a job chain(atom) to the resources it needs to run.
  92 When kbase decodes the atom in the ringbuffer it finds the set of resources and calls kds to request all the needed resources.
  93 As EGL needs to know when the kds request is delivered a new base event object is needed: atom enqueued. This event is only delivered for atoms which uses kds.
  94 The callback kbase registers trigger the dependency object described which would trigger the existing JD system to release the job chain.
  95 When the atom is done kds resource set release is call to release the resources.
  96
  97 EGL will typically use exclusive access to the render target, while all buffers used as input can be marked as shared.
  98
  99
 100 Buffer publish/vsync
 101 --------------------
 102 EGL will use a separate ioctl or DRM flip to request the flip.
 103 If the LCD driver is integrated with kds EGL can do these operations early.
 104 The LCD driver must then implement the ioctl or DRM flip to be asynchronous with kds async call.
 105 The LCD driver binds a kds resource to each virtual buffer (2 buffers in case of double-buffering).
 106 EGL will make a dependency to the target kds resource in the kbase atom.
 107 After EGL receives a atom enqueued event it can ask the LCD driver to pan to the target kds resource.
 108 When the atom is completed it'll release the resource and the LCD driver will get its callback.
 109 In the callback it'll load the target buffer into the DMA unit of the LCD hardware.
 110 The LCD driver will be the consumer of both buffers for a short period.
 111 The LCD driver will call kds resource set release on the previous on-screen buffer when the next vsync/dma read end is handled.
 112
 113