source: trunk/kernel/devices/dev_fbf.h@ 95

Last change on this file since 95 was 3, checked in by alain, 9 years ago

Introduce dev_fbf, dev dma, dev_iob
File size: 8.0 KB
Line 
1/*
2 * dev_fbf.h - FBF (Block Device Controler) generic device API definition.
3 *
4 * Author Alain Greiner (2016)
5 *
6 * Copyright (c) UPMC Sorbonne Universites
7 *
8 * This file is part of ALMOS-MKH
9 *
10 * ALMOS-MKH is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; version 2.0 of the License.
13 *
14 * ALMOS-MKH is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License
20 * along with ALMOS-kernel; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
22 */
23
24#ifndef _DEV_FBF_H
25#define _DEV_FBF_H
26
27#include <hal_types.h>
28
29/**** Forward declarations ****/
30
31struct chdev_s;
32
33/*****************************************************************************************
34 * Generic Frame Buffer Controler definition
35 *
36 * This device provide access to an external graphic display, that is seen
37 * as a fixed size frame buffer, mapped in the kernel address space.
38 * Each pixel takes one byte defining 256 levels of gray.
39 *
40 * It supports five command types:
41 * - SIZE : return the Frame buffer width and height.
42 * - ALLOC : give exclusive ownership of the frame buffer to the requesting process.
43 * - FREE : release the exclusive ownership to the kernel.
44 * - READ : move a given number of bytes from the frame buffer to a memory buffer.
45 * - WRITE : move a given number of bytes from a memory buffer to the frame buffer.
46 *
47 * It does not creates the associated server thread.
48 * - The SIZE, ALLOC, FREE commands are directly handled by the FBF device.
49 * - The READ & WRITE commands are actually registered in the DMA device waiting queue,
50 * using the local DMA channel defined by the calling core lid.
51 *****************************************************************************************/
52
53/******************************************************************************************
54 * This defines the (implementation independant) extension for the generic FBF device.
55 *****************************************************************************************/
56
57typedef struct fbf_extend_s
58{
59 uint32_t width; /*! number of pixels per line. */
60 uint32_t height; /*! total number of lines. */
61}
62fbf_extend_t;
63
64/******************************************************************************************
65 * This enum defines the various implementations of the generic FBF peripheral.
66 * It must be kept consistent with the define in arch_info.h file.
67 *****************************************************************************************/
68
69enum fbf_impl_e
70{
71 IMPL_FBF_SCL = 0,
72 IMPL_FBF_I86 = 1,
73}
74fbf_impl_t;
75
76/******************************************************************************************
77 * This defines the (implementation independant) command passed to the driver.
78 *****************************************************************************************/
79
80typedef struct fbf_command_s
81{
82 xptr_t dev_xp; /*! extended pointer on device descriptor */
83 uint32_t to_fbf; /*! requested operation type. */
84 uint32_t length; /*! number of bytes. */
85 uint32_t offset; /*! offset in frame buffer (bytes) */
86 xptr_t buf_xp; /*! extended pointer on memory buffer */
87 uint32_t error; /*! operation status (0 if success) */
88}
89fbf_command_t;
90
91/******************************************************************************************
92 * This function completes the FBF chdev descriptor initialisation,
93 * namely the width and height parameters.
94 * TODO : these parameters should be provided by the hardware through a dedicated
95 * software API ...
96 * It calls the specific driver initialisation function, to initialise the hardware
97 * device and the specific data structures when required by the implementation.
98 * It must be called by a local thread.
99 ******************************************************************************************
100 * @ chdev : pointer on FBF chdev descriptor.
101 * @ width : number of pixels (bytes) per line.
102 * @ height : total number of lines.
103 *****************************************************************************************/
104void dev_fbf_init( struct chdev_s * chdev,
105 uint32_t width,
106 uint32_t height );
107
108/******************************************************************************************
109 * This function returns the fixed size frame buffer features.
110 ******************************************************************************************
111 * @ width : number of pixels (bytes) per line.
112 * @ heigth : total number of lines.
113 *****************************************************************************************/
114void dev_fbf_get_size( uint32_t * width,
115 uint32_t * height );
116
117/******************************************************************************************
118 * This function try to get the exclusive ownership of the frame buffer.
119 ******************************************************************************************
120 * @ return 0 if success / return EINVAL if frame buffer already allocated.
121 *****************************************************************************************/
122error_t dev_fbf_alloc();
123
124/******************************************************************************************
125 * This function releases the exclusive ownership of the frame buffer.
126 *****************************************************************************************/
127void dev_fbf_free();
128
129/******************************************************************************************
130 * This blocking function try to tranfer <length> bytes from the frame buffer, starting
131 * from <offset>, to the memory buffer defined by <buffer> argument.
132 * The corresponding request is actually registered in the local DMA device waiting
133 * queue that has the same index as the calling core. The calling thread is descheduled,
134 * waiting on transfer completion. It will be resumed by the DMA IRQ signaling completion.
135 ******************************************************************************************
136 * @ buffer : local pointer on target buffer in memory.
137 * @ length : number of bytes.
138 * @ offset : first byte in frame buffer.
139 * @ returns 0 if success / returns EINVAL if error.
140 *****************************************************************************************/
141error_t dev_fbf_read( char * buffer,
142 uint32_t length,
143 uint32_t offset );
144
145/******************************************************************************************
146 * This blocking function try to tranfer <length> bytes from a memory buffer defined
147 * by <buffer> argument, to the frame buffer, starting from <offset>.
148 * The corresponding request is actually registered in the local DMA device waiting
149 * queue, that has the same index as the calling core. The calling thread is descheduled,
150 * waiting on transfer completion. It will be resumed by the DMA IRQ signaling completion.
151 ******************************************************************************************
152 * @ buffer : local pointer on source buffer in memory.
153 * @ length : number of bytes.
154 * @ offset : first byte in frame buffer.
155 * @ returns 0 if success / returns EINVAL if error.
156 *****************************************************************************************/
157error_t dev_fbf_write( char * buffer,
158 uint32_t length,
159 uint32_t offset );
160
161#endif /* _DEV_FBF_H */
Note: See TracBrowser for help on using the repository browser.