source: rtems-docs/bsp_howto/frame_buffer.rst @ b350509

4.115
Last change on this file since b350509 was b350509, checked in by Amar Takhar <amar@…>, on 01/17/16 at 05:47:50

Split document into seperate files by section.

  • Property mode set to 100644
File size: 7.9 KB
Line 
1Frame Buffer Driver
2###################
3
4In this chapter, we present the basic functionality implemented by a
5frame buffer driver: ``frame_buffer_initialize()``, ``frame_buffer_open()``,``frame_buffer_close()``, ``frame_buffer_read()``, ``frame_buffer_write()``
6and ``frame_buffer_control()``.
7
8Introduction
9============
10
11The purpose of the frame buffer driver is to provide an abstraction for
12graphics hardware.
13By using the frame buffer interface, an application can display graphics
14without knowing anything about the low-level details of interfacing to a
15particular graphics adapter. The parameters governing the mapping of
16memory to displayed pixels (planar or linear, bit depth, etc) is still
17implementation-specific, but device-independent methods are provided to
18determine and potentially modify these parameters.
19
20The frame buffer driver is commonly located in the ``console``
21directory of the BSP and registered by the name */dev/fb0*.
22Additional frame buffers (if available) are named */dev/fb1*,*/dev/fb2*, etc.
23
24To 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()``.
25
26Driver Function Overview
27========================
28
29Initialization
30--------------
31
32The driver initialization is called once during the RTEMS initialization
33process and returns RTEMS_SUCCESSFUL when the device driver is successfully
34initialized. During the initialization, a name is assigned to the frame
35buffer device.  If the graphics hardware supports console text output,
36as is the case with the pc386 VGA hardware, initialization into graphics
37mode may be deferred until the device is ``open()`` ed.
38
39The ``frame_buffer_initialize()`` function may look like this:
40
41.. code:: c
42
43    rtems_device_driver frame_buffer_initialize(
44    rtems_device_major_number  major,
45    rtems_device_minor_number  minor,
46    void                      \*arg)
47    {
48    rtems_status_code status;
49    printk( "frame buffer driver initializing..\\n" );
50    /*
51    * Register the device
52    \*/
53    status = rtems_io_register_name("/dev/fb0", major, 0);
54    if (status != RTEMS_SUCCESSFUL)
55    {
56    printk("Error registering frame buffer device!\\n");
57    rtems_fatal_error_occurred( status );
58    }
59    /*
60    * graphics hardware initialization goes here for non-console
61    * devices
62    \*/
63    return RTEMS_SUCCESSFUL;
64    }
65
66Opening the Frame Buffer Device
67-------------------------------
68
69The ``frame_buffer_open()`` function is called whenever a frame buffer device is opened.
70If the frame buffer is registered as "/dev/fb0", the ``frame_buffer_open`` entry point
71will be called as the result of an  ``open("/dev/fb0", mode)`` in the application.
72
73Thread safety of the frame buffer driver is implementation-dependent.
74The VGA driver shown below uses a mutex to prevent multiple open()
75operations of the frame buffer device.
76
77The ``frame_buffer_open()`` function returns RTEMS_SUCCESSFUL when the device driver
78is successfully opened, and RTEMS_UNSATISFIED if the device is already open:
79.. code:: c
80
81    rtems_device_driver frame_buffer_close(
82    rtems_device_major_number  major,
83    rtems_device_minor_number  minor,
84    void                      \*arg
85    )
86    {
87    if (pthread_mutex_unlock(&mutex) == 0){
88    /* restore previous state.  for VGA this means return to text mode.
89    * leave out if graphics hardware has been initialized in
90    * frame_buffer_initialize() \*/
91    ega_hwterm();
92    printk( "FBVGA close called.\\n" );
93    return RTEMS_SUCCESSFUL;
94    }
95    return RTEMS_UNSATISFIED;
96    }
97
98In the previous example, the function ``ega_hwinit()`` takes care of
99hardware-specific initialization.
100
101Closing the Frame Buffer Device
102-------------------------------
103
104The ``frame_buffer_close()`` is invoked when the frame buffer device
105is closed.  It frees up any resources allocated in``frame_buffer_open()``, and should restore previous hardware state.
106The entry point corresponds to the device driver close entry point.
107
108Returns RTEMS_SUCCESSFUL when the device driver is successfully closed:
109.. code:: c
110
111    rtems_device_driver frame_buffer_close(
112    rtems_device_major_number  major,
113    rtems_device_minor_number  minor,
114    void                      \*arg)
115    {
116    pthread_mutex_unlock(&mutex);
117    /* TODO check mutex return value, RTEMS_UNSATISFIED if it failed.  we
118    * don't want to unconditionally call ega_hwterm()... \*/
119    /* restore previous state.  for VGA this means return to text mode.
120    * leave out if graphics hardware has been initialized in
121    * frame_buffer_initialize() \*/
122    ega_hwterm();
123    printk( "frame buffer close called.\\n" );
124    return RTEMS_SUCCESSFUL;
125    }
126
127Reading from the Frame Buffer Device
128------------------------------------
129
130The ``frame_buffer_read()`` is invoked from a ``read()`` operation
131on the frame buffer device.
132Read functions should allow normal and partial reading at the end of frame buffer memory.
133This method returns RTEMS_SUCCESSFUL when the device is successfully read from:
134.. code:: c
135
136    rtems_device_driver frame_buffer_read(
137    rtems_device_major_number  major,
138    rtems_device_minor_number  minor,
139    void                      \*arg
140    )
141    {
142    rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
143    rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
144    memcpy(rw_args->buffer, (const void \*) (fb_fix.smem_start + rw_args->offset), rw_args->bytes_moved);
145    return RTEMS_SUCCESSFUL;
146    }
147
148Writing to the Frame Buffer Device
149----------------------------------
150
151The ``frame_buffer_write()`` is invoked from a ``write()``
152operation on the frame buffer device.
153The frame buffer write function is similar to the read function, and
154should handle similar cases involving partial writes.
155
156This method returns RTEMS_SUCCESSFUL when the device is successfully
157written to:
158.. code:: c
159
160    rtems_device_driver frame_buffer_write(
161    rtems_device_major_number  major,
162    rtems_device_minor_number  minor,
163    void                      \*arg
164    )
165    {
166    rtems_libio_rw_args_t \*rw_args = (rtems_libio_rw_args_t \*)arg;
167    rw_args->bytes_moved = ((rw_args->offset + rw_args->count) > fb_fix.smem_len ) ? (fb_fix.smem_len - rw_args->offset) : rw_args->count;
168    memcpy( (void \*) (fb_fix.smem_start + rw_args->offset), rw_args->buffer, rw_args->bytes_moved);
169    return RTEMS_SUCCESSFUL;
170    }
171
172Frame Buffer IO Control
173-----------------------
174
175The frame buffer driver allows several ioctls, partially compatible with
176the Linux kernel,
177to obtain information about the hardware.
178
179All ``ioctl()`` operations on the frame buffer device invoke``frame_buffer_control()``.
180
181Ioctls supported:
182
183- ioctls to get the frame buffer screen info (fixed and variable).
184
185- ioctl to set and get palette.
186
187.. code:: c
188
189    rtems_device_driver frame_buffer_control(
190    rtems_device_major_number  major,
191    rtems_device_minor_number  minor,
192    void                      \*arg
193    )
194    {
195    rtems_libio_ioctl_args_t \*args = arg;
196    printk( "FBVGA ioctl called, cmd=%x\\n", args->command  );
197    switch( args->command ) {
198    case FBIOGET_FSCREENINFO:
199    args->ioctl_return =  get_fix_screen_info( ( struct fb_fix_screeninfo * ) args->buffer );
200    break;
201    case FBIOGET_VSCREENINFO:
202    args->ioctl_return =  get_var_screen_info( ( struct fb_var_screeninfo * ) args->buffer );
203    break;
204    case FBIOPUT_VSCREENINFO:
205    /* not implemented yet*/
206    args->ioctl_return = -1;
207    return RTEMS_UNSATISFIED;
208    case FBIOGETCMAP:
209    args->ioctl_return =  get_palette( ( struct fb_cmap * ) args->buffer );
210    break;
211    case FBIOPUTCMAP:
212    args->ioctl_return =  set_palette( ( struct fb_cmap * ) args->buffer );
213    break;
214    default:
215    args->ioctl_return = 0;
216    break;
217    }
218    return RTEMS_SUCCESSFUL;
219    }
220
221See ``rtems/fb.h`` for more information on the list of ioctls and
222data structures they work with.
223
224.. COMMENT: COPYRIGHT (c) 1988-2002.
225
226.. COMMENT: On-Line Applications Research Corporation (OAR).
227
228.. COMMENT: All rights reserved.
229
Note: See TracBrowser for help on using the repository browser.