source: trunk/kernel/devices/dev_ioc.h

Last change on this file was 657, checked in by alain, 21 months ago

Introduce remote_buf.c/.h & socket.c/.h files.
Update dev_nic.c/.h files.

File size: 11.0 KB
Line 
1/*
2 * dev_ioc.h - IOC (Block Device Controler) generic device API definition.
3 *
4 * Author  Alain Greiner    (2016,2017,2018,2019,2020)
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_IOC_H
25#define _DEV_IOC_H
26
27#include <kernel_config.h>
28#include <hal_kernel_types.h>
29
30/****  Forward declarations  ****/
31
32struct chdev_s;
33
34/*****************************************************************************************
35 *     Generic Block Device Controler definition
36 *
37 * This device provide access to an external mass storage peripheral such as a
38 * magnetic hard disk or a SD card, that can store blocks of data in a linear array
39 * of sectors indexed by a simple lba (logic block address).
40 *
41 * It supports four command types:
42 * - READ       : move blocks from device to memory, with a descheduling policy.
43 * - WRITE      : move blocks from memory to device, with a descheduling policy.
44 * - SYNC_READ  : move blocks from device to memory, with a busy waiting policy.
45 * - SYNC_WRITE : move blocks from memory to device, with a busy waiting policy.
46 *
47 * For the READ or WRITE operations, the client thread is descheduled, and the work
48 * is done by the server thread associated to the IOC device:
49 * The client thread calls the dev_ioc_move_data() kernel functions that (i) registers
50 * the command in the client thread descriptor, (ii) registers the client thread
51 * in the IOC device waiting queue, and (iii) blocks on the THREAD_BLOCKED_IO condition
52 * and deschedules.
53 * The server thread attached to the IOC device descriptor handles the commands
54 * registered in the waiting queue, calling the IOC driver function.
55 * Most IOC device implementations have a DMA capability, but some implementations,
56 * such as the RDK (Ram Disk) implementation does not use DMA.
57 * When the server thread completes an I/O operation, it reactivates the client thread.
58 *
59 * The SYNC_READ and SYNC_WRITE operations are used by the kernel in the initialisation
60 * phase, to update the FAT (both the FAT mapper and the FAT on IOC device), or to update
61 * a directory on IOC device when a new file is created.
62 * These synchronous operations do not not use the IOC device waiting queue,
63 * the server thread, and the IOC IRQ. The client thread does not deschedules:
64 * it registers the command in the thread descriptor, calls directly the IOC driver,
65 * and uses a busy-waiting policy to poll the IOC device status.
66 *****************************************************************************************/
67
68/******************************************************************************************
69 * This defines the (implementation independant) extension for the generic IOC device.
70 *****************************************************************************************/
71
72typedef struct ioc_extend_s
73{
74    uint32_t    size;      /*! number of bytes in a block                               */
75    uint32_t    count;     /*! total number of blocks in physical device                */
76}
77ioc_extend_t;
78
79/******************************************************************************************
80 * This enum defines the various implementations of the generic IOC peripheral.
81 * It must be kept consistent with the define in arch_info.h file.
82 *****************************************************************************************/
83
84typedef enum
85{
86    IMPL_IOC_BDV =   0,     
87    IMPL_IOC_HBA =   1, 
88    IMPL_IOC_SDC =   2,
89    IMPL_IOC_SPI =   3,
90    IMPL_IOC_RDK =   4,
91}
92ioc_impl_t;
93
94/******************************************************************************************
95 * This structure defines the IOC command for all drivers implementing the IOC device.
96 *****************************************************************************************/
97
98typedef enum
99{
100    IOC_READ       = 0,
101    IOC_WRITE      = 1,
102    IOC_SYNC_READ  = 2,
103    IOC_SYNC_WRITE = 3,
104}
105ioc_cmd_type_t;
106
107typedef struct ioc_command_s
108{
109    xptr_t      dev_xp;     /*! extended pointer on IOC device descriptor                */
110    uint32_t    type;       /*! command type above                                       */
111    uint32_t    lba;        /*! first block index                                        */
112    uint32_t    count;      /*! number of blocks                                         */
113    xptr_t      buf_xp;     /*! extended pointer on kernel memory buffer                 */
114    uint32_t    error;      /*! operation status (0 if success)                          */
115}
116ioc_command_t;
117
118/******************************************************************************************
119 * This function returns a printable string for a IOC command type.
120 ******************************************************************************************
121 * @ cmd  : command type.
122 * @ return pointer on string.
123 *****************************************************************************************/
124char * dev_ioc_cmd_str( ioc_cmd_type_t cmd );
125
126/******************************************************************************************
127 * This function completes the IOC chdev descriptor initialisation,
128 * namely the link with the implementation specific driver.
129 * The func, impl, channel, is_rx, base fields have been previously initialised.
130 * It calls the specific driver initialisation function, to initialise the hardware
131 * device and the specific data structures when required.
132 * It creates the associated server thread and allocates a WTI from local ICU.
133 * It must de executed by a local thread.
134 ******************************************************************************************
135 * @ chdev     : local pointer on IOC chdev descriptor.
136 *****************************************************************************************/
137void dev_ioc_init( struct chdev_s * chdev );
138
139/******************************************************************************************
140 * This blocking function register an asynchronous READ request : move <count> contiguous
141 * blocks from the block device, starting from block defined by the <lba> argument, to a
142 * kernel buffer defined by the <buffer_xp> argument.
143 * It register the request in the client thread descriptor, it register the client thread
144 * in the IOC device queue, it blocks on the THREAD_BLOCKED_IO condition, and deschedules.
145 * It will be reactivated by the DEV server thread when the transfer is completed.
146 * It can be executed by a thread running in any cluster.
147 ******************************************************************************************
148 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
149 * @ lba       : first block index on device.
150 * @ count     : number of blocks to transfer.
151 * @ returns 0 if success / returns -1 if error.
152 *****************************************************************************************/
153error_t dev_ioc_read( xptr_t    buffer_xp,
154                      uint32_t  lba,
155                      uint32_t  count );
156
157/******************************************************************************************
158 * This blocking function register an asynchronous WRITE request : move <count> contiguous
159 * blocks from a kernel buffer defined by the <buffer_xp> argument to the block device,
160 * starting from block defined by the <lba> argument.
161 * It register the request in the client thread descriptor, it register the client thread
162 * in the IOC device queue, it blocks on the THREAD_BLOCKED_IO condition, and deschedules.
163 * It will be reactivated by the DEV server thread when the transfer is completed.
164 * It can be executed by a thread running in any cluster.
165 ******************************************************************************************
166 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
167 * @ lba       : first block index on device.
168 * @ count     : number of blocks to transfer.
169 * @ returns 0 if success / returns -1 if error.
170 *****************************************************************************************/
171error_t dev_ioc_write( xptr_t    buffer_xp,
172                       uint32_t  lba,
173                       uint32_t  count );
174
175/******************************************************************************************
176 * This blocking function executes a synchronous SYNC_READ request : it moves <count>
177 * contiguous blocks of data from the block device, starting from block defined by the
178 * <lba> argument to a kernel memory buffer, defined by the <buffer_xp> argument.
179 * The request is registered in the calling thread descriptor, but the client thread calls
180 * directly the driver cmd function, that is also a blocking function returning only
181 * when the transfer is completed.
182 * It can be executed by a thread running in any cluster.
183 ******************************************************************************************
184 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
185 * @ lba       : first block index on device.
186 * @ count     : number of blocks to transfer.
187 * @ returns 0 if success / returns -1 if error.
188 *****************************************************************************************/
189error_t dev_ioc_sync_read( xptr_t    buffer_xp,
190                           uint32_t  lba,
191                           uint32_t  count );
192
193/******************************************************************************************
194 * This blocking function executes a synchronous SYNC_WRITE request : it moves <count>
195 * contiguous blocks of data from a kernel memory buffer, defined by the <buffer_xp>
196 * argument to the block device, starting from block defined by the <lba> argument.
197 * The request is registered in the calling thread descriptor, but the client thread calls
198 * directly the driver cmd() function, that is also a blocking function returning only
199 * when the transfer is completed.
200 * It can be executed by a thread running in any cluster.
201 ******************************************************************************************
202 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
203 * @ lba       : first block index on device.
204 * @ count     : number of blocks to transfer.
205 * @ returns 0 if success / returns -1 if error.
206 *****************************************************************************************/
207error_t dev_ioc_sync_write( xptr_t    buffer_xp,
208                            uint32_t  lba,
209                            uint32_t  count );
210
211#endif  /* _DEV_IOC_H */
Note: See TracBrowser for help on using the repository browser.