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

Last change on this file since 296 was 188, checked in by alain, 7 years ago

Redefine the PIC device API.
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 * It calls the specific driver initialisation function, to initialise the hardware
94 * device and the specific data structures when required by the implementation.
95 * It must be called by a local thread.
96 *
97 * TODO In this first approach, the "width" and "height" parameters are defined
98 * by the CONFIG_FBF_WIDTH & CONFIG_FBF_HEIGHT in the kernel_config.h file.
99 * These parameters should be provided by the driver, accessing dedicated
100 * adressable registers in the FBF controler.
101 ******************************************************************************************
102 * @ chdev      : pointer on FBF chdev descriptor.
103 *****************************************************************************************/
104void dev_fbf_init( struct chdev_s * chdev );
105
106/******************************************************************************************
107 * This function returns the fixed size frame buffer features.
108 ******************************************************************************************
109 * @ width     : number of pixels (bytes) per line.
110 * @ heigth    : total number of lines.
111 *****************************************************************************************/
112void dev_fbf_get_size( uint32_t  * width,
113                       uint32_t  * height );
114
115/******************************************************************************************
116 * This function try to get the exclusive ownership of the frame buffer.
117 ******************************************************************************************
118 * @ return 0 if success / return EINVAL if frame buffer already allocated.
119 *****************************************************************************************/
120error_t dev_fbf_alloc();
121
122/******************************************************************************************
123 * This function releases the exclusive ownership of the frame buffer.
124 *****************************************************************************************/
125void dev_fbf_free();
126
127/******************************************************************************************
128 * This blocking function try to tranfer <length> bytes from the frame buffer, starting
129 * from <offset>, to the memory buffer defined by <buffer> argument.
130 * The corresponding request is actually registered in the local DMA device waiting
131 * queue that has the same index as the calling core. The calling thread is descheduled,
132 * waiting on transfer completion. It will be resumed by the DMA IRQ signaling completion.
133 ******************************************************************************************
134 * @ buffer    : local pointer on target buffer in memory.
135 * @ length    : number of bytes.
136 * @ offset    : first byte in frame buffer.   
137 * @ returns 0 if success / returns EINVAL if error.
138 *****************************************************************************************/
139error_t dev_fbf_read( char         * buffer,
140                      uint32_t       length,
141                      uint32_t       offset );
142
143/******************************************************************************************
144 * This blocking function try to tranfer <length> bytes from a memory buffer defined
145 * by <buffer> argument, to the frame buffer, starting from <offset>.
146 * The corresponding request is actually registered in the local DMA device waiting
147 * queue, that has the same index as the calling core. The calling thread is descheduled,
148 * waiting on transfer completion. It will be resumed by the DMA IRQ signaling completion.
149 ******************************************************************************************
150 * @ buffer    : local pointer on source buffer in memory.
151 * @ length    : number of bytes.
152 * @ offset    : first byte in frame buffer.   
153 * @ returns 0 if success / returns EINVAL if error.
154 *****************************************************************************************/
155error_t dev_fbf_write( char         * buffer,
156                       uint32_t       length,
157                       uint32_t       offset );
158
159#endif  /* _DEV_FBF_H */
Note: See TracBrowser for help on using the repository browser.