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 | |
---|
31 | struct 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 | |
---|
68 | typedef 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 | } |
---|
73 | ioc_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 | |
---|
80 | enum 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 | } |
---|
88 | ioc_impl_t; |
---|
89 | |
---|
90 | /****************************************************************************************** |
---|
91 | * This defines the (implementation independant) command passed to the driver. |
---|
92 | *****************************************************************************************/ |
---|
93 | |
---|
94 | typedef 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 | } |
---|
103 | ioc_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 | *****************************************************************************************/ |
---|
117 | void 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 | *****************************************************************************************/ |
---|
131 | error_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 | *****************************************************************************************/ |
---|
147 | error_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 | *****************************************************************************************/ |
---|
169 | void dev_ioc_server( struct device_s * dev ); |
---|
170 | |
---|
171 | #endif /* _DEV_IOC_H */ |
---|