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 <kernel_config.h> |
---|
28 | #include <hal_types.h> |
---|
29 | |
---|
30 | /**** Forward declarations ****/ |
---|
31 | |
---|
32 | struct 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 two command types: |
---|
41 | * - READ : move a given number of contiguous blocks from device to a memory buffer. |
---|
42 | * - WRITE : move a given number of contiguous blocks from a memory buffer to device. |
---|
43 | * |
---|
44 | * An I/O operation requires dynamic ressource allocation, and is always blocking for |
---|
45 | * the client thread. The general scenario is detailed below. |
---|
46 | * A) the client thread start the I/O operation, by calling the dev_ioc_read() |
---|
47 | * or the dev_ioc_write() kernel functions that perform the following actions: |
---|
48 | * 1) it get a free WTI mailbox from the client cluster WTI allocator. |
---|
49 | * 2) it enables the WTI IRQ on the client cluster ICU and update interrupt vector. |
---|
50 | * 3) it access the PIC to link the WTI mailbox to the IOC IRQ. |
---|
51 | * 4) it builds the command descriptor. |
---|
52 | * 5) it registers in the IOCdevice waiting queue. |
---|
53 | * 6) itblock on the THREAD_BLOCKED_IO condition and deschedule. |
---|
54 | * B) The server thread attached to the IOC device descriptor handles the commands |
---|
55 | * registered in the waiting queue, calling the IOC driver function. |
---|
56 | * Most hardware implementation have a DMA capability, but some implementations, |
---|
57 | * such as the RDK (Ram Disk) implementation does not use DMA. |
---|
58 | * C) The ISR signaling the I/O operation completion reactivates the client thread, |
---|
59 | * that releases the allocated resources: |
---|
60 | * 1) access the PIC to unlink the IOC IRQ. |
---|
61 | * 2) disable the WTI IRQ in the client cluster ICU and update interrupt vector. |
---|
62 | * 3) release the WTI mailbox to the client cluster WTI allocator. |
---|
63 | *****************************************************************************************/ |
---|
64 | |
---|
65 | /****************************************************************************************** |
---|
66 | * This defines the (implementation independant) extension for the generic IOC device. |
---|
67 | *****************************************************************************************/ |
---|
68 | |
---|
69 | typedef struct ioc_extend_s |
---|
70 | { |
---|
71 | uint32_t size; /*! number of bytes in a block */ |
---|
72 | uint32_t count; /*! total number of blocks in physical device */ |
---|
73 | } |
---|
74 | ioc_extend_t; |
---|
75 | |
---|
76 | /****************************************************************************************** |
---|
77 | * This enum defines the various implementations of the generic IOC peripheral. |
---|
78 | * It must be kept consistent with the define in arch_info.h file. |
---|
79 | *****************************************************************************************/ |
---|
80 | |
---|
81 | enum ioc_impl_e |
---|
82 | { |
---|
83 | IMPL_IOC_BDV = 0, |
---|
84 | IMPL_IOC_HBA = 1, |
---|
85 | IMPL_IOC_SDC = 2, |
---|
86 | IMPL_IOC_SPI = 3, |
---|
87 | IMPL_IOC_RDK = 4, |
---|
88 | } |
---|
89 | ioc_impl_t; |
---|
90 | |
---|
91 | /****************************************************************************************** |
---|
92 | * This defines the (implementation independant) command passed to the driver. |
---|
93 | *****************************************************************************************/ |
---|
94 | |
---|
95 | typedef struct ioc_command_s |
---|
96 | { |
---|
97 | xptr_t dev_xp; /*! extended pointer on device descriptor */ |
---|
98 | uint32_t to_mem; /*! requested operation (WRITE if zero / READ if non-zero) */ |
---|
99 | uint32_t lba; /*! first block index */ |
---|
100 | uint32_t count; /*! number of blocks */ |
---|
101 | xptr_t buf_xp; /*! extended pointer on memory buffer */ |
---|
102 | uint32_t error; /*! operation status (0 if success) */ |
---|
103 | } |
---|
104 | ioc_command_t; |
---|
105 | |
---|
106 | /****************************************************************************************** |
---|
107 | * This function completes the IOC chdev descriptor initialisation, |
---|
108 | * namely the link with the implementation specific driver. |
---|
109 | * The func, impl, channel, is_rx, base fields have been previously initialised. |
---|
110 | * It calls the specific driver initialisation function, to initialise the hardware |
---|
111 | * device and the specific data structures when required. |
---|
112 | * It creates the associated server thread and allocates a WTI from local ICU. |
---|
113 | * It must de executed by a local thread. |
---|
114 | ****************************************************************************************** |
---|
115 | * @ chdev : local pointer on IOC chdev descriptor. |
---|
116 | *****************************************************************************************/ |
---|
117 | void dev_ioc_init( struct chdev_s * chdev ); |
---|
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 | #endif /* _DEV_IOC_H */ |
---|