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

Last change on this file since 453 was 437, checked in by alain, 7 years ago

Fix various bugs
File size: 9.1 KB
RevLine 
[1]1/*
2 * dev_ioc.h - IOC (Block Device Controler) generic device API definition.
3 *
[437]4 * Author  Alain Greiner    (2016,2017,2018)
[1]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
[14]27#include <kernel_config.h>
[1]28#include <hal_types.h>
29
30/****  Forward declarations  ****/
31
[3]32struct chdev_s;
[1]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).
[23]40 * It supports three 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
45 * A READ or WRITE operation requires dynamic ressource allocation. The calling thread
46 * is descheduled, and the work is done by the server thread associated to IOC device.
47 * The general scenario is detailed below.
[1]48 * A) the client thread start the I/O operation, by calling the dev_ioc_read()
49 *    or the dev_ioc_write() kernel functions that perform the following actions:
50 *    1) it get a free WTI mailbox from the client cluster WTI allocator.
51 *    2) it enables the WTI IRQ on the client cluster ICU and update interrupt vector.
52 *    3) it access the PIC to link the WTI mailbox to the IOC IRQ.
53 *    4) it builds the command descriptor.
[23]54 *    5) it registers in the IOC device waiting queue.
[1]55 *    6) itblock on the THREAD_BLOCKED_IO condition and deschedule.
56 * B) The server thread attached to the IOC device descriptor handles the commands
57 *    registered in the waiting queue, calling the IOC driver function.
58 *    Most hardware implementation have a DMA capability, but some implementations,
59 *    such as the RDK (Ram Disk) implementation does not use DMA.
60 * C) The ISR signaling the I/O operation completion reactivates the client thread,
61 *    that releases the allocated resources:
62 *    1) access the PIC to unlink the IOC IRQ.
63 *    2) disable the WTI IRQ in the client cluster ICU and update interrupt vector.
64 *    3) release the WTI mailbox to the client cluster WTI allocator.
[23]65 *
66 * The SYNC_READ operation is used by the kernel in the initialisation phase. It does
67 * not uses the IOC device waiting queue and server thread, and does not use the IOC IRQ,
68 * but implement a busy-waiting policy for the calling thread.
[1]69 *****************************************************************************************/
70
71/******************************************************************************************
72 * This defines the (implementation independant) extension for the generic IOC device.
73 *****************************************************************************************/
74
75typedef struct ioc_extend_s
76{
77    uint32_t    size;      /*! number of bytes in a block                               */
78    uint32_t    count;     /*! total number of blocks in physical device                */
79}
80ioc_extend_t;
81
82/******************************************************************************************
83 * This enum defines the various implementations of the generic IOC peripheral.
84 * It must be kept consistent with the define in arch_info.h file.
85 *****************************************************************************************/
86
87enum ioc_impl_e
88{
89    IMPL_IOC_BDV =   0,     
90    IMPL_IOC_HBA =   1, 
91    IMPL_IOC_SDC =   2,
92    IMPL_IOC_SPI =   3,
93    IMPL_IOC_RDK =   4,
94}
95ioc_impl_t;
96
97/******************************************************************************************
98 * This defines the (implementation independant)  command passed to the driver.
99 *****************************************************************************************/
100
[23]101enum
102{
103    IOC_READ       = 0,
104    IOC_WRITE      = 1,
105    IOC_SYNC_READ  = 2,
106};
107
[1]108typedef struct ioc_command_s
109{
[188]110    xptr_t      dev_xp;     /*! extended pointer on IOC device descriptor                */
[23]111    uint32_t    type;       /*! IOC_READ / IOC_WRITE / IOC_SYNC_READ                     */
[1]112    uint32_t    lba;        /*! first block index                                        */
113    uint32_t    count;      /*! number of blocks                                         */
114    xptr_t      buf_xp;     /*! extended pointer on memory buffer                        */
115    uint32_t    error;      /*! operation status (0 if success)                          */
116}
117ioc_command_t;
118
119/******************************************************************************************
[3]120 * This function completes the IOC chdev descriptor initialisation,
[1]121 * namely the link with the implementation specific driver.
[3]122 * The func, impl, channel, is_rx, base fields have been previously initialised.
[1]123 * It calls the specific driver initialisation function, to initialise the hardware
124 * device and the specific data structures when required.
[3]125 * It creates the associated server thread and allocates a WTI from local ICU.
126 * It must de executed by a local thread.
[1]127 ******************************************************************************************
[3]128 * @ chdev     : local pointer on IOC chdev descriptor.
[1]129 *****************************************************************************************/
[3]130void dev_ioc_init( struct chdev_s * chdev );
[1]131
132/******************************************************************************************
133 * This blocking function try to tranfer one or several contiguous blocks of data
[23]134 * from the block device to a local memory buffer. The corresponding request is actually
[1]135 * registered in the device pending request queue, and the calling thread is descheduled,
136 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
137 * It must be called in the client cluster.
138 ******************************************************************************************
[23]139 * @ buffer    : local pointer on target buffer in memory (must be block aligned).
[1]140 * @ lba       : first block index on device.
141 * @ count     : number of blocks to transfer.
142 * @ returns 0 if success / returns EINVAL if error.
143 *****************************************************************************************/
[23]144error_t dev_ioc_read( uint8_t      * buffer,
[1]145                      uint32_t       lba,
146                      uint32_t       count );
147
148/******************************************************************************************
149 * This blocking function try to tranfer one or several contiguous blocks of data
[23]150 * from a local memory buffer to the block device. The corresponding request is actually
[1]151 * registered in the device pending request queue, and the calling thread is descheduled,
152 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
153 * It must be called in the client cluster.
154 ******************************************************************************************
[23]155 * @ buffer    : local pointer on source buffer in memory (must be block aligned).
[1]156 * @ lba       : first block index on device.
157 * @ count     : number of blocks to transfer.
158 * @ returns 0 if success / returns EINVAL if error.
159 *****************************************************************************************/
[23]160error_t dev_ioc_write( uint8_t      * buffer,
[1]161                       uint32_t       lba,
162                       uint32_t       count );
163
[23]164/******************************************************************************************
165 * This blocking function try to tranfer one or several contiguous blocks of data
166 * from the block device to a memory buffer.
167 * It does  not uses the IOC device waiting queue and server thread, and does not use
[246]168 * the IOC IRQ, but call directly the relevant IOC driver, implementing a busy-waiting
[23]169 * policy for the calling thread.
170 * It must be called in the client cluster.
171 ******************************************************************************************
172 * @ buffer    : local pointer on target buffer in memory (must be block aligned).
173 * @ lba       : first block index on device.
174 * @ count     : number of blocks to transfer.
175 * @ returns 0 if success / returns EINVAL if error.
176 *****************************************************************************************/
177error_t dev_ioc_sync_read( uint8_t      * buffer,
178                           uint32_t       lba,
179                           uint32_t       count );
180
[1]181#endif  /* _DEV_IOC_H */
Note: See TracBrowser for help on using the repository browser.