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

Last change on this file since 176 was 3, checked in by alain, 8 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.