source: trunk/kernel/devices/dev_fbf.h @ 657

Last change on this file since 657 was 657, checked in by alain, 22 months ago

Introduce remote_buf.c/.h & socket.c/.h files.
Update dev_nic.c/.h files.

File size: 19.3 KB
Line 
1/*
2 * dev_fbf.h - FBF (Frame Buffer) generic device API definition.
3 *
4 * Author  Alain Greiner    (2016,2017,2018,2019,2020)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _DEV_FBF_H
25#define _DEV_FBF_H
26
27#include <hal_kernel_types.h>
28#include <shared_fbf.h>
29#include <remote_rwlock.h>
30#include <bits.h>
31
32/****  Forward declarations  ****/
33
34struct chdev_s;
35
36/*****************************************************************************************
37 *      Frame Buffer Controler API definition
38 *
39 * This device provide access to an external graphic display, that is seen
40 * as a fixed size frame buffer, mapped in the kernel address space.
41 * The only pixel encoding type in the current implementation is one byte per pixel
42 * (256 levels of gray).
43 *
44 * It supports a first API, for the user syscalls, implementing a simple windows manager.
45 * This windows manager allows any process to create and use for display one (or several)
46 * window(s). Each window defines a private buffer, dynamically allocated in user space,
47 * that can be directly accessed by the owner process.
48 * These windows can be moved in the frame buffer, they can be resized, they can overlap
49 * other windows, but a window must be entirely contained in the frame buffer.
50 *
51 * To avoid contention, the window descriptor, and the associated user buffer are not
52 * allocated in the cluster containing the FBF chdev, but are distributed: each window
53 * is allocated in the cluster defined by the thread that required the window creation.
54 *
55 * Each window has a single process owner, but all the windows are registered in the FBF
56 * chdev as a windows_tbl[] array, indexed by the window identifier (wid), and each entry
57 * contains an extended pointer on the window descriptor. All windows are also registered
58 * in a trans-cluster xlist, defining the overlapping order (last window in xlist has the
59 * highest priority).
60 *
61 * To refresh a window <wid>, the owner process calls the dev_fbf_refresh_window()
62 * function, that sends parallel RPC_FBF_DISPLAY requests to other cores. All cores
63 * synchronously execute the dev_fbf_display() function. This function scan all windows
64 * to respect the overlaping order, and updates all pixels of the <wid> window.
65 *
66 * 1) This "syscall" API defines five syscalls :
67 * - FBF_GET_CONFIG     : returns the FBF width, height, and pixel encoding type.
68 * - FBF_CREATE_WINDOW  : create a new window , owned by the calling process.
69 * - FBF_DELETE_WINDOW  : delete a registered window.
70 * - FBF_MOVE_WINDOW    : move in FBF a registered window.
71 * - FBF_REFRESH_WINDOW : request refresh of a given window.
72 *
73 * These 5 operations do not use the FBF device waiting queue, the associated
74 * device thread and the FBF IRQ, as the client thread does NOT deschedule,
75 * and does NOT call the FBF driver.
76 *
77 * 2) Two extra syscalls exist but are deprecated:
78 * - FBF_DIRECT_WRITE   : move synchronously pixels from an user buffer to the FBF.
79 * - FBF_DIRECT_READ    : move synchronously pixels from the FBF to an user buffer.
80 *
81 * For these deprecated operations, the client thread calls
82 * directly the driver to move data between the user buffer and the FBF.
83 *
84 * 3) The FBF device defines defines four command types to access FBF driver(s) :
85 * - FBF_DRIVER_KERNEL_WRITE : move pixels from a kernel window to the FBF.
86 * - FBF_DRIVER_KERNEL_READ  : move pixels from the FBF to a kernel window.
87 * - FBF_DRIVER_USER_WRITE   : move bytes from an user buffer to the FBF.
88 * - FBF_DRIVER_USER_READ    : move bytes from the FBF to an user buffer.
89 *
90 * Note: As we don't use any external DMA to move data to or from the frame buffer,
91 * but only software memcpy, there is no L2/L3 coherence issue for this device.
92 *
93 *****************************************************************************************/
94
95/******************************************************************************************
96 * This defines the (implementation independant) extension for the generic FBF device.
97 *****************************************************************************************/
98
99typedef struct fbf_extend_s
100{
101    remote_rwlock_t windows_lock;        /*! lock protecting windows xlist               */
102    xlist_entry_t   windows_root;        /*! root of the windows xlist                   */
103
104    xptr_t          windows_tbl[CONFIG_FBF_WINDOWS_MAX_NR];         /*! window desc.     */
105    bitmap_t        windows_bitmap[CONFIG_FBF_WINDOWS_MAX_NR >> 5]; /*! wid allocator    */
106
107    uint32_t        width;               /*! number of pixels per line.                  */
108    uint32_t        height;              /*! total number of lines.                      */
109    uint32_t        subsampling;         /*! pixel encoding type.                        */
110}
111fbf_extend_t;
112
113/******************************************************************************************
114 * This enum defines the various implementations of the generic FBF peripheral.
115 * It must be kept consistent with the define in arch_info.h file.
116 *****************************************************************************************/
117
118typedef enum
119{
120    IMPL_FBF_SCL =   0,     
121    IMPL_FBF_I86 =   1, 
122} 
123fbf_impl_t;
124
125/******************************************************************************************
126 * This structure defines the FBF command for all drivers implementing the FBF device.
127 *****************************************************************************************/
128
129typedef enum
130{
131    FBF_DRIVER_USER_READ     = 1,
132    FBF_DRIVER_USER_WRITE    = 2,
133    FBF_DRIVER_KERNEL_READ   = 3,
134    FBF_DRIVER_KERNEL_WRITE  = 4,
135}
136fbf_driver_cmd_type_t;
137
138typedef struct fbf_command_s
139{
140    xptr_t      dev_xp;        /*! extended pointer on device descriptor                 */
141    uint32_t    type;          /*! requested driver operation type.                      */
142    uint32_t    npixels;       /*! number of bytes.                                      */
143    uint32_t    offset;        /*! offset in frame buffer (pixels)                       */
144    void      * buffer;        /*! pointer on memory buffer (kernel or user)             */
145    uint32_t    error;         /*! operation status (0 if success)                       */
146}
147fbf_command_t;
148
149/******************************************************************************************
150 * This structure defines an FBF window descriptor, allocated to a given user process.
151 * The window descriptor and the associated buffer are allocated in the cluster where
152 * is running the thread requesting the window creation.
153 * The <wid> allocator, the window_tbl[] array, and the root of the xlist of windows are
154 * imlemented in the FBF device extension.
155 *****************************************************************************************/
156
157typedef struct fbf_window_s
158{
159    pid_t          pid;         /*! owner process identifier                             */
160    uint32_t       wid;         /*! window identifier                                    */
161    uint32_t       height;      /*! number of lines in window                            */
162    uint32_t       width;       /*! number of pixels per line in window                  */
163    uint32_t       l_min;       /*! first line index in FBF                              */
164    uint32_t       p_min;       /*! first pixel index in FBF                             */
165    uint8_t      * buffer;      /*! pointer on buffer in user space                      */
166    bool_t         hidden;      /*! no display on FBF when true                          */
167    xlist_entry_t  xlist;       /*! member of registered FBF windows list                */
168}
169fbf_window_t;
170
171/******************************************************************************************
172 * This function returns a printable string for a given FBF user command  <cmd_type>.
173 * WARNING : It must be kept consistent with the enum in the <shared_fbf.h> file
174 ******************************************************************************************
175 * @ cmd_type   :  FBF user command type (defined in shared_fbf.h file).
176 * @ returns a string pointer.
177 *****************************************************************************************/
178char * dev_fbf_cmd_str( uint32_t cmd_type );
179
180/******************************************************************************************
181 * This function completes the FBF chdev descriptor initialisation.
182 * It calls the specific driver initialisation function, to initialise the hardware
183 * device, and the chdev extension. It must be called by a local thread.
184 ******************************************************************************************
185 * @ chdev      : pointer on FBF chdev descriptor.
186 *****************************************************************************************/
187void dev_fbf_init( struct chdev_s * chdev );
188
189/******************************************************************************************
190 * This function implements the fbf_get_config() syscall, and returns the FBF
191 * size and type. It can be called by a client thread running in any cluster.
192 * It does NOT access the hardware, as the size and type have been registered
193 * in the chdev descriptor extension by the dev_fbf_init() function.
194 * It can be called by any thread running in any cluster.
195 ******************************************************************************************
196 * @ width     : [out] number of pixels per line.
197 * @ height    : [out] total number of lines.
198 * @ type      : [out] pixel encoding type.
199 *****************************************************************************************/
200void dev_fbf_get_config( uint32_t  * width,
201                         uint32_t  * height,
202                         uint32_t  * type );
203
204/******************************************************************************************
205 * This function implements the fbf_create_window() syscall.
206 * It registers a new window in the windows_tbl[] array, and the windows list,
207 * registers in the reference cluster an ANON vseg, that will be mapped in local cluster.
208 * The window index <wid> is dynamically allocated. The owner is the calling process.
209 * The FBF window is defined by the <nlines>, <npixels>, <l_min>, <p_min> arguments.
210 * It can be called by any thread running in any cluster. As this vseg is not directly
211 * mapped to the frame buffer, the owner process can access this private buffer without
212 * syscall. As for any vseg, the physical memory is allocated on demand at each page fault.
213* The created vseg base address in user space is returned in the <user_base> argument.
214 *
215 * Implementation note:
216 * 1. it allocates memory in the local cluster for the window,
217 * 2. it creates in the associated vseg,
218 * 3. it initializes the window descriptor,
219 * 4. it takes the lock protecting the windows in write mode,
220 * 5. it allocates a new  <wid>,
221 * 6. it registers the window in the window_tbl[] array,
222 * 7. it registers the window in the windows list,
223 * 8. it releases the lock protecting windows.
224 * It does not call the FBF driver.
225 ******************************************************************************************
226 * @ nlines      : [in]  number of lines in window.
227 * @ npixels     : [in]  number of pixels per line in window.
228 * @ l_min       : [in]  first pixel index in FBF.
229 * @ p_min       : [in]  first line index in FBF.
230 * @ user_base   : [out] pointer on allocated buffer base in user space.
231 * @ return the <wid> index if success / returns -1 if failure
232 *****************************************************************************************/
233uint32_t dev_fbf_create_window( uint32_t   nlines,
234                                uint32_t   npixels,
235                                uint32_t   l_min,
236                                uint32_t   p_min,
237                                intptr_t * user_base );
238
239/******************************************************************************************
240 * This function implements the fbf_delete_window() syscall to delete a FBF window,
241 * and release all memory allocated for this window and for the associated vseg.
242 * releases the memory allocated for the window buffer and for the window descriptor.
243 * It can be called by any thread running in any cluster.
244 *
245 * Implementation note:
246 * 1. it takes the lock protecting windows in write mode,
247 * 2. it set the hidden flag in deleted window descriptor,
248 * 3. it refresh the FBF window,
249 * 4. it removes the window from windows_tbl[] array,
250 * 5. it removes the window from xlist,     
251 * 6. it releases the wid to bitmap,
252 * 7. it releases the lock protecting windows,
253 * 8. it releases the memory allocated for window descriptor,
254 * 9. it deletes the associated vseg in all clusters
255 * It does not call directly the FBF driver.
256 ******************************************************************************************
257 * @ wid       : [in] window index in window_tbl[].
258 * @ returns 0 if success / returns -1 if wid not registered.
259 *****************************************************************************************/
260error_t dev_fbf_delete_window( uint32_t wid );
261                               
262/******************************************************************************************
263 * This function implements the fbf_move_window() syscall.
264 * It moves a window identified by the <wid> argument to a new position in the FBF,
265 * defined by the <l_min> and <p_min> arguments.
266 * It can be called by any thread running in any cluster.
267 *
268 * Implementation note:
269 * 1. it takes the lock protecting windows in write mode,
270 * 2. it gives the modified window the lowest priority,
271 * 3. it set the "hidden" flag in window descriptor,
272 * 4. it refresh the FBF for the current window position,
273 * 5. it set the new coordinates in the window descriptor,
274 * 6. it gives the modified window the highest priority,
275 * 7. it reset the "hidden" flag in window descriptor,
276 * 8. it refresh the FBF for the new window position,
277 * 9. it releases the lock protecting windows,
278 * It does not call directly the FBF driver.
279 ******************************************************************************************
280 * @ wid       : [in] window index in window_tbl[].
281 * @ l_min     : [in] new first pixel index in FBF.
282 * @ p_min     : [in] new first line index in FBF.
283 * @ returns 0 if success / returns -1 if illegal arguments.
284 *****************************************************************************************/
285error_t dev_fbf_move_window( uint32_t wid,
286                             uint32_t l_min,
287                             uint32_t p_min );
288
289/******************************************************************************************
290 * This function implements the fbf_resize_window() syscall.
291 * It changes the <width> and <height> of a window identified by the <wid> argument.
292 * It updates the associated vseg "size" if required, but does not change the vseg "base".
293 * When the new window buffer is larger than the existing one, it is 0 filled.
294 * It can be called by any thread running in any cluster.
295 *
296 * Implementation note:
297 * 1.  it takes the lock protecting windows in write mode,
298 * 2.  it gives the modified window the lowest priority,
299 * 3.  it set the "hidden" flag in window descriptor,
300 * 4.  it refresh the FBF for the current window,
301 * 5.  it set the new size in the window descriptor,
302 * 6.  it resizes the associated vseg if required,
303 * 7.  if fill the window buffer extension with 0 if required,
304 * 8.  it gives the modified window the highest priority,
305 * 9.  it reset the "hidden" flag in window descriptor,
306 * 10. it refresh the FBF for the new window,
307 * 11. it releases the lock protecting windows,
308 * It does not call directly the FBF driver.
309 ******************************************************************************************
310 * @ wid       : [in] window index in window_tbl[].
311 * @ width     : [in] new number of pixels per line.
312 * @ height    : [in] new number of lines.
313 * @ returns 0 if success / returns -1 if illegal arguments.
314 *****************************************************************************************/
315error_t dev_fbf_resize_window( uint32_t wid,
316                               uint32_t width,
317                               uint32_t height );
318
319/******************************************************************************************
320 * This function implements the fbf_refresh_window() syscall.
321 * It allows an owner process to signal the windows manager that some lines of a window
322 * identified by the <wid>, <line_min>, and <line_max> argument have been modified, and
323 * must be refreshed in the FBF. It scans all the registered FBF windows to respect the
324 * overlap order defined by the windows xlist.
325 * It can be called by any thread running in any cluster.
326 *
327 * Implementation note:
328 * 1. it takes the lock protecting windows in read mode,
329 * 2. it refresh the FBF,
330 * 3. it releases the lock protecting windows,
331 * It does not call directly the FBF driver.
332 ******************************************************************************************
333 * @ wid        : [in] window index in window_tbl[]
334 * @ line_first : [in] first line index in window.
335 * @ line_last  : [in] last line index (excluded).
336 * @ returns 0 if success / returns -1 if wid not registered.
337 *****************************************************************************************/
338error_t dev_fbf_refresh_window( uint32_t wid,
339                                uint32_t line_first,
340                                uint32_t line_last );
341
342/******************************************************************************************
343 * WARNING : This function is deprecated ( january 2020 [AG] ). It was defined
344 * to implement the fbf_read() and fbf_write() deprecated syscalls.
345 *
346 * It  moves <length> bytes between the frame buffer, starting from pixel defined
347 * by the <offset> argument, and an user buffer defined by the <user_buffer> argument.
348 * The transfer direction are defined by the <is_write> argument.
349 * An error is returned when <offset> + <npixels> is larger than the FBF size.
350 * The request is registered in the client thread descriptor, but the client thread is
351 * not descheduled, and calls directly the FBF driver.
352 * It can be called by a client thread running in any cluster.
353 ******************************************************************************************
354 * @ is_write    : [in] write FBF weh true / read FBF when false
355 * @ user_buffer : [in] pointer on memory buffer in user space.
356 * @ npixels     : [in] number of bytes.
357 * @ offset      : [in] first byte in frame buffer.   
358 * @ returns 0 if success / returns -1 if error.
359 *****************************************************************************************/
360error_t dev_fbf_move_data( bool_t     is_write,
361                           void     * user_buffer,
362                           uint32_t   npixels,
363                           uint32_t   offset );
364
365#endif  /* _DEV_FBF_H */
Note: See TracBrowser for help on using the repository browser.