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

Last change on this file since 647 was 647, checked in by alain, 2 years ago

...miscelaneous...

File size: 7.8 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 *
41 * It supports four command types:
42 * - READ       : move blocks from device to memory, with a descheduling policy.
43 * - WRITE      : move blocks from memory to device, with a descheduling policy.
44 * - SYNC_READ  : move blocks from device to memory, with a busy waiting policy.
45 * - SYNC_WRITE : move blocks from memory to device, with a busy waiting policy.
46 *
47 * For the he READ or WRITE operations, the client thread is descheduled, and the work
48 * is done by the server thread associated to the IOC device:
49 * The client thread calls the dev_ioc_move_data() kernel functions that (i) registers
50 * the command in the client thread descriptor, (ii) registers the client thread
51 * in the IOC device waiting queue, and (iii) blocks on the THREAD_BLOCKED_IO condition
52 * and deschedules.
53 * 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 IOC device implementations have a DMA capability, but some implementations,
56 * such as the RDK (Ram Disk) implementation does not use DMA.
57 * When the server thread completes an I/O operation, it reactivates the client thread.
58 *
59 * The SYNC_READ and SYNC_WRITE operations are used by the kernel in the initialisation
60 * phase, to update the FAT (both the FAT mapper and the FAT on IOC device), or to update
61 * a directory on IOC device when a new file is created.
62 * These synchronous operations do not not use the IOC device waiting queue,
63 * the server thread, and the IOC IRQ. The client thread does not deschedules:
64 * it registers the command in the thread descriptor, calls directly the IOC driver,
65 * and uses a busy-waiting policy to poll the IOC device status.
66 *****************************************************************************************/
67
68/******************************************************************************************
69 * This defines the (implementation independant) extension for the generic IOC device.
70 *****************************************************************************************/
71
72typedef struct ioc_extend_s
73{
74    uint32_t    size;      /*! number of bytes in a block                               */
75    uint32_t    count;     /*! total number of blocks in physical device                */
76}
77ioc_extend_t;
78
79/******************************************************************************************
80 * This enum defines the various implementations of the generic IOC peripheral.
81 * It must be kept consistent with the define in arch_info.h file.
82 *****************************************************************************************/
83
84typedef enum
85{
86    IMPL_IOC_BDV =   0,     
87    IMPL_IOC_HBA =   1, 
88    IMPL_IOC_SDC =   2,
89    IMPL_IOC_SPI =   3,
90    IMPL_IOC_RDK =   4,
91}
92ioc_impl_t;
93
94/******************************************************************************************
95 * This defines the (implementation independant)  command passed to the driver.
96 *****************************************************************************************/
97
98typedef enum
99{
100    IOC_READ       = 0,
101    IOC_WRITE      = 1,
102    IOC_SYNC_READ  = 2,
103    IOC_SYNC_WRITE = 3,
104}
105cmd_type_t;
106
107typedef struct ioc_command_s
108{
109    xptr_t      dev_xp;     /*! extended pointer on IOC device descriptor                */
110    uint32_t    type;       /*! command type above                                       */
111    uint32_t    lba;        /*! first block index                                        */
112    uint32_t    count;      /*! number of blocks                                         */
113    xptr_t      buf_xp;     /*! extended pointer on memory buffer                        */
114    uint32_t    error;      /*! operation status (0 if success)                          */
115}
116ioc_command_t;
117
118/******************************************************************************************
119 * This function returns a printable string for a IOC command type.
120 ******************************************************************************************
121 * @ cmd  : command type.
122 * @ return pointer on string.
123 *****************************************************************************************/
124char * dev_ioc_cmd_str( cmd_type_t cmd );
125
126/******************************************************************************************
127 * This function completes the IOC chdev descriptor initialisation,
128 * namely the link with the implementation specific driver.
129 * The func, impl, channel, is_rx, base fields have been previously initialised.
130 * It calls the specific driver initialisation function, to initialise the hardware
131 * device and the specific data structures when required.
132 * It creates the associated server thread and allocates a WTI from local ICU.
133 * It must de executed by a local thread.
134 ******************************************************************************************
135 * @ chdev     : local pointer on IOC chdev descriptor.
136 *****************************************************************************************/
137void dev_ioc_init( struct chdev_s * chdev );
138
139/******************************************************************************************
140 * This blocking function moves <count> contiguous blocks of data between the block device
141 * starting from block defined by the <lba> argument and a kernel memory buffer, defined
142 * by the <buffer_xp> argument. The transfer direction and mode are defined by the
143 * <cmd_type> argument. The request is always registered in the calling thread descriptor.
144 * - In synchronous mode, the calling thread is not descheduled, and directly calls the
145 *   IOC driver, polling the IOC status to detect transfer completion.
146 * - In asynchronous mode, the calling thread blocks and deschedules, and the IOC driver
147 *   is called by the server thread associated to the IOC device.
148 ******************************************************************************************
149 * @ cmd_type  : IOC_READ / IOC_WRITE / IOC_SYNC_READ / IOC_SYN_WRITE.
150 * @ buffer_xp : extended pointer on kernel buffer in memory (must be block aligned).
151 * @ lba       : first block index on device.
152 * @ count     : number of blocks to transfer.
153 * @ returns 0 if success / returns -1 if error.
154 *****************************************************************************************/
155error_t dev_ioc_move_data( uint32_t  cmd_type,
156                           xptr_t    buffer_xp,
157                           uint32_t  lba,
158                           uint32_t  count );
159
160#endif  /* _DEV_IOC_H */
Note: See TracBrowser for help on using the repository browser.