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

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

First import
File size: 9.0 KB
Line 
1/*
2 * dev_ioc.h - IOC (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_IOC_H
25#define _DEV_IOC_H
26
27#include <hal_types.h>
28
29/****  Forward declarations  ****/
30
31struct device_s;
32
33/*****************************************************************************************
34 *     Generic Block Device Controler definition
35 *
36 * This device provide access to an external mass storage peripheral such as a
37 * magnetic hard disk or a SD card, that can store blocks of data in a linear array
38 * of sectors indexed by a simple lba (logic block address).
39 * It supports two command types:
40 * - READ  : move a given number of contiguous blocks from device to a memory buffer.
41 * - WRITE : move a given number of contiguous blocks from a memory buffer to device.
42 *
43 * An I/O operation requires dynamic ressource allocation, and is always blocking for
44 * the client thread. The general scenario is detailed below.
45 * A) the client thread start the I/O operation, by calling the dev_ioc_read()
46 *    or the dev_ioc_write() kernel functions that perform the following actions:
47 *    1) it get a free WTI mailbox from the client cluster WTI allocator.
48 *    2) it enables the WTI IRQ on the client cluster ICU and update interrupt vector.
49 *    3) it access the PIC to link the WTI mailbox to the IOC IRQ.
50 *    4) it builds the command descriptor.
51 *    5) it registers in the IOCdevice waiting queue.
52 *    6) itblock on the THREAD_BLOCKED_IO condition and deschedule.
53 * B) 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 hardware implementation have a DMA capability, but some implementations,
56 *    such as the RDK (Ram Disk) implementation does not use DMA.
57 * C) The ISR signaling the I/O operation completion reactivates the client thread,
58 *    that releases the allocated resources:
59 *    1) access the PIC to unlink the IOC IRQ.
60 *    2) disable the WTI IRQ in the client cluster ICU and update interrupt vector.
61 *    3) release the WTI mailbox to the client cluster WTI allocator.
62 *****************************************************************************************/
63
64/******************************************************************************************
65 * This defines the (implementation independant) extension for the generic IOC device.
66 *****************************************************************************************/
67
68typedef struct ioc_extend_s
69{
70    uint32_t    size;      /*! number of bytes in a block                               */
71    uint32_t    count;     /*! total number of blocks in physical device                */
72}
73ioc_extend_t;
74
75/******************************************************************************************
76 * This enum defines the various implementations of the generic IOC peripheral.
77 * It must be kept consistent with the define in arch_info.h file.
78 *****************************************************************************************/
79
80enum ioc_impl_e
81{
82    IMPL_IOC_BDV =   0,     
83    IMPL_IOC_HBA =   1, 
84    IMPL_IOC_SDC =   2,
85    IMPL_IOC_SPI =   3,
86    IMPL_IOC_RDK =   4,
87}
88ioc_impl_t;
89
90/******************************************************************************************
91 * This defines the (implementation independant)  command passed to the driver.
92 *****************************************************************************************/
93
94typedef struct ioc_command_s
95{
96    xptr_t      dev_xp;      /*! extended pointer on device descriptor                    */
97    uint32_t    to_mem;     /*! requested operation (WRITE if zero / READ if non-zero)   */
98    uint32_t    lba;        /*! first block index                                        */
99    uint32_t    count;      /*! number of blocks                                         */
100    xptr_t      buf_xp;     /*! extended pointer on memory buffer                        */
101    uint32_t    error;      /*! operation status (0 if success)                          */
102}
103ioc_command_t;
104
105/******************************************************************************************
106 * This function completes the IOC device descriptor initialisation,
107 * namely the link with the implementation specific driver.
108 * The func, impl, channel, is_rxt, base, and size fields must be previously initialised.
109 * It calls the specific driver initialisation function, to initialise the hardware
110 * device and the specific data structures when required.
111 * It creates the associated server thread.
112 * It can be executed in another cluster than the cluster containing the device descriptor
113 * or the hardware device itself.
114 ******************************************************************************************
115 * @ xp_dev     : extended pointer on IOC device descriptor.
116 *****************************************************************************************/
117void dev_ioc_init( xptr_t  xp_dev );
118
119/******************************************************************************************
120 * This blocking function try to tranfer one or several contiguous blocks of data
121 * from the block device to a memory buffer. The corresponding request is actually
122 * registered in the device pending request queue, and the calling thread is descheduled,
123 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
124 * It must be called in the client cluster.
125 ******************************************************************************************
126 * @ buffer    : local pointer on target buffer in memory.
127 * @ lba       : first block index on device.
128 * @ count     : number of blocks to transfer.
129 * @ returns 0 if success / returns EINVAL if error.
130 *****************************************************************************************/
131error_t dev_ioc_read( char         * buffer,
132                      uint32_t       lba,
133                      uint32_t       count );
134
135/******************************************************************************************
136 * This blocking function try to tranfer one or several contiguous blocks of data
137 * from a memory buffer to the block device. The corresponding request is actually
138 * registered in the device pending request queue, and the calling thread is descheduled,
139 * waiting on transfer completion. It will be resumed by the IRQ signaling completion.
140 * It must be called in the client cluster.
141 ******************************************************************************************
142 * @ buffer    : local pointer on source buffer in memory.
143 * @ lba       : first block index on device.
144 * @ count     : number of blocks to transfer.
145 * @ returns 0 if success / returns EINVAL if error.
146 *****************************************************************************************/
147error_t dev_ioc_write( char         * buffer,
148                       uint32_t       lba,
149                       uint32_t       count );
150
151/******************************************************************************************
152 * This function is executed by the server thread associated to the IOC device descriptor.
153 * This thread is created and activated by the dev_ioc_init() function.
154 * It executes an infinite loop to handle sequencially all commands registered
155 * by the client threads in the device waiting queue, calling the driver CMD function.
156 * 
157 * - If the peripheral can only handle one single command, the driver block the server
158 *   thread on the THREAD_BLOCKED_DEV_ISR condition, waiting I/O operation conmpletion.
159 *   The server thread must be reacticated by the driver ISR function.
160 * - If the peripheral can handle several commands in parallel (AHCI is an example), the
161 *   driver does not block the server thread (it is only descheduled if the number of
162 *   commands exceeeds the max number of parallel commands supported by the peripheral.
163 *
164 * When the waiting queue is empty, the server thread blocks on the THREAD_BLOCKED_CMD
165 * condition and deschedule. It is re-activated by a client thread registering a command.
166 ******************************************************************************************
167 * @ dev     : local pointer on IOC device descriptor.
168 *****************************************************************************************/
169void dev_ioc_server( struct device_s * dev );
170
171#endif  /* _DEV_IOC_H */
Note: See TracBrowser for help on using the repository browser.