source: trunk/kernel/devices/dev_mmc.h @ 458

Last change on this file since 458 was 457, checked in by alain, 6 years ago

This version modifies the exec syscall and fixes a large number of small bugs.
The version number has been updated (0.1)
File size: 8.4 KB
Line 
1/*
2 * dev_mmc.h - MMC (Generic L2 cache controller) device API definition.
3 *
4 * Authors   Alain Greiner  (2016,2017,2018)
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-MKH; 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_MMC_H_
25#define _DEV_MMC_H_
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29#include <spinlock.h>
30
31/*****************************************************************************************
32 *     Generic L2 cache controller definition
33 *
34 * The MMC (Memory Cache Controller) device describes an internal peripheral,
35 * acting in all clusters containing a level 2 cache controller.
36 *
37 * It supports  five command types:
38 * - MMC_CC_INVAL   : invalidate all cache lines covering a given buffer in L2 cache.
39 * - MMC_CC_SYNC    : synchronize all cache lines covering a given buffer to L3 cache.
40 * - MMC_GET_ERROR  : return content of a given error signaling register.
41 * - MMC_SET_ERROR  : set a given error signaling register.
42 * - MMC_GET_INSTRU : return content of a given instrumentation register.
43 *
44 * As all L2 caches can be accessed by any thread running in any cluster, a calling
45 * thread must get exclusive access to the MMC configuration interface.
46 * As these operations consume few cycles, and access conflicts are expected to be
47 * rare events, the calling threads use a busy waiting strategy to get the device
48 * spinlock, but do not register in the device waiting queue, and no server thread
49 * is used for this device.
50 ****************************************************************************************/
51 
52/****  Forward declarations  ****/
53
54struct chdev_s;
55
56/******************************************************************************************
57 * This enum defines the various implementations of the generic MMC peripheral.
58 * It must be kept consistent with the define in arch_info.h file.
59 *****************************************************************************************/
60
61enum mmc_impl_e
62{
63    IMPL_MMC_TSR =   0,     
64}
65mmc_impl_t;
66
67/*****************************************************************************************
68 * This structure defines the (implementation independant) command pased to the driver.
69 * To have a fixed format, the arguments interpretation depends on the command type.
70 ****************************************************************************************/
71
72enum
73{
74    MMC_CC_INVAL   = 0,
75    MMC_CC_SYNC    = 1,
76    MMC_GET_ERROR  = 2,
77    MMC_SET_ERROR  = 3,
78    MMC_GET_INSTRU = 4,
79};
80
81typedef struct mmc_command_s
82{
83    xptr_t      dev_xp;     /*! extended pointer on target MMC device descriptor        */
84    uint32_t    type;       /*! CC_INVAL / CC_SYNC / GET_ERROR / SET_ERROR / GET_INSTRU */
85    void      * buf_ptr;    /*! local pointer on memory buffer    (used by INVAL/SYNC)  */
86    uint32_t    buf_size;   /*! memory buffer size (bytes)        (used by INVAL/SYNC)  */
87    uint32_t    reg_index;  /*! register index in MMC peripheral  (used by SET/GET)     */
88    uint32_t  * reg_ptr;    /*! local pointer on src/dst buffer   (used by SET/GET)     */
89    error_t     error;      /*! operation status (0 if success)                         */
90}
91mmc_command_t;
92
93/*****************************************************************************************
94 * This function initializes the driver specific fields in the generic MMC device
95 * descriptor, and the implementation specific driver.
96 * It must be executed once in any cluster containing an L2 cache.
97 *****************************************************************************************
98 * @ chdev      : pointer on MMC device descriptor.
99 ****************************************************************************************/
100void dev_mmc_init( struct chdev_s * chdev );
101
102/*****************************************************************************************
103 * This function invalidates all cache lines covering a memory buffer
104 * in the physical address space.
105 * It can be executed by any thread in any cluster, because it uses remote accesses
106 * to access both the MMC device descriptor, and the L2 cache configuration interface.
107 *****************************************************************************************
108 * @ buf_xp     : extended pointer on memory buffer.
109 * @ buf_size   : buffer size (bytes).
110 * @ return 0 if success / return EINVAL if failure
111 ****************************************************************************************/
112error_t dev_mmc_inval( xptr_t     buf_xp,
113                       uint32_t   buf_size );
114
115/*****************************************************************************************
116 * This function forces the L2 cache to synchronize the L3 cache for all cache lines
117 * covering a memory buffer in the physical address space.
118 * It can be executed by any thread in any cluster, because it uses remote accesses
119 * to access both the MMC device descriptor, and the L2 cache configuration interface.
120 *****************************************************************************************
121 * @ buf_xp     : extended pointer on memory buffer.
122 * @ buf_size   : buffer size (bytes).
123 * @ return 0 if success / return EINVAL if failure
124 ****************************************************************************************/
125error_t dev_mmc_sync( xptr_t     buf_xp,
126                      uint32_t   buf_size );
127                       
128/*****************************************************************************************
129 * This function set a value in one error signaling MMC register.
130 * It can be executed by any thread in any cluster, because it uses remote accesses
131 * to access the L2 cache instrumentation interface in any cluster.
132 *****************************************************************************************
133 * @ cxy     : MMC cluster identifier.
134 * @ index   : register index in MMC peripheral.
135 * @ wdata   : value to be written.
136 * @ return 0 if success / return EINVAL if failure
137 ****************************************************************************************/
138error_t dev_mmc_set_error( cxy_t    cxy,
139                           uint32_t index,
140                           uint32_t wdata );
141             
142/*****************************************************************************************
143 * This function returns the value contained in one error signaling MMC register.
144 * It can be executed by any thread in any cluster, because it uses remote accesses
145 * to access the L2 cache instrumentation interface in any cluster.
146 *****************************************************************************************
147 * @ cxy     : MMC cluster identifier.
148 * @ index   : error register index in MMC peripheral.
149 * @ rdata   : local pointer on buffer for returned value.
150 * @ return 0 if success / return EINVAL if failure
151 ****************************************************************************************/
152error_t dev_mmc_get_error( cxy_t      cxy,
153                           uint32_t   index, 
154                           uint32_t * rdata );
155             
156
157/*****************************************************************************************
158 * This function returns the value contained in one instrumentation MMC register.
159 * It can be executed by any thread in any cluster, because it uses remote accesses
160 * to access the L2 cache configuration interface in any cluster.
161 *****************************************************************************************
162 * @ cxy     : MMC cluster identifier.
163 * @ index   : instrumentation register index in MMC peripheral.
164 * @ rdata   : local pointer on buffer for returned value.
165 * @ return 0 if success / return EINVAL if failure
166 ****************************************************************************************/
167error_t dev_mmc_get_instrumentation( cxy_t      cxy,
168                                     uint32_t   index,
169                                     uint32_t * rdata );
170
171#endif  /* _DEV_MMC_H_ */
Note: See TracBrowser for help on using the repository browser.