Changeset 657 for trunk/kernel/devices/dev_fbf.h
- Timestamp:
- Mar 18, 2020, 11:16:59 PM (4 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/kernel/devices/dev_fbf.h
r647 r657 1 1 /* 2 * dev_fbf.h - FBF ( Block Device Controler) generic device API definition.2 * dev_fbf.h - FBF (Frame Buffer) generic device API definition. 3 3 * 4 * Author Alain Greiner (2016,2017,2018,2019 )4 * Author Alain Greiner (2016,2017,2018,2019,2020) 5 5 * 6 6 * Copyright (c) UPMC Sorbonne Universites … … 27 27 #include <hal_kernel_types.h> 28 28 #include <shared_fbf.h> 29 #include <remote_rwlock.h> 30 #include <bits.h> 29 31 30 32 /**** Forward declarations ****/ … … 33 35 34 36 /***************************************************************************************** 35 * Generic Frame Buffer Controlerdefinition37 * Frame Buffer Controler API definition 36 38 * 37 39 * This device provide access to an external graphic display, that is seen 38 40 * as a fixed size frame buffer, mapped in the kernel address space. 39 * The supported pixel encoding types are defined in the <shared_fbf.h> file. 40 * 41 * It supports three command types: 42 * GET_CONFIG : return frame buffer size and type. 43 * READ : move bytes from frame buffer to memory / deschedule the calling thread. 44 * WRITE : move bytes from memory to frame buffer / deschedule the calling thread. 45 * 46 * The READ and WRITE operations do not use the FBF device waiting queue, 47 * the server thread, and the IOC IRQ. The client thread does not deschedule: 48 * it registers the command in the thread descriptor, and calls directly the FBF driver. 49 * that makes a (user <-> kernel) memcpy. 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. 50 65 * 51 * Note: As we don't use any external DMA to move data, but a purely software approach, 52 * there is no L2/L3 coherence issue. 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 * 53 93 *****************************************************************************************/ 54 94 … … 59 99 typedef struct fbf_extend_s 60 100 { 61 uint32_t width; /*! number of pixels per line. */ 62 uint32_t height; /*! total number of lines. */ 63 uint32_t subsampling; /*! pixel encoding type. */ 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. */ 64 110 } 65 111 fbf_extend_t; … … 70 116 *****************************************************************************************/ 71 117 72 enum fbf_impl_e 118 typedef enum 73 119 { 74 120 IMPL_FBF_SCL = 0, … … 77 123 fbf_impl_t; 78 124 125 /****************************************************************************************** 126 * This structure defines the FBF command for all drivers implementing the FBF device. 127 *****************************************************************************************/ 128 129 typedef 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 } 136 fbf_driver_cmd_type_t; 137 79 138 typedef struct fbf_command_s 80 139 { 81 140 xptr_t dev_xp; /*! extended pointer on device descriptor */ 82 uint32_t type; /*! requested operation type.*/83 uint32_t length;/*! number of bytes. */84 uint32_t offset; /*! offset in frame buffer ( bytes)*/85 void * buffer; /*! pointer on memory buffer in user space*/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) */ 86 145 uint32_t error; /*! operation status (0 if success) */ 87 146 } 88 147 fbf_command_t; 89 148 90 91 /****************************************************************************************** 92 * This function returns a printable string for a given FBF command <cmd_type>. 93 ****************************************************************************************** 94 * @ cmd_type : FBF command type (defined in shared_fbf.h file). 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 157 typedef 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 } 169 fbf_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). 95 176 * @ returns a string pointer. 96 177 *****************************************************************************************/ … … 100 181 * This function completes the FBF chdev descriptor initialisation. 101 182 * It calls the specific driver initialisation function, to initialise the hardware 102 * device and the chdev extension. It must be called by a local thread.183 * device, and the chdev extension. It must be called by a local thread. 103 184 ****************************************************************************************** 104 185 * @ chdev : pointer on FBF chdev descriptor. … … 107 188 108 189 /****************************************************************************************** 109 * This function returns the frame buffer size and type. 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. 110 192 * It does NOT access the hardware, as the size and type have been registered 111 * in the chdev descriptor extension. 193 * in the chdev descriptor extension by the dev_fbf_init() function. 194 * It can be called by any thread running in any cluster. 112 195 ****************************************************************************************** 113 196 * @ width : [out] number of pixels per line. … … 120 203 121 204 /****************************************************************************************** 122 * This blocking function moves <length> bytes between the frame buffer, starting from 123 * byte defined by <offset>, and an user buffer defined by the <user_buffer> argument. 124 * It can be called by a client thread running in any cluster. 125 * The transfer direction are defined by the <cmd_type> argument. 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 *****************************************************************************************/ 233 uint32_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 *****************************************************************************************/ 260 error_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 *****************************************************************************************/ 285 error_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 *****************************************************************************************/ 315 error_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 *****************************************************************************************/ 338 error_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. 126 350 * The request is registered in the client thread descriptor, but the client thread is 127 351 * not descheduled, and calls directly the FBF driver. 128 ****************************************************************************************** 129 * @ cmd_type : FBF_READ / FBF_WRITE / FBF_SYNC_READ / FBF_SYN_WRITE. 130 * @ user_buffer : pointer on memory buffer in user space. 131 * @ length : number of bytes. 132 * @ offset : first byte in frame buffer. 133 * @ returns 0 if success / returns EINVAL if error. 134 *****************************************************************************************/ 135 error_t dev_fbf_move_data( uint32_t cmd_type, 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 *****************************************************************************************/ 360 error_t dev_fbf_move_data( bool_t is_write, 136 361 void * user_buffer, 137 uint32_t length,362 uint32_t npixels, 138 363 uint32_t offset ); 139 364
Note: See TracChangeset
for help on using the changeset viewer.