Changes between Initial Version and Version 1 of fbf_device_api

Timestamp:

Jan 20, 2020, 3:10:40 PM (5 years ago)

Author:

alain

Comment:

--

fbf_device_api

@@ +1 @@
+= FBF device API =
+
+[[PageOutline]]
+
+== __A) General principles__ ==
+
+This device provide access to an external graphic display, that is seen as a fixed size frame buffer, mapped in the kernel address space. The only pixel encoding type in the current implementation is one byte per pixel (256 levels of gray).
+
+It defines a first API, implementing the user syscalls, and implementing a simple, kernel controlled, windows manager.
+This windows manager allows any process to create and use for display one (or several) window(s). Each window defines a private buffer, dynamically allocated in user space, that can be directly accessed (for read and write) by the owner process.
+
+These windows can be moved in the frame buffer, they can be resized, they can overlap other windows, but a window must be entirely contained in the frame buffer.
+
+To avoid contention, the window descriptor, and the associated user buffer are not allocated in the cluster containing the FBF chdev, but are distributed: each window is allocated in the cluster defined by the thread that required the window creation.
+
+Each window has a single process owner, but all the windows are registered in the FBF chdev in a windows_tbl[] array, indexed by the window identifier (wid). Each array entry contains an extended pointer on the window descriptor. All windows are also registered in a trans-cluster xlist, defining the overlapping order (last window in xlist has the highest priority).
+
+All FBF access functions are defined in the [https://www-soc.lip6.fr/trac/almos-mkh/kernel/devices/dev_fbf.c  dev_fbf.c] et [https://www-soc.lip6.fr/trac/almos-mkh/kernel/devices/dev_fbf.h dev_fbf.h] files.
+
+== __B) Initialisation__ == 
+
+The '''dev_fbf_init()''' function completes the FBF chdev descriptor initialisation. It calls the specific driver initialisation function, to initialise the specific hardware device, and initializes the FBF chdev extension. It must be called by a local thread.
+
+== __C) Sys-calls API__ ==
+
+The ''syscalls'' API define the following access functions, that do NOT use the the FBF device waiting queue, the associated
+device thread and the FBF IRQ, as the client thread does NOT deschedules,
+
+=== C.1) dev_fbf_get_config() ===
+
+This function implements the ''fbf_get_config()'' syscall. It returns the FBF number of lines, the number of pixels per line, and the pixel encoding type. It can be called by a client thread running in any cluster.
+It does not access the hardware, as the size and type have been registered in the chdev descriptor extension by the dev_fbf_init() function.
+
+=== C.2) dev_fbf_create_window() ===
+
+This blocking function implements the ''fbf_create_window()'' sys-call. It registers a new window in the windows_tbl[] array, and in the windows list, rooted in FBF device descriptor. It registers in the reference VSL an ANON vseg, that will be mapped in local cluster. The window index <wid> is dynamically allocated. The owner process is the calling process. The FBF window is defined by the <nlines>, <npixels>, <l_min>, <p_min> arguments. The created vseg base address in user space is returned in the <user_base> argument. It can be called by any thread running in any cluster.
+
+As the vseg associated to the window is not directly  mapped to the frame buffer, the owner process can read and write in the window buffer without syscall. As for any other vseg, the physical memory is allocated on demand, at each page fault. 
+
+=== C.3) dev_fbf_refresh_window() ===
+
+This blocking function implements the ''fbf_refresh_window()'' sys-call. It allows the owner process to signal the windows manager that some lines of a window identified by the <wid>, <line_min>, and <line_max> arguments have been modified, and must be refreshed in the FBF. It scans all the registered FBF windows to respect the overlap order defined by the windows xlist. It can be called by any thread running in any cluster.
+
+=== C.4) dev_fbf_move_window() ===
+
+This blocking function implements the ''fbf_move_window()'' sys-call. It moves a window identified by the <wid> argument to a new position in the FBF, defined by the <l_min> and <p_min> arguments. It can be called by any thread running in any cluster.
+
+=== C.5) dev_fbf_resize_window() ===
+
+This blocking function implements the ''fbf_resize_window()'' syscall. It changes the <width> and <height> of a window identified by the <wid> argument. It updates the size of the associated vseg, but does not change the vseg "base". When the new window buffer is larger than the existing one, this buffer is 0 filled. It can be called by any thread running in any cluster.
+
+=== C.6) dev_fbf_delete_window() ===
+
+This function implements the ''fbf_delete_window()'' syscall to delete a FBF window. It releases all memory allocated for the window buffer and for the window descriptor. It can be called by any thread running in any cluster.
+
+=== C.7) dev_fbf_move_data() ===
+
+This function implements the deprecated ''fbf_read()'' and ''fbf_write()'' sys-calls.
+ * 2) Two extra syscalls exist but are deprecated:
+ * - FBF_DIRECT_WRITE   : move synchronously pixels from an user buffer to the FBF.
+ * - FBF_DIRECT_READ    : move synchronously pixels from the FBF to an user buffer.
+ *
+ * For these deprecated operations, the client thread calls
+ * directly the driver to move data between the user buffer and the FBF.
+ * 
+
+=== C) Drivers API FBF The FBF device defines defines four command types to access FBF driver(s) :
+ * - FBF_DRIVER_KERNEL_WRITE : move pixels from a kernel window to the FBF.
+ * - FBF_DRIVER_KERNEL_READ  : move pixels from the FBF to a kernel window.
+ * - FBF_DRIVER_USER_WRITE   : move bytes from an user buffer to the FBF. 
+ * - FBF_DRIVER_USER_READ    : move bytes from the FBF to an user buffer. 
+ *
+ * Note: As we don'