From 6d7a4d2ee7053488f625faccc8bd4dc4d25d6460 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 17 Jun 2016 15:05:41 +1000 Subject: Update the BSP howto. Closes #2590. --- bsp_howto/frame_buffer.rst | 309 ++++++++++++++++++++++++--------------------- 1 file changed, 167 insertions(+), 142 deletions(-) (limited to 'bsp_howto/frame_buffer.rst') diff --git a/bsp_howto/frame_buffer.rst b/bsp_howto/frame_buffer.rst index e7a8ce8..006191c 100644 --- a/bsp_howto/frame_buffer.rst +++ b/bsp_howto/frame_buffer.rst @@ -1,29 +1,40 @@ .. comment SPDX-License-Identifier: CC-BY-SA-4.0 +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Frame Buffer Driver ################### -In this chapter, we present the basic functionality implemented by a -frame buffer driver: ``frame_buffer_initialize()``, ``frame_buffer_open()``,``frame_buffer_close()``, ``frame_buffer_read()``, ``frame_buffer_write()`` -and ``frame_buffer_control()``. +In this chapter, we present the basic functionality implemented by a frame +buffer driver: + +- ``frame_buffer_initialize()`` +- ``frame_buffer_open()`` +- ``frame_buffer_close()`` +- ``frame_buffer_read()`` +- ``frame_buffer_write()`` +- ``frame_buffer_control()`` Introduction ============ The purpose of the frame buffer driver is to provide an abstraction for -graphics hardware. -By using the frame buffer interface, an application can display graphics -without knowing anything about the low-level details of interfacing to a -particular graphics adapter. The parameters governing the mapping of -memory to displayed pixels (planar or linear, bit depth, etc) is still -implementation-specific, but device-independent methods are provided to +graphics hardware. By using the frame buffer interface, an application can +display graphics without knowing anything about the low-level details of +interfacing to a particular graphics adapter. The parameters governing the +mapping of memory to displayed pixels (planar or linear, bit depth, etc) is +still implementation-specific, but device-independent methods are provided to determine and potentially modify these parameters. -The frame buffer driver is commonly located in the ``console`` -directory of the BSP and registered by the name */dev/fb0*. -Additional frame buffers (if available) are named */dev/fb1*,*/dev/fb2*, etc. +The frame buffer driver is commonly located in the ``console`` directory of the +BSP and registered by the name :file:`/dev/fb0`. Additional frame buffers (if +available) are named :file:`/dev/fb1*,*/dev/fb2`, etc. -To work with the frame buffer, the following operation sequence is used:``open()``, ``ioctls()`` to get the frame buffer info, ``read()`` and/or``write()``, and ``close()``. +To work with the frame buffer, the following operation sequence is +used:``open()``, ``ioctls()`` to get the frame buffer info, ``read()`` +and/or ``write()``, and ``close()``. Driver Function Overview ======================== @@ -32,69 +43,77 @@ Initialization -------------- The driver initialization is called once during the RTEMS initialization -process and returns RTEMS_SUCCESSFUL when the device driver is successfully -initialized. During the initialization, a name is assigned to the frame -buffer device. If the graphics hardware supports console text output, -as is the case with the pc386 VGA hardware, initialization into graphics -mode may be deferred until the device is ``open()`` ed. +process and returns ``RTEMS_SUCCESSFUL`` when the device driver is successfully +initialized. During the initialization, a name is assigned to the frame buffer +device. If the graphics hardware supports console text output, as is the case +with the pc386 VGA hardware, initialization into graphics mode may be deferred +until the device is ``open()`` ed. The ``frame_buffer_initialize()`` function may look like this: -.. code:: c +.. code-block:: c rtems_device_driver frame_buffer_initialize( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg) + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg) { - rtems_status_code status; - printk( "frame buffer driver initializing..\\n" ); - /* - * Register the device - \*/ - status = rtems_io_register_name("/dev/fb0", major, 0); - if (status != RTEMS_SUCCESSFUL) - { - printk("Error registering frame buffer device!\\n"); - rtems_fatal_error_occurred( status ); - } - /* - * graphics hardware initialization goes here for non-console - * devices - \*/ - return RTEMS_SUCCESSFUL; + rtems_status_code status; + + printk( "frame buffer driver initializing..\n" ); + + /* + * Register the device + */ + status = rtems_io_register_name("/dev/fb0", major, 0); + if (status != RTEMS_SUCCESSFUL) + { + printk("Error registering frame buffer device!\n"); + rtems_fatal_error_occurred( status ); + } + + /* + * graphics hardware initialization goes here for non-console + * devices + */ + + return RTEMS_SUCCESSFUL; } Opening the Frame Buffer Device ------------------------------- -The ``frame_buffer_open()`` function is called whenever a frame buffer device is opened. -If the frame buffer is registered as "/dev/fb0", the ``frame_buffer_open`` entry point -will be called as the result of an ``open("/dev/fb0", mode)`` in the application. +The ``frame_buffer_open()`` function is called whenever a frame buffer device +is opened. If the frame buffer is registered as :file:`/dev/fb0`, the +``frame_buffer_open`` entry point will be called as the result of an +``open("/dev/fb0", mode)`` in the application. + +Thread safety of the frame buffer driver is implementation-dependent. The VGA +driver shown below uses a mutex to prevent multiple open() operations of the +frame buffer device. -Thread safety of the frame buffer driver is implementation-dependent. -The VGA driver shown below uses a mutex to prevent multiple open() -operations of the frame buffer device. +The ``frame_buffer_open()`` function returns ``RTEMS_SUCCESSFUL`` when the +device driver is successfully opened, and ``RTEMS_UNSATISFIED`` if the device +is already open: -The ``frame_buffer_open()`` function returns RTEMS_SUCCESSFUL when the device driver -is successfully opened, and RTEMS_UNSATISFIED if the device is already open: -.. code:: c +.. code-block:: c rtems_device_driver frame_buffer_close( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg ) { - if (pthread_mutex_unlock(&mutex) == 0){ - /* restore previous state. for VGA this means return to text mode. - * leave out if graphics hardware has been initialized in - * frame_buffer_initialize() \*/ - ega_hwterm(); - printk( "FBVGA close called.\\n" ); - return RTEMS_SUCCESSFUL; - } - return RTEMS_UNSATISFIED; + if (pthread_mutex_unlock(&mutex) == 0) { + /* restore previous state. for VGA this means return to text mode. + * leave out if graphics hardware has been initialized in + * frame_buffer_initialize() + */ + ega_hwterm(); + printk( "FBVGA close called.\n" ); + return RTEMS_SUCCESSFUL; + } + return RTEMS_UNSATISFIED; } In the previous example, the function ``ega_hwinit()`` takes care of @@ -103,82 +122,92 @@ hardware-specific initialization. Closing the Frame Buffer Device ------------------------------- -The ``frame_buffer_close()`` is invoked when the frame buffer device -is closed. It frees up any resources allocated in``frame_buffer_open()``, and should restore previous hardware state. -The entry point corresponds to the device driver close entry point. +The ``frame_buffer_close()`` is invoked when the frame buffer device is closed. +It frees up any resources allocated in ``frame_buffer_open()``, and should +restore previous hardware state. The entry point corresponds to the device +driver close entry point. + +Returns ``RTEMS_SUCCESSFUL`` when the device driver is successfully closed: -Returns RTEMS_SUCCESSFUL when the device driver is successfully closed: -.. code:: c +.. code-block:: c rtems_device_driver frame_buffer_close( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg) + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg) { - pthread_mutex_unlock(&mutex); - /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed. we - * don't want to unconditionally call ega_hwterm()... \*/ - /* restore previous state. for VGA this means return to text mode. - * leave out if graphics hardware has been initialized in - * frame_buffer_initialize() \*/ - ega_hwterm(); - printk( "frame buffer close called.\\n" ); - return RTEMS_SUCCESSFUL; + pthread_mutex_unlock(&mutex); + + /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed. we + * don't want to unconditionally call ega_hwterm()... */ + /* restore previous state. for VGA this means return to text mode. + * leave out if graphics hardware has been initialized in + * frame_buffer_initialize() */ + ega_hwterm(); + printk( "frame buffer close called.\n" ); + return RTEMS_SUCCESSFUL; } Reading from the Frame Buffer Device ------------------------------------ -The ``frame_buffer_read()`` is invoked from a ``read()`` operation -on the frame buffer device. -Read functions should allow normal and partial reading at the end of frame buffer memory. -This method returns RTEMS_SUCCESSFUL when the device is successfully read from: -.. code:: c +The ``frame_buffer_read()`` is invoked from a ``read()`` operation on the frame +buffer device. Read functions should allow normal and partial reading at the +end of frame buffer memory. This method returns ``RTEMS_SUCCESSFUL`` when the +device is successfully read from: + +.. code-block:: c rtems_device_driver frame_buffer_read( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg ) { - rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg; - rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count; - memcpy(rw_args->buffer, (const void \*) (fb_fix.smem_start + rw_args->offset), rw_args->bytes_moved); - return RTEMS_SUCCESSFUL; + rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg; + rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? + (fb_fix.smem_len - rw_args->offset) : rw_args->count; + memcpy(rw_args->buffer, + (const void *) (fb_fix.smem_start + rw_args->offset), + rw_args->bytes_moved); + return RTEMS_SUCCESSFUL; } Writing to the Frame Buffer Device ---------------------------------- -The ``frame_buffer_write()`` is invoked from a ``write()`` -operation on the frame buffer device. -The frame buffer write function is similar to the read function, and -should handle similar cases involving partial writes. +The ``frame_buffer_write()`` is invoked from a ``write()`` operation on the +frame buffer device. The frame buffer write function is similar to the read +function, and should handle similar cases involving partial writes. -This method returns RTEMS_SUCCESSFUL when the device is successfully +This method returns ``RTEMS_SUCCESSFUL`` when the device is successfully written to: -.. code:: c + +.. code-block:: c rtems_device_driver frame_buffer_write( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg ) { - rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg; - rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count; - memcpy( (void \*) (fb_fix.smem_start + rw_args->offset), rw_args->buffer, rw_args->bytes_moved); - return RTEMS_SUCCESSFUL; + rtems_libio_rw_args_t *rw_args = (rtems_libio_rw_args_t *)arg; + rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? + (fb_fix.smem_len - rw_args->offset) : rw_args->count; + memcpy((void *) (fb_fix.smem_start + rw_args->offset), + rw_args->buffer, + rw_args->bytes_moved); + return RTEMS_SUCCESSFUL; } Frame Buffer IO Control ----------------------- -The frame buffer driver allows several ioctls, partially compatible with -the Linux kernel, -to obtain information about the hardware. +The frame buffer driver allows several ioctls, partially compatible with the +Linux kernel, to obtain information about the hardware. -All ``ioctl()`` operations on the frame buffer device invoke``frame_buffer_control()``. +All ``ioctl()`` operations on the frame buffer device invoke +``frame_buffer_control()``. Ioctls supported: @@ -186,46 +215,42 @@ Ioctls supported: - ioctl to set and get palette. -.. code:: c +.. code-block:: c rtems_device_driver frame_buffer_control( - rtems_device_major_number major, - rtems_device_minor_number minor, - void \*arg + rtems_device_major_number major, + rtems_device_minor_number minor, + void *arg ) { - rtems_libio_ioctl_args_t \*args = arg; - printk( "FBVGA ioctl called, cmd=%x\\n", args->command ); - switch( args->command ) { - case FBIOGET_FSCREENINFO: - args->ioctl_return = get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer ); - break; - case FBIOGET_VSCREENINFO: - args->ioctl_return = get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer ); - break; - case FBIOPUT_VSCREENINFO: - /* not implemented yet*/ - args->ioctl_return = -1; - return RTEMS_UNSATISFIED; - case FBIOGETCMAP: - args->ioctl_return = get_palette( ( struct fb_cmap * ) args->buffer ); - break; - case FBIOPUTCMAP: - args->ioctl_return = set_palette( ( struct fb_cmap * ) args->buffer ); - break; - default: - args->ioctl_return = 0; - break; - } - return RTEMS_SUCCESSFUL; + rtems_libio_ioctl_args_t *args = arg; + + printk( "FBVGA ioctl called, cmd=%x\n", args->command ); + + switch( args->command ) { + case FBIOGET_FSCREENINFO: + args->ioctl_return = get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer ); + break; + case FBIOGET_VSCREENINFO: + args->ioctl_return = get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer ); + break; + case FBIOPUT_VSCREENINFO: + /* not implemented yet*/ + args->ioctl_return = -1; + return RTEMS_UNSATISFIED; + case FBIOGETCMAP: + args->ioctl_return = get_palette( ( struct fb_cmap * ) args->buffer ); + break; + case FBIOPUTCMAP: + args->ioctl_return = set_palette( ( struct fb_cmap * ) args->buffer ); + break; + default: + args->ioctl_return = 0; + break; + } + + return RTEMS_SUCCESSFUL; } -See ``rtems/fb.h`` for more information on the list of ioctls and -data structures they work with. - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - +See ``rtems/fb.h`` for more information on the list of ioctls and data +structures they work with. -- cgit v1.2.3