source: trunk/kernel/devices/dev_ioc.h @ 645

Last change on this file since 645 was 627, checked in by alain, 5 years ago

Replace the queuelock protectingthe FAT by a rwlock in the FATFS.

File size: 11.1 KB
Line 
1/*
2 * dev_ioc.h - IOC (Block Device Controler) generic device API definition.
3 *
4 * Author  Alain Greiner    (2016,2017,2018,2019)
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 * It supports four command types:
41 * - READ       : move blocks from device to memory, with a descheduling policy.
42 * - WRITE      : move blocks from memory to device, with a descheduling policy.
43 * - SYNC_READ  : move blocks from device to memory, with a busy waiting policy.
44 * - SYNC_WRITE : move blocks from memory to device, with a busy waiting policy.
45
46 * The READ or WRITE operations require dynamic ressource allocation. The calling thread
47 * is descheduled, and the work is done by the server thread associated to IOC device.
48 * The general scenario is detailed below.
49 * A) the client thread start the I/O operation, by calling the dev_ioc_read()
50 *    or the dev_ioc_write() kernel functions that perform the following actions:
51 *    1) it get a free WTI mailbox from the client cluster WTI allocator.
52 *    2) it enables the WTI IRQ on the client cluster ICU and update interrupt vector.
53 *    3) it access the PIC to link the WTI mailbox to the IOC IRQ.
54 *    4) it builds the command descriptor.
55 *    5) it registers in the IOC device waiting queue.
56 *    6) itblock on the THREAD_BLOCKED_IO condition and deschedule.
57 * B) The server thread attached to the IOC device descriptor handles the commands
58 *    registered in the waiting queue, calling the IOC driver function.
59 *    Most hardware implementation have a DMA capability, but some implementations,
60 *    such as the RDK (Ram Disk) implementation does not use DMA.
61 * C) The ISR signaling the I/O operation completion reactivates the client thread,
62 *    that releases the allocated resources:
63 *    1) access the PIC to unlink the IOC IRQ.
64 *    2) disable the WTI IRQ in the client cluster ICU and update interrupt vector.
65 *    3) release the WTI mailbox to the client cluster WTI allocator.
66 *
67 * The SYNC_READ and SYNC_WRITE operations are used by the kernel in the initialisation
68 * phase, to update the FAT (both the FAT mapper and the FAT on IOC device), or to update
69 * a directory on IOC device when a new file is created.
70 * - These synchronous operations do not not use the IOC device waiting queue,
71 *   the server thread, and the IOC IRQ, but implement a busy-waiting policy
72 *   for the calling thread.
73 * - As the work
74 *****************************************************************************************/
75
76/******************************************************************************************
77 * This defines the (implementation independant) extension for the generic IOC device.
78 *****************************************************************************************/
79
80typedef struct ioc_extend_s
81{
82    uint32_t    size;      /*! number of bytes in a block                               */
83    uint32_t    count;     /*! total number of blocks in physical device                */
84}
85ioc_extend_t;
86
87/******************************************************************************************
88 * This enum defines the various implementations of the generic IOC peripheral.
89 * It must be kept consistent with the define in arch_info.h file.
90 *****************************************************************************************/
91
92typedef enum
93{
94    IMPL_IOC_BDV =   0,     
95    IMPL_IOC_HBA =   1, 
96    IMPL_IOC_SDC =   2,
97    IMPL_IOC_SPI =   3,
98    IMPL_IOC_RDK =   4,
99}
100ioc_impl_t;
101
102/******************************************************************************************
103 * This defines the (implementation independant)  command passed to the driver.
104 *****************************************************************************************/
105
106typedef enum
107{
108    IOC_READ       = 0,
109    IOC_WRITE      = 1,
110    IOC_SYNC_READ  = 2,
111    IOC_SYNC_WRITE = 3,
112}
113cmd_type_t;
114
115typedef struct ioc_command_s
116{
117    xptr_t      dev_xp;     /*! extended pointer on IOC device descriptor                */
118    uint32_t    type;       /*! IOC_READ / IOC_WRITE / IOC_SYNC_READ                     */
119    uint32_t    lba;        /*! first block index                                        */
120    uint32_t    count;      /*! number of blocks                                         */
121    xptr_t      buf_xp;     /*! extended pointer on memory buffer                        */
122    uint32_t    error;      /*! operation status (0 if success)                          */
123}
124ioc_command_t;
125
126/******************************************************************************************
127 * This function returns a printable string for a IOC command type.
128 ******************************************************************************************
129 * @ cmd  : command type.
130 * @ return pointer on string.
131 *****************************************************************************************/
132char * dev_ioc_cmd_str( cmd_type_t cmd );
133
134/******************************************************************************************
135 * This function completes the IOC chdev descriptor initialisation,
136 * namely the link with the implementation specific driver.
137 * The func, impl, channel, is_rx, base fields have been previously initialised.
138 * It calls the specific driver initialisation function, to initialise the hardware
139 * device and the specific data structures when required.
140 * It creates the associated server thread and allocates a WTI from local ICU.
141 * It must de executed by a local thread.
142 ******************************************************************************************
143 * @ chdev     : local pointer on IOC chdev descriptor.
144 *****************************************************************************************/
145void dev_ioc_init( struct chdev_s * chdev );
146
147/******************************************************************************************
148 * This blocking function moves one or several contiguous blocks of data
149 * from the block device to a local memory buffer. The corresponding request is actually
150 * registered in the device pending request queue, and the calling thread is descheduled,
151 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
152 * It must be called by a local thread.
153 ******************************************************************************************
154 * @ buffer    : local pointer on target buffer in memory (must be block aligned).
155 * @ lba       : first block index on device.
156 * @ count     : number of blocks to transfer.
157 * @ returns 0 if success / returns -1 if error.
158 *****************************************************************************************/
159error_t dev_ioc_read( uint8_t      * buffer,
160                      uint32_t       lba,
161                      uint32_t       count );
162
163/******************************************************************************************
164 * This blocking function moves one or several contiguous blocks of data
165 * from a local memory buffer to the block device. The corresponding request is actually
166 * registered in the device pending request queue, and the calling thread is descheduled,
167 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
168 * It must be called by a local thread.
169 ******************************************************************************************
170 * @ buffer    : local pointer on source buffer in memory (must be block aligned).
171 * @ lba       : first block index on device.
172 * @ count     : number of blocks to transfer.
173 * @ returns 0 if success / returns -1 if error.
174 *****************************************************************************************/
175error_t dev_ioc_write( uint8_t      * buffer,
176                       uint32_t       lba,
177                       uint32_t       count );
178
179/******************************************************************************************
180 * This blocking function moves one or several contiguous blocks of data
181 * from the block device to a - possibly remote - memory buffer.
182 * It uses an extended pointer, because the target buffer is generally a remote mapper.
183 * It does  not uses the IOC device waiting queue and server thread, and does not use
184 * the IOC IRQ, but call directly the relevant IOC driver, implementing a busy-waiting
185 * policy for the calling thread.
186 * It can be called by a thread running in any cluster.
187 ******************************************************************************************
188 * @ buffer_xp : extended pointer on target buffer in memory (must be block aligned).
189 * @ lba       : first block index on device.
190 * @ count     : number of blocks to transfer.
191 * @ returns 0 if success / returns -1 if error.
192 *****************************************************************************************/
193error_t dev_ioc_sync_read( xptr_t         buffer_xp,
194                           uint32_t       lba,
195                           uint32_t       count );
196
197/******************************************************************************************
198 * This blocking function moves one or several contiguous blocks of data
199 * from a - possibly remote - memory buffer to the block device.
200 * It uses an extended pointer, because the target buffer is generally a remote mapper.
201 * It does  not uses the IOC device waiting queue and server thread, and does not use
202 * the IOC IRQ, but call directly the relevant IOC driver, implementing a busy-waiting
203 * policy for the calling thread.
204 * It can be called by a thread running in any cluster.
205 ******************************************************************************************
206 * @ buffer_xp : extended pointer on source buffer in memory (must be block aligned).
207 * @ lba       : first block index on device.
208 * @ count     : number of blocks to transfer.
209 * @ returns 0 if success / returns -1 if error.
210 *****************************************************************************************/
211error_t dev_ioc_sync_write( xptr_t         buffer_xp,
212                            uint32_t       lba,
213                            uint32_t       count );
214
215#endif  /* _DEV_IOC_H */
Note: See TracBrowser for help on using the repository browser.