summaryrefslogtreecommitdiffstats
path: root/doc/bsp_howto/framebuffer.t
diff options
context:
space:
mode:
Diffstat (limited to 'doc/bsp_howto/framebuffer.t')
-rw-r--r--doc/bsp_howto/framebuffer.t251
1 files changed, 0 insertions, 251 deletions
diff --git a/doc/bsp_howto/framebuffer.t b/doc/bsp_howto/framebuffer.t
deleted file mode 100644
index 846194c843..0000000000
--- a/doc/bsp_howto/framebuffer.t
+++ /dev/null
@@ -1,251 +0,0 @@
-@c
-@c COPYRIGHT (c) 1988-2009.
-@c On-Line Applications Research Corporation (OAR).
-@c All rights reserved.
-
-@chapter Frame Buffer Driver
-
-In this chapter, we present the basic functionality implemented by a
-frame buffer driver: @code{frame_buffer_initialize()}, @code{frame_buffer_open()},
-@code{frame_buffer_close()}, @code{frame_buffer_read()}, @code{frame_buffer_write()}
-and @code{frame_buffer_control()}.
-
-@section 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
-determine and potentially modify these parameters.
-
-The frame buffer driver is commonly located in the @code{console}
-directory of the BSP and registered by the name @b{/dev/fb0}.
-Additional frame buffers (if available) are named @b{/dev/fb1},
-@b{/dev/fb2}, etc.
-
-To work with the frame buffer, the following operation sequence is used:
-@code{open()}, @code{ioctls()} to get the frame buffer info, @code{read()} and/or
-@code{write()}, and @code{close()}.
-
-@section Driver Function Overview
-
-@subsection 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 @code{open()}ed.
-
-The @code{frame_buffer_initialize()} function may look like this:
-
-@example
-@group
-rtems_device_driver frame_buffer_initialize(
- 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;
-@}
-@end group
-@end example
-
-@subsection Opening the Frame Buffer Device
-
-The @code{frame_buffer_open()} function is called whenever a frame buffer device is opened.
-If the frame buffer is registered as "/dev/fb0", the @code{frame_buffer_open} entry point
-will be called as the result of an @code{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.
-
-The @code{frame_buffer_open()} function returns RTEMS_SUCCESSFUL when the device driver
-is successfully opened, and RTEMS_UNSATISFIED if the device is already open:
-
-@example
-@group
-rtems_device_driver frame_buffer_close(
- 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;
-@}
-@end group
-@end example
-
-In the previous example, the function @code{ega_hwinit()} takes care of
-hardware-specific initialization.
-
-@subsection Closing the Frame Buffer Device
-
-The @code{frame_buffer_close()} is invoked when the frame buffer device
-is closed. It frees up any resources allocated in
-@code{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:
-
-@example
-@group
-rtems_device_driver frame_buffer_close(
- 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;
-@}
-
-@end group
-@end example
-
-
-@subsection Reading from the Frame Buffer Device
-
-The @code{frame_buffer_read()} is invoked from a @code{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:
-
-@example
-@group
-rtems_device_driver frame_buffer_read(
- 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;
-@}
-@end group
-@end example
-
-@subsection Writing to the Frame Buffer Device
-
-The @code{frame_buffer_write()} is invoked from a @code{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
-written to:
-
-@example
-@group
-rtems_device_driver frame_buffer_write(
- 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;
-@}
-@end group
-@end example
-
-
-@subsection Frame Buffer IO Control
-
-The frame buffer driver allows several ioctls, partially compatible with
-the Linux kernel,
-to obtain information about the hardware.
-
-All @code{ioctl()} operations on the frame buffer device invoke
-@code{frame_buffer_control()}.
-
-Ioctls supported:
-@itemize @bullet
-@item ioctls to get the frame buffer screen info (fixed and variable).
-@item ioctl to set and get palette.
-@end itemize
-
-@example
-@group
-rtems_device_driver frame_buffer_control(
- 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;
-@}
-@end group
-@end example
-
-See @code{rtems/fb.h} for more information on the list of ioctls and
-data structures they work with.