flesh out the buffer management & security sub-section

1 files changed, 93 insertions, 7 deletions

diff --git a/linuxgraphicsdrivers.lyx b/linuxgraphicsdrivers.lyx
index 6a242db..da1fb2c 100644
--- a/linuxgraphicsdrivers.lyx
+++ b/linuxgraphicsdrivers.lyx
@@ -5579,34 +5579,120 @@ To prevent access to arbitrary GPU memory, the command submission ioctl
  bearable, and this is how the open source radeon drivers work.
 \end_layout
 
+\begin_layout Subsubsection
+Buffer management
+\end_layout
+
 \begin_layout Standard
+GPU buffer allocation and management is done in the kernel and exposed to
+ the userspace through the GEM interface.
+ Such buffer is then called an object or a buffer object (BO).
+\end_layout
 
-\lang english
-GEM, TTM
+\begin_layout Standard
+GEM has been introduced by Intel in 2008 to simplify Tungsten Graphics'
+ TTM (Translation Table Maps) and became the standard way to allocate, read,
+ write and sharing BOs between applications.
+ It is however impossible to share buffers between drivers through GEM.
 \end_layout
 
 \begin_layout Standard
+As the GEM interface is driver-dependent, it is advised to use the driver-depend
+ent libdrm calls to manage your buffers.
+ However, the general outline of the interface remains fairly constant.
+\end_layout
+
+\begin_layout Paragraph*
 
 \lang english
-map/unmap ioctls
+Object Allocation & Destruction
 \end_layout
 
 \begin_layout Standard
+Object allocation is done by calling the GEM_CREATE function.
+ It should take the required size of the buffer as an argument and return
+ a handle that is non-zero.
+ This handle will be used later on as a buffer identifier.
+\end_layout
+
+\begin_layout Paragraph*
 
 \lang english
-pwrite
+Reading and writing from/to a buffer object
 \end_layout
 
 \begin_layout Standard
+There are two ways to read/write from/to a buffer object:
+\end_layout
 
-\lang english
-Share video memory
+\begin_layout Itemize
+pread/pwrite : syscalls to read/write to/from a buffer object.
+ They both take the BO offset, the size and where the data should be read
+ from/written to;
+\end_layout
+
+\begin_layout Itemize
+mapping the BO : it is possible for the userspace to map the BO in his memory
+ space.
+ Mapping takes the BO offset and size that should be mapped as an argument.
+ It then returns the address of the BO in the user's virtual address space.
+\end_layout
+
+\begin_layout Paragraph*
+Sharing buffer objects between applications
+\end_layout
+
+\begin_layout Standard
+The GEM interface specifies a way for applications/clients to share buffers.
+ In order to share a buffer, a client should:
+\end_layout
+
+\begin_layout Enumerate
+call GEM_FLINK with the handle of the buffer object to be shared.
+ An uint32 name will be returned.
+\end_layout
+
+\begin_layout Enumerate
+transfer this name to the clients that should access the buffer object
+\end_layout
+
+\begin_layout Enumerate
+the remote clients should open the BO by name by using the GEM_OPEN IOCTL.
+\end_layout
+
+\begin_layout Standard
+By default, no buffers are shared between clients.
+ However, when one buffer is shared, any authenticated client can read/write
+ to the BO.
+ No access control is done between authenticated clients.
+\end_layout
+
+\begin_layout Standard
+A client is said to be authenticated if his euid is 0 (root) or if an already-au
+thenticated client added this client to the authenticated-clients list.
 \end_layout
 
 \begin_layout Standard
+The procedure to authenticate a non-root client is:
+\end_layout
+
+\begin_layout Enumerate
+get a magic cookie from the dri interface (drm_getmagic)
+\end_layout
+
+\begin_layout Enumerate
+send the magic cookie to an already-authenticated client
+\end_layout
+
+\begin_layout Enumerate
+the authenticated client calls drm_authmagic to authenticate the cookie
+ and thus, the original client
+\end_layout
+
+\begin_layout Paragraph*
 
 \lang english
-flink
+Sharing buffer objects between drivers
 \end_layout
 
 \begin_layout Standard