/* * dev_fbf.h - FBF (Frame Buffer) generic device API definition. * * Author Alain Greiner (2016,2017,2018,2019,2020) * * Copyright (c) UPMC Sorbonne Universites * * This file is part of ALMOS-MKH * * ALMOS-MKH is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by * the Free Software Foundation; version 2.0 of the License. * * ALMOS-MKH is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with ALMOS-kernel; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef _DEV_FBF_H #define _DEV_FBF_H #include #include #include #include /**** Forward declarations ****/ struct chdev_s; /***************************************************************************************** * Frame Buffer Controler API definition * * 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 ALMOS-MKH implementation (oct 2020) * is one byte per pixel (256 levels of gray). * * It supports a first API, for the user syscalls, implementing a simple 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 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 as a windows_tbl[] array, indexed by the window identifier (wid), and each 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). * * To refresh a window , the owner process calls the dev_fbf_refresh_window() * function, that sends parallel RPC_FBF_DISPLAY requests to other cores. All cores * synchronously execute the dev_fbf_display() function. This function scan all windows * to respect the overlaping order, and updates all pixels of the window. * * 1) This "syscall" API defines five syscalls : * - FBF_GET_CONFIG : returns the FBF width, height, and pixel encoding type. * - FBF_CREATE_WINDOW : create a new window , owned by the calling process. * - FBF_DELETE_WINDOW : delete a registered window. * - FBF_MOVE_WINDOW : move in FBF a registered window. * - FBF_REFRESH_WINDOW : request refresh of a given window. * * These 5 operations do not use the FBF device waiting queue, the associated * device thread and the FBF IRQ, as the client thread does NOT deschedule, * and does NOT call the FBF driver. * * 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. * * 3) 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't use any external DMA to move data to or from the frame buffer, * but only software memcpy, there is no L2/L3 coherence issue for this device. * *****************************************************************************************/ /****************************************************************************************** * This defines the (implementation independant) extension for the generic FBF device. *****************************************************************************************/ typedef struct fbf_extend_s { remote_rwlock_t windows_lock; /*! lock protecting windows xlist */ xlist_entry_t windows_root; /*! root of the windows xlist */ xptr_t windows_tbl[CONFIG_FBF_WINDOWS_MAX_NR]; /*! window desc. */ bitmap_t windows_bitmap[CONFIG_FBF_WINDOWS_MAX_NR >> 5]; /*! wid allocator */ uint32_t width; /*! Frame Buffer number of pixels per line. */ uint32_t height; /*! Frame Buffer total number of lines. */ uint32_t subsampling; /*! Frame Buffer pixel encoding type. */ } fbf_extend_t; /****************************************************************************************** * This enum defines the various implementations of the generic FBF peripheral. * It must be kept consistent with the define in arch_info.h file. *****************************************************************************************/ typedef enum { IMPL_FBF_SCL = 0, IMPL_FBF_I86 = 1, } fbf_impl_t; /****************************************************************************************** * This structure defines the FBF command for all drivers implementing the FBF device. *****************************************************************************************/ typedef enum { FBF_DRIVER_USER_READ = 1, FBF_DRIVER_USER_WRITE = 2, FBF_DRIVER_KERNEL_READ = 3, FBF_DRIVER_KERNEL_WRITE = 4, } fbf_driver_cmd_type_t; typedef struct fbf_command_s { xptr_t dev_xp; /*! extended pointer on device descriptor */ uint32_t type; /*! requested driver operation type. */ uint32_t npixels; /*! number of bytes. */ uint32_t offset; /*! offset in frame buffer (pixels) */ void * buffer; /*! pointer on memory buffer (kernel or user) */ uint32_t error; /*! operation status (0 if success) */ } fbf_command_t; /****************************************************************************************** * This structure defines an FBF window descriptor, allocated to a given user process. * The window descriptor and the associated buffer are allocated in the cluster where * is running the thread requesting the window creation. * The allocator, the window_tbl[] array, and the root of the xlist of windows are * imlemented in the FBF device extension. *****************************************************************************************/ typedef struct fbf_window_s { pid_t pid; /*! owner process identifier */ uint32_t wid; /*! window identifier */ uint32_t height; /*! number of lines in window */ uint32_t width; /*! number of pixels per line in window */ uint32_t l_min; /*! first line index in FBF */ uint32_t p_min; /*! first pixel index in FBF */ uint8_t * buffer; /*! pointer on buffer in user space */ bool_t hidden; /*! no display on FBF when true */ xlist_entry_t xlist; /*! member of registered FBF windows list */ } fbf_window_t; /****************************************************************************************** * This function returns a printable string for a given FBF user command . * WARNING : It must be kept consistent with the enum in the file ****************************************************************************************** * @ cmd_type : FBF user command type (defined in shared_fbf.h file). * @ returns a string pointer. *****************************************************************************************/ char * dev_fbf_cmd_str( uint32_t cmd_type ); /****************************************************************************************** * This function checks that the calling process is the owner of the window identified * by the argument, and returns an extended pointer on the window descriptor. * It can be called by a thread running in any cluster. ****************************************************************************************** * @ wid : FBF window kernel identifier. * @ returns XPTR on the window if success / return XPT_NULL if not owner or undefined. *****************************************************************************************/ xptr_t dev_fbf_get_xptr_from_wid( uint32_t wid ); /****************************************************************************************** * This function completes the FBF chdev descriptor initialisation. * It calls the specific driver initialisation function, to initialise the hardware * device, and the chdev extension. It must be called by a local thread. ****************************************************************************************** * @ chdev : pointer on FBF chdev descriptor. *****************************************************************************************/ void dev_fbf_init( struct chdev_s * chdev ); /****************************************************************************************** * This function implements the fbf_get_config() syscall, and returns the FBF * size and 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. * It can be called by any thread running in any cluster. ****************************************************************************************** * @ width : [out] number of pixels per line. * @ height : [out] total number of lines. * @ type : [out] pixel encoding type. *****************************************************************************************/ void dev_fbf_get_config( uint32_t * width, uint32_t * height, uint32_t * type ); /****************************************************************************************** * This function implements the fbf_create_window() syscall. * It registers a new window in the windows_tbl[] array, and the windows list, * registers in the reference cluster an ANON vseg, that will be mapped in local cluster. * The window index is dynamically allocated. The owner is the calling process. * The FBF window is defined by the , , , arguments. * It can be called by any thread running in any cluster. As the vseg is not directly * mapped to the frame buffer, the owner process can access this private buffer without * syscall. As for any vseg, the physical memory is allocated on demand at each page fault. * The created vseg base address in user space is returned in the argument. * The created window is set in "hidden" mode. ****************************************************************************************** * Implementation note: * 1. it allocates memory in the local cluster for the window descriptor, * 2. it creates in the associated vseg, * 3. it initializes the window descriptor, * 4. it takes the lock protecting the windows in write mode, * 5. it allocates a new , * 6. it registers the window in the window_tbl[] array, * 7. it registers the window in the FBF rooted windows list, * 8. it releases the lock protecting windows. ****************************************************************************************** * @ nlines : [in] number of lines in window. * @ npixels : [in] number of pixels per line in window. * @ l_min : [in] first pixel index in FBF reference. * @ p_min : [in] first line index in FBF reference. * @ user_base : [out] pointer on allocated buffer base in user space. * @ return the index if success / returns -1 if failure *****************************************************************************************/ uint32_t dev_fbf_create_window( uint32_t nlines, uint32_t npixels, uint32_t l_min, uint32_t p_min, intptr_t * user_base ); /****************************************************************************************** * This function implements the fbf_active_wiindow syscall. It set or reset the "hidden" * flag for the window identified by the argument as specified by argument. ****************************************************************************************** * @ wid : [in] window index in window_tbl[]. * @ active : [in] set hidden flag if zero / rest hidden flag if non zero. * @ returns 0 if success / returns -1 if wid not registered. *****************************************************************************************/ error_t dev_fbf_active_window( uint32_t wid, uint32_t active ); /****************************************************************************************** * This function implements the fbf_delete_window() syscall to delete a FBF window, * and release all memory allocated for this window and for the associated vseg. * releases the memory allocated for the window buffer and for the window descriptor. * It can be called by any thread running in any cluster. ****************************************************************************************** * Implementation note: * 1. it set the "hidden" flag in the window descriptor, * 2. it refresh the window in FBF, * 3. it takes the lock protecting windows in write mode, * 4. it removes the window from windows_tbl[] array, * 5. it removes the window from xlist, * 6. it releases the wid to bitmap, * 7. it releases the lock protecting windows from write mode, * 8. it releases the memory allocated for window descriptor, * 9. it deletes the associated vseg in all clusters ****************************************************************************************** * @ wid : [in] window index in window_tbl[]. * @ returns 0 if success / returns -1 if wid not registered. *****************************************************************************************/ error_t dev_fbf_delete_window( uint32_t wid ); /****************************************************************************************** * This function implements the fbf_move_window() syscall. * It moves a window identified by the argument to a new position in the FBF, * defined by the and arguments. * It can be called by any thread running in any cluster. ****************************************************************************************** * Implementation note: * 1. it set the "hidden" flag in window descriptor, * 2. it refresh the FBF for the current window position, * 3. it takes the lock protecting windows in write mode, * 4. it set the new coordinates in the window descriptor, * 5. it gives the modified window the highest priority, * 6. it releases the lock protecting windows, * 7. it reset the "hidden" flag in window descriptor, * 8. it refresh the FBF for the new window position, ****************************************************************************************** * @ wid : [in] window index in window_tbl[]. * @ l_min : [in] new first pixel index in FBF reference. * @ p_min : [in] new first line index in FBF reference. * @ returns 0 if success / returns -1 if illegal arguments. *****************************************************************************************/ error_t dev_fbf_move_window( uint32_t wid, uint32_t l_min, uint32_t p_min ); /****************************************************************************************** * This function implements the fbf_resize_window() syscall. * It changes the and of a window identified by the argument. * It updates the associated vseg "size" if required, but does not change the vseg "base". * When the new window buffer is larger than the existing one, it is 0 filled. * It can be called by any thread running in any cluster. ****************************************************************************************** * Implementation note: * 1. it set the "hidden" flag in window descriptor, * 2. it refresh the FBF for the current window, * 3. it takes the lock protecting windows in write mode, * 4. it set the new size in the window descriptor, * 5. it resizes the associated vseg if required, * 6. it fill the user buffer with zero if required, * 7. it gives the modified window the highest priority, * 8. it releases the lock protecting windows, * 9. it reset the "hidden" flag in window descriptor, * 10. it refresh the FBF for the new window, ****************************************************************************************** * @ wid : [in] window index in window_tbl[]. * @ width : [in] new number of pixels per line. * @ height : [in] new number of lines. * @ returns 0 if success / returns -1 if illegal arguments. *****************************************************************************************/ error_t dev_fbf_resize_window( uint32_t wid, uint32_t width, uint32_t height ); /****************************************************************************************** * This function implements the fbf_refresh_window() syscall. * It allows an owner process to signal the windows manager that some lines of a window * identified by the , , and argument have been modified, and * must be refreshed in the FBF. * It can be called by any thread running in any cluster. ****************************************************************************************** * Implementation note: * it simply checks the arguments, and calls the fbf_update() function. ****************************************************************************************** * @ wid : [in] window index in window_tbl[] * @ line_min : [in] first line index in window in window referencd. * @ line_max : [in] last line index in window in window reference (excluded). * @ returns 0 if success / returns -1 if wid not registered. *****************************************************************************************/ error_t dev_fbf_refresh_window( uint32_t wid, uint32_t line_min, uint32_t line_max ); /****************************************************************************************** * This function implements the fbf_front_window() syscall. * It gives the highest priority to the window identified by the argument, * and refresh the FBF accordingly. * It can be called by any thread running in any cluster. ****************************************************************************************** * Implementation note: * 1. it takes the lock protecting windows in write mode, * 2. it modify the xlist of windows rooted in FBF, * 3. it releases the lock from write mode, * 4. it refresh the window in FBF, ****************************************************************************************** * @ wid : [in] window index in window_tbl[] * @ returns 0 if success / returns -1 if wid not registered. *****************************************************************************************/ error_t dev_fbf_front_window( uint32_t wid ); /****************************************************************************************** * This function displays on the TXT0 kernel terminal the list of registered FBF windows * rooted in the FBF device - in decreasing priority order - owned by the process * identified by the argument. It displays all windows when pid value is 0. * It can be called by any thread running in any cluster. ****************************************************************************************** * @ pid : [in] target process identifier / all processes when pid == 0 *****************************************************************************************/ void dev_fbf_display_windows( pid_t pid ); /****************************************************************************************** * This function deletes all FBF windows owned by the process identified by * the argument. It can be called by any thread running in any cluster. ****************************************************************************************** * @ pid : [in] target process identifier. *****************************************************************************************/ void dev_fbf_cleanup( pid_t pid ); /****************************************************************************************** * TODO : This function is deprecated ( january 2020 [AG] ). It was defined * to implement the fbf_read() and fbf_write() deprecated syscalls. ****************************************************************************************** * It moves bytes between the frame buffer, starting from pixel defined * by the argument, and an user buffer defined by the argument. * The transfer direction are defined by the argument. * An error is returned when + is larger than the FBF size. * The request is registered in the client thread descriptor, but the client thread is * not descheduled, and calls directly the FBF driver. * It can be called by a client thread running in any cluster. ****************************************************************************************** * @ is_write : [in] write FBF weh true / read FBF when false * @ user_buffer : [in] pointer on memory buffer in user space. * @ npixels : [in] number of bytes. * @ offset : [in] first byte in frame buffer. * @ returns 0 if success / returns -1 if error. *****************************************************************************************/ error_t dev_fbf_move_data( bool_t is_write, void * user_buffer, uint32_t npixels, uint32_t offset ); #endif /* _DEV_FBF_H */