Update the BSP howto.

Closes #2590.

1 files changed, 167 insertions, 142 deletions

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.