1 | Frame Buffer Driver |
---|
2 | ################### |
---|
3 | |
---|
4 | In this chapter, we present the basic functionality implemented by a |
---|
5 | frame buffer driver: ``frame_buffer_initialize()``, ``frame_buffer_open()``,``frame_buffer_close()``, ``frame_buffer_read()``, ``frame_buffer_write()`` |
---|
6 | and ``frame_buffer_control()``. |
---|
7 | |
---|
8 | Introduction |
---|
9 | ============ |
---|
10 | |
---|
11 | The purpose of the frame buffer driver is to provide an abstraction for |
---|
12 | graphics hardware. |
---|
13 | By using the frame buffer interface, an application can display graphics |
---|
14 | without knowing anything about the low-level details of interfacing to a |
---|
15 | particular graphics adapter. The parameters governing the mapping of |
---|
16 | memory to displayed pixels (planar or linear, bit depth, etc) is still |
---|
17 | implementation-specific, but device-independent methods are provided to |
---|
18 | determine and potentially modify these parameters. |
---|
19 | |
---|
20 | The frame buffer driver is commonly located in the ``console`` |
---|
21 | directory of the BSP and registered by the name */dev/fb0*. |
---|
22 | Additional frame buffers (if available) are named */dev/fb1*,*/dev/fb2*, etc. |
---|
23 | |
---|
24 | 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()``. |
---|
25 | |
---|
26 | Driver Function Overview |
---|
27 | ======================== |
---|
28 | |
---|
29 | Initialization |
---|
30 | -------------- |
---|
31 | |
---|
32 | The driver initialization is called once during the RTEMS initialization |
---|
33 | process and returns RTEMS_SUCCESSFUL when the device driver is successfully |
---|
34 | initialized. During the initialization, a name is assigned to the frame |
---|
35 | buffer device. If the graphics hardware supports console text output, |
---|
36 | as is the case with the pc386 VGA hardware, initialization into graphics |
---|
37 | mode may be deferred until the device is ``open()`` ed. |
---|
38 | |
---|
39 | The ``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 | |
---|
66 | Opening the Frame Buffer Device |
---|
67 | ------------------------------- |
---|
68 | |
---|
69 | The ``frame_buffer_open()`` function is called whenever a frame buffer device is opened. |
---|
70 | If the frame buffer is registered as "/dev/fb0", the ``frame_buffer_open`` entry point |
---|
71 | will be called as the result of an ``open("/dev/fb0", mode)`` in the application. |
---|
72 | |
---|
73 | Thread safety of the frame buffer driver is implementation-dependent. |
---|
74 | The VGA driver shown below uses a mutex to prevent multiple open() |
---|
75 | operations of the frame buffer device. |
---|
76 | |
---|
77 | The ``frame_buffer_open()`` function returns RTEMS_SUCCESSFUL when the device driver |
---|
78 | is 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 | |
---|
98 | In the previous example, the function ``ega_hwinit()`` takes care of |
---|
99 | hardware-specific initialization. |
---|
100 | |
---|
101 | Closing the Frame Buffer Device |
---|
102 | ------------------------------- |
---|
103 | |
---|
104 | The ``frame_buffer_close()`` is invoked when the frame buffer device |
---|
105 | is closed. It frees up any resources allocated in``frame_buffer_open()``, and should restore previous hardware state. |
---|
106 | The entry point corresponds to the device driver close entry point. |
---|
107 | |
---|
108 | Returns 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 | |
---|
127 | Reading from the Frame Buffer Device |
---|
128 | ------------------------------------ |
---|
129 | |
---|
130 | The ``frame_buffer_read()`` is invoked from a ``read()`` operation |
---|
131 | on the frame buffer device. |
---|
132 | Read functions should allow normal and partial reading at the end of frame buffer memory. |
---|
133 | This 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 | |
---|
148 | Writing to the Frame Buffer Device |
---|
149 | ---------------------------------- |
---|
150 | |
---|
151 | The ``frame_buffer_write()`` is invoked from a ``write()`` |
---|
152 | operation on the frame buffer device. |
---|
153 | The frame buffer write function is similar to the read function, and |
---|
154 | should handle similar cases involving partial writes. |
---|
155 | |
---|
156 | This method returns RTEMS_SUCCESSFUL when the device is successfully |
---|
157 | written 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 | |
---|
172 | Frame Buffer IO Control |
---|
173 | ----------------------- |
---|
174 | |
---|
175 | The frame buffer driver allows several ioctls, partially compatible with |
---|
176 | the Linux kernel, |
---|
177 | to obtain information about the hardware. |
---|
178 | |
---|
179 | All ``ioctl()`` operations on the frame buffer device invoke``frame_buffer_control()``. |
---|
180 | |
---|
181 | Ioctls 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 | |
---|
221 | See ``rtems/fb.h`` for more information on the list of ioctls and |
---|
222 | data 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 | |
---|