Ignore:
Timestamp:
Mar 18, 2020, 11:16:59 PM (23 months ago)
Author:
alain
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/kernel/devices/dev_fbf.h

    r647 r657  
    11/*
    2  * dev_fbf.h - FBF (Block Device Controler) generic device API definition.
     2 * dev_fbf.h - FBF (Frame Buffer) generic device API definition.
    33 *
    4  * Author  Alain Greiner    (2016,2017,2018,2019)
     4 * Author  Alain Greiner    (2016,2017,2018,2019,2020)
    55 *
    66 * Copyright (c) UPMC Sorbonne Universites
     
    2727#include <hal_kernel_types.h>
    2828#include <shared_fbf.h>
     29#include <remote_rwlock.h>
     30#include <bits.h>
    2931
    3032/****  Forward declarations  ****/
     
    3335
    3436/*****************************************************************************************
    35  *     Generic Frame Buffer Controler definition
     37 *      Frame Buffer Controler API definition
    3638 *
    3739 * This device provide access to an external graphic display, that is seen
    3840 * 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.
    5065 *
    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 *
    5393 *****************************************************************************************/
    5494
     
    5999typedef struct fbf_extend_s
    60100{
    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.                        */
    64110}
    65111fbf_extend_t;
     
    70116 *****************************************************************************************/
    71117
    72 enum fbf_impl_e
     118typedef enum
    73119{
    74120    IMPL_FBF_SCL =   0,     
     
    77123fbf_impl_t;
    78124
     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
    79138typedef struct fbf_command_s
    80139{
    81140    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)             */
    86145    uint32_t    error;         /*! operation status (0 if success)                       */
    87146}
    88147fbf_command_t;
    89148
    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
     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).
    95176 * @ returns a string pointer.
    96177 *****************************************************************************************/
     
    100181 * This function completes the FBF chdev descriptor initialisation.
    101182 * 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.
    103184 ******************************************************************************************
    104185 * @ chdev      : pointer on FBF chdev descriptor.
     
    107188
    108189/******************************************************************************************
    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.
    110192 * 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.
    112195 ******************************************************************************************
    113196 * @ width     : [out] number of pixels per line.
     
    120203
    121204/******************************************************************************************
    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 *****************************************************************************************/
     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.
    126350 * The request is registered in the client thread descriptor, but the client thread is
    127351 * 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 *****************************************************************************************/
     360error_t dev_fbf_move_data( bool_t     is_write,
    136361                           void     * user_buffer,
    137                            uint32_t   length,
     362                           uint32_t   npixels,
    138363                           uint32_t   offset );
    139364
Note: See TracChangeset for help on using the changeset viewer.