source: trunk/kernel/devices/dev_fbf.h

Last change on this file was 674, checked in by alain, 3 years ago

1) Introduce up to 4 command lines arguments in the KSH "load" command.
These arguments are transfered to the user process through the
argc/argv mechanism, using the user space "args" vseg.

2) Introduce the named and anonymous "pipes", for inter-process communication
through the pipe() and mkfifo() syscalls.

3) Introduce the "chat" application to validate the two above mechanisms.

4) Improve printk() and assert() fonctions in printk.c.

File size: 23.1 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 ALMOS-MKH implementation (oct 2020)
42 * is one byte per pixel (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 * For these deprecated operations, the client thread calls
81 * directly the driver to move data between the user buffer and the FBF.
82 *
83 * 3) The FBF device defines defines four command types to access FBF driver(s) :
84 * - FBF_DRIVER_KERNEL_WRITE : move pixels from a kernel window to the FBF.
85 * - FBF_DRIVER_KERNEL_READ  : move pixels from the FBF to a kernel window.
86 * - FBF_DRIVER_USER_WRITE   : move bytes from an user buffer to the FBF.
87 * - FBF_DRIVER_USER_READ    : move bytes from the FBF to an user buffer.
88 *
89 * Note: As we don't use any external DMA to move data to or from the frame buffer,
90 * but only software memcpy, there is no L2/L3 coherence issue for this device.
91 *
92 *****************************************************************************************/
93
94/******************************************************************************************
95 * This defines the (implementation independant) extension for the generic FBF device.
96 *****************************************************************************************/
97
98typedef struct fbf_extend_s
99{
100    remote_rwlock_t windows_lock;        /*! lock protecting windows xlist               */
101    xlist_entry_t   windows_root;        /*! root of the windows xlist                   */
102
103    xptr_t          windows_tbl[CONFIG_FBF_WINDOWS_MAX_NR];         /*! window desc.     */
104    bitmap_t        windows_bitmap[CONFIG_FBF_WINDOWS_MAX_NR >> 5]; /*! wid allocator    */
105
106    uint32_t        width;               /*! Frame Buffer number of pixels per line.     */
107    uint32_t        height;              /*! Frame Buffer total number of lines.         */
108    uint32_t        subsampling;         /*! Frame Buffer pixel encoding type.           */
109}
110fbf_extend_t;
111
112/******************************************************************************************
113 * This enum defines the various implementations of the generic FBF peripheral.
114 * It must be kept consistent with the define in arch_info.h file.
115 *****************************************************************************************/
116
117typedef enum
118{
119    IMPL_FBF_SCL =   0,     
120    IMPL_FBF_I86 =   1, 
121} 
122fbf_impl_t;
123
124/******************************************************************************************
125 * This structure defines the FBF command for all drivers implementing the FBF device.
126 *****************************************************************************************/
127
128typedef enum
129{
130    FBF_DRIVER_USER_READ     = 1,
131    FBF_DRIVER_USER_WRITE    = 2,
132    FBF_DRIVER_KERNEL_READ   = 3,
133    FBF_DRIVER_KERNEL_WRITE  = 4,
134}
135fbf_driver_cmd_type_t;
136
137typedef struct fbf_command_s
138{
139    xptr_t      dev_xp;        /*! extended pointer on device descriptor                 */
140    uint32_t    type;          /*! requested driver operation type.                      */
141    uint32_t    npixels;       /*! number of bytes.                                      */
142    uint32_t    offset;        /*! offset in frame buffer (pixels)                       */
143    void      * buffer;        /*! pointer on memory buffer (kernel or user)             */
144    uint32_t    error;         /*! operation status (0 if success)                       */
145}
146fbf_command_t;
147
148/******************************************************************************************
149 * This structure defines an FBF window descriptor, allocated to a given user process.
150 * The window descriptor and the associated buffer are allocated in the cluster where
151 * is running the thread requesting the window creation.
152 * The <wid> allocator, the window_tbl[] array, and the root of the xlist of windows are
153 * imlemented in the FBF device extension.
154 *****************************************************************************************/
155
156typedef struct fbf_window_s
157{
158    pid_t          pid;         /*! owner process identifier                             */
159    uint32_t       wid;         /*! window identifier                                    */
160    uint32_t       height;      /*! number of lines in window                            */
161    uint32_t       width;       /*! number of pixels per line in window                  */
162    uint32_t       l_min;       /*! first line index in FBF                              */
163    uint32_t       p_min;       /*! first pixel index in FBF                             */
164    uint8_t      * buffer;      /*! pointer on buffer in user space                      */
165    bool_t         hidden;      /*! no display on FBF when true                          */
166    xlist_entry_t  xlist;       /*! member of registered FBF windows list                */
167}
168fbf_window_t;
169
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 checks that the calling process is the owner of the window identified
182 * by the <wid> argument, and returns an extended pointer on the window descriptor.
183 * It can be called by a thread running in any cluster.
184 ******************************************************************************************
185 * @ wid        :  FBF window kernel identifier.
186 * @ returns XPTR on the window if success / return XPT_NULL if not owner or undefined.
187 *****************************************************************************************/
188xptr_t dev_fbf_get_xptr_from_wid( uint32_t wid );
189
190/******************************************************************************************
191 * This function completes the FBF chdev descriptor initialisation.
192 * It calls the specific driver initialisation function, to initialise the hardware
193 * device, and the chdev extension. It must be called by a local thread.
194 ******************************************************************************************
195 * @ chdev      : pointer on FBF chdev descriptor.
196 *****************************************************************************************/
197void dev_fbf_init( struct chdev_s * chdev );
198
199/******************************************************************************************
200 * This function implements the fbf_get_config() syscall, and returns the FBF
201 * size and type. It can be called by a client thread running in any cluster.
202 * It does NOT access the hardware, as the size and type have been registered
203 * in the chdev descriptor extension by the dev_fbf_init() function.
204 * It can be called by any thread running in any cluster.
205 ******************************************************************************************
206 * @ width     : [out] number of pixels per line.
207 * @ height    : [out] total number of lines.
208 * @ type      : [out] pixel encoding type.
209 *****************************************************************************************/
210void dev_fbf_get_config( uint32_t  * width,
211                         uint32_t  * height,
212                         uint32_t  * type );
213
214/******************************************************************************************
215 * This function implements the fbf_create_window() syscall.
216 * It registers a new window in the windows_tbl[] array, and the windows list,
217 * registers in the reference cluster an ANON vseg, that will be mapped in local cluster.
218 * The window index <wid> is dynamically allocated. The owner is the calling process.
219 * The FBF window is defined by the <nlines>, <npixels>, <l_min>, <p_min> arguments.
220 * It can be called by any thread running in any cluster. As the vseg is not directly
221 * mapped to the frame buffer, the owner process can access this private buffer without
222 * syscall. As for any vseg, the physical memory is allocated on demand at each page fault.
223 * The created vseg base address in user space is returned in the <user_base> argument.
224 * The created window is set in "hidden" mode.
225 ******************************************************************************************
226 * Implementation note:
227 * 1. it allocates memory in the local cluster for the window descriptor,
228 * 2. it creates in the associated vseg,
229 * 3. it initializes the window descriptor,
230 * 4. it takes the lock protecting the windows in write mode,
231 * 5. it allocates a new  <wid>,
232 * 6. it registers the window in the window_tbl[] array,
233 * 7. it registers the window in the FBF rooted windows list,
234 * 8. it releases the lock protecting windows.
235 ******************************************************************************************
236 * @ nlines      : [in]  number of lines in window.
237 * @ npixels     : [in]  number of pixels per line in window.
238 * @ l_min       : [in]  first pixel index in FBF reference.
239 * @ p_min       : [in]  first line index in FBF reference.
240 * @ user_base   : [out] pointer on allocated buffer base in user space.
241 * @ return the <wid> index if success / returns -1 if failure
242 *****************************************************************************************/
243uint32_t dev_fbf_create_window( uint32_t   nlines,
244                                uint32_t   npixels,
245                                uint32_t   l_min,
246                                uint32_t   p_min,
247                                intptr_t * user_base );
248
249
250/******************************************************************************************
251 * This function implements the fbf_active_wiindow syscall. It set or reset the "hidden"
252*  flag for the window identified by the <wid> argument as specified by <active> argument.
253 ******************************************************************************************
254 * @ wid       : [in] window index in window_tbl[].
255 * @ active    : [in] set hidden flag if zero / rest hidden flag if non zero.
256 * @ returns 0 if success / returns -1 if wid not registered.
257 *****************************************************************************************/
258error_t dev_fbf_active_window( uint32_t wid,
259                               uint32_t active );
260
261/******************************************************************************************
262 * This function implements the fbf_delete_window() syscall to delete a FBF window,
263 * and release all memory allocated for this window and for the associated vseg.
264 * releases the memory allocated for the window buffer and for the window descriptor.
265 * It can be called by any thread running in any cluster.
266 ******************************************************************************************
267 * Implementation note:
268 * 1. it set the "hidden" flag in the window descriptor,
269 * 2. it refresh the window in FBF,
270 * 3. it takes the lock protecting windows in write mode,
271 * 4. it removes the window from windows_tbl[] array,
272 * 5. it removes the window from xlist,     
273 * 6. it releases the wid to bitmap,
274 * 7. it releases the lock protecting windows from write mode,
275 * 8. it releases the memory allocated for window descriptor,
276 * 9. it deletes the associated vseg in all clusters
277 ******************************************************************************************
278 * @ wid       : [in] window index in window_tbl[].
279 * @ returns 0 if success / returns -1 if wid not registered.
280 *****************************************************************************************/
281error_t dev_fbf_delete_window( uint32_t wid );
282                               
283/******************************************************************************************
284 * This function implements the fbf_move_window() syscall.
285 * It moves a window identified by the <wid> argument to a new position in the FBF,
286 * defined by the <l_min> and <p_min> arguments.
287 * It can be called by any thread running in any cluster.
288 ******************************************************************************************
289 * Implementation note:
290 * 1. it set the "hidden" flag in window descriptor,
291 * 2. it refresh the FBF for the current window position,
292 * 3. it takes the lock protecting windows in write mode,
293 * 4. it set the new coordinates in the window descriptor,
294 * 5. it gives the modified window the highest priority,
295 * 6. it releases the lock protecting windows,
296 * 7. it reset the "hidden" flag in window descriptor,
297 * 8. it refresh the FBF for the new window position,
298 ******************************************************************************************
299 * @ wid       : [in] window index in window_tbl[].
300 * @ l_min     : [in] new first pixel index in FBF reference.
301 * @ p_min     : [in] new first line index in FBF reference.
302 * @ returns 0 if success / returns -1 if illegal arguments.
303 *****************************************************************************************/
304error_t dev_fbf_move_window( uint32_t wid,
305                             uint32_t l_min,
306                             uint32_t p_min );
307
308/******************************************************************************************
309 * This function implements the fbf_resize_window() syscall.
310 * It changes the <width> and <height> of a window identified by the <wid> argument.
311 * It updates the associated vseg "size" if required, but does not change the vseg "base".
312 * When the new window buffer is larger than the existing one, it is 0 filled.
313 * It can be called by any thread running in any cluster.
314 ******************************************************************************************
315 * Implementation note:
316 * 1.  it set the "hidden" flag in window descriptor,
317 * 2.  it refresh the FBF for the current window,
318 * 3.  it takes the lock protecting windows in write mode,
319 * 4.  it set the new size in the window descriptor,
320 * 5.  it resizes the associated vseg if required,
321 * 6.  it fill the user buffer with zero if required,
322 * 7.  it gives the modified window the highest priority,
323 * 8.  it releases the lock protecting windows,
324 * 9.  it reset the "hidden" flag in window descriptor,
325 * 10. it refresh the FBF for the new window,
326 ******************************************************************************************
327 * @ wid       : [in] window index in window_tbl[].
328 * @ width     : [in] new number of pixels per line.
329 * @ height    : [in] new number of lines.
330 * @ returns 0 if success / returns -1 if illegal arguments.
331 *****************************************************************************************/
332error_t dev_fbf_resize_window( uint32_t wid,
333                               uint32_t width,
334                               uint32_t height );
335
336/******************************************************************************************
337 * This function implements the fbf_refresh_window() syscall.
338 * It allows an owner process to signal the windows manager that some lines of a window
339 * identified by the <wid>, <line_min>, and <line_max> argument have been modified, and
340 * must be refreshed in the FBF.
341 * It can be called by any thread running in any cluster.
342 ******************************************************************************************
343 * Implementation note:
344 * it simply checks the arguments, and calls the fbf_update() function.
345 ******************************************************************************************
346 * @ wid        : [in] window index in window_tbl[]
347 * @ line_min   : [in] first line index in window in window referencd.
348 * @ line_max   : [in] last line index in window in window reference (excluded).
349 * @ returns 0 if success / returns -1 if wid not registered.
350 *****************************************************************************************/
351error_t dev_fbf_refresh_window( uint32_t wid,
352                                uint32_t line_min,
353                                uint32_t line_max );
354
355/******************************************************************************************
356 * This function implements the fbf_front_window() syscall.
357 * It gives the highest priority to the window identified by the <wid> argument,
358 * and refresh the FBF accordingly.
359 * It can be called by any thread running in any cluster.
360 ******************************************************************************************
361 * Implementation note:
362 * 1. it takes the lock protecting windows in write mode,
363 * 2. it modify the xlist of windows rooted in FBF,
364 * 3. it releases the lock from write mode,
365 * 4. it refresh the window in FBF,
366 ******************************************************************************************
367 * @ wid        : [in] window index in window_tbl[]
368 * @ returns 0 if success / returns -1 if wid not registered.
369 *****************************************************************************************/
370error_t dev_fbf_front_window( uint32_t wid );
371
372/******************************************************************************************
373 * This function displays on the TXT0 kernel terminal the list of registered FBF windows
374 * rooted in the FBF device - in decreasing priority order - owned by the process
375 * identified by the <pid> argument. It displays all windows when pid value is 0.
376 * It can be called by any thread running in any cluster.
377 ******************************************************************************************
378 * @ pid       : [in] target process identifier / all processes when pid == 0
379 *****************************************************************************************/
380void dev_fbf_display_windows( pid_t pid );
381
382/******************************************************************************************
383 * This function deletes all FBF windows owned by the process identified by
384 * the <pid> argument. It can be called by any thread running in any cluster.
385 ******************************************************************************************
386 * @ pid       : [in] target process identifier.
387 *****************************************************************************************/
388void dev_fbf_cleanup( pid_t pid );
389
390
391
392
393
394
395
396/******************************************************************************************
397 * TODO : This function is deprecated ( january 2020 [AG] ). It was defined
398 * to implement the fbf_read() and fbf_write() deprecated syscalls.
399 ******************************************************************************************
400 * It  moves <length> bytes between the frame buffer, starting from pixel defined
401 * by the <offset> argument, and an user buffer defined by the <user_buffer> argument.
402 * The transfer direction are defined by the <is_write> argument.
403 * An error is returned when <offset> + <npixels> is larger than the FBF size.
404 * The request is registered in the client thread descriptor, but the client thread is
405 * not descheduled, and calls directly the FBF driver.
406 * It can be called by a client thread running in any cluster.
407 ******************************************************************************************
408 * @ is_write    : [in] write FBF weh true / read FBF when false
409 * @ user_buffer : [in] pointer on memory buffer in user space.
410 * @ npixels     : [in] number of bytes.
411 * @ offset      : [in] first byte in frame buffer.   
412 * @ returns 0 if success / returns -1 if error.
413 *****************************************************************************************/
414error_t dev_fbf_move_data( bool_t     is_write,
415                           void     * user_buffer,
416                           uint32_t   npixels,
417                           uint32_t   offset );
418
419#endif  /* _DEV_FBF_H */
Note: See TracBrowser for help on using the repository browser.