source: trunk/kernel/fs/devfs.h @ 675

Last change on this file since 675 was 673, checked in by alain, 4 years ago

Introduce the DEBUG_VFS_ERROR in kernel_config to make
error messges display conditional.
File size: 9.0 KB
RevLine 
[23]1/*
2 * devfs.h - DEVFS File System API definition                               
3 *
4 * Authors       Mohamed Lamine Karaoui (2014,2015)
[673]5 *               Alain Greiner          (2016,2017,2018,2019,2020)
[23]6 *
7 * Copyright (c) 2011,2012 UPMC Sorbonne Universites
8 *
9 * This file is part of ALMOS-MKH.
10 *
11 * ALMOS-MKH is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; version 2.0 of the License.
14 *
15 * ALMOS-MKH is distributed in the hope that it will be useful, but
16 * WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 * General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License
21 * along with ALMOS-MKH; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
23 */
24
25#ifndef _DEVFS_H_
26#define _DEVFS_H_
27
[657]28
[188]29//////////////////////////////////////////////////////////////////////////////////////////
[657]30// The DEVFS File System contains the inodes and dentries associated to the chdev
31// descriptors available in the architecture.
[238]32//
33// It is structured as a three levels tree structure :
[188]34// - The "dev" directory inode is stored in cluster_IO. It is the root of the DEVFS
35//   file system. The parent inode is the "/" VFS root.
[23]36// - There is one "internal_cxy" directory inode per cluster, that is the parent of
[188]37//   the local children inodes associated to the local, internal chdev descriptors.
38//   The parent dentry is stored in cluster_IO.
[23]39// - The I/O cluster contains one "external" directory inode, that is the parent of
[188]40//   the remote children inodes associated to the remote external chdev descriptors.
41//   The parent dentry is stored in cluster_IO.
[23]42//
[238]43// The DEVFS extensions to the generic VFS are the following:
[657]44// 1) The vfs_ctx_t "extend" field is pointing on the devfs_ctx_t structure.
45// 2) The vfs_inode_t "extend" field is pointing on the chdev descriptor.
[188]46//////////////////////////////////////////////////////////////////////////////////////////
[23]47
[188]48/*****************************************************************************************
49 * This structure defines the DEVFS context extension.
50 ****************************************************************************************/
[23]51
[188]52typedef struct devfs_ctx_s
[23]53{
[204]54    xptr_t   dev_inode_xp;               /*! extended pointer on DEVFS root inode       */ 
[188]55    xptr_t   external_inode_xp;          /*! extended pointer on DEVFS external inode   */ 
[23]56}
[188]57devfs_ctx_t;
[23]58/*****************************************************************************************
[657]59 * This fuction allocates memory for a DEVFS context descriptor in cluster identified
60 * by the <cxy> argument.
[23]61 *****************************************************************************************
[657]62 * @ cxy     : [in] target cluster identifier.
63 * @ return an extended pointer on the created context / return NULL if failure.
[23]64 ****************************************************************************************/
[657]65xptr_t  devfs_ctx_alloc( cxy_t cxy );
[23]66
67/*****************************************************************************************
[188]68 * This function initialises the DEVFS context from arguments values, and link it
69 * to the relevant VFS context in the local cluster.
70 *****************************************************************************************
[657]71 * @ devfs_ctx               : [in]  extended pointer on DEVFS context.
[204]72 * @ devfs_dev_inode_xp      : [out] extended pointer on  <dev> inode.
73 * @ devfs_external_inode_xp : [out] extended pointer on  <external> inode.
[23]74 ****************************************************************************************/
[657]75void devfs_ctx_init( xptr_t    devfs_ctx_xp,
76                     xptr_t    devfs_dev_inode_xp,
77                     xptr_t    devfs_external_inode_xp );
[23]78
79/*****************************************************************************************
[188]80 * This function releases memory dynamically allocated for the DEVFS context.
[23]81 *****************************************************************************************
[188]82 * @ devfs_ctx   : local pointer on DEVFS context.
[23]83 ****************************************************************************************/
[657]84void devfs_ctx_destroy( xptr_t  devfs_ctx_xp );
[23]85
86/*****************************************************************************************
[657]87 * This function starts to create the DEVFS subtree.
88 * This function creates in cluster 0 the "dev" and "external" DEVFS directories.
89 * For each one, it creates the inode and the associated dentry. The DEVFS root inode
90 * <dev is linked to the VFS parent inode identified by <parent_inode_xp>.
[23]91 *****************************************************************************************
[657]92 * @ parent_inode_xp         : [in]  extended pointer on the parent VFS inode.
[204]93 * @ devfs_dev_inode_xp      : [out] extended pointer on created <dev> inode.
[188]94 * @ devfs_external_inode_xp : [out] extended pointer on created <external> inode.
[23]95 ****************************************************************************************/
[188]96void devfs_global_init( xptr_t   parent_inode_xp,
[204]97                        xptr_t * devfs_dev_inode_xp,
[188]98                        xptr_t * devfs_external_inode_xp );
[23]99
100/*****************************************************************************************
[188]101 * This function completes the initialisation of the DEVFS subtree.
102 * It should be called once in each cluster.
103 * 1. In each cluster (i), it creates the "internal" directory,
104 *    linked to the DEVFS "dev" parent directory.
[657]105 * 2. In each cluster (i), it creates, for each external chdev in cluster (i),
[188]106 *    a pseudo-file, linked to the DEVFS "external" parent directory.
[657]107 * 3. In each cluster (i), it creates, for each internal chdev in cluster (i),
[188]108 *    a pseudo-file, linked to the DEVFS "internal" parent directory.
109 *****************************************************************************************
[657]110 * @ devfs_dev_inode_xp      : [in]  extended pointer on DEVFS root inode.
111 * @ devfs_external_inode_xp : [in]  extended pointer on DEVFS external inode.
[23]112 ****************************************************************************************/
[204]113void devfs_local_init( xptr_t   devfs_dev_inode_xp,
[657]114                       xptr_t   devfs_external_inode_xp );
[188]115                       
[407]116/******************************************************************************************
[598]117 * This function is called by the sys_read() and sys_write() functions.
118 * It moves <size> bytes between a TXT device, and an user space <u_buf> buffer.
119 * It uses the <file_xp> and <to_buffer> arguments, to call the relevant device function.
120 * It uses a kernel buffer allocated in the calling thread kernel stack.
121 * If the <size> argument is larger than CONFIG_TXT_KBUF_SIZE, the user buffer is split
122 * in smaller chunks to be copied from the user buffer to this kernel buffer.
[407]123 ******************************************************************************************
124 * @ to_buffer : device -> buffer if true / buffer -> device if false.
125 * @ file_xp   : extended pointer on the remote file descriptor.
126 * @ u_buf     : user space buffer (virtual address).
127 * @ size      : requested number of bytes from offset.
128 * @ returns number of bytes actually moved if success / -1 if error.
129 *****************************************************************************************/
130int devfs_user_move( bool_t   to_buffer,
131                     xptr_t   file_xp, 
[598]132                     char   * u_buf,
[407]133                     uint32_t size );
134
[612]135/******************************************************************************************
136 * As the DEVFS is dynamically build in memory during kernel init, all relevant
137 * information is contained in the Inode Tree. Therefore, this function simply
138 * access the xhtab contained in the <inode> descriptor, to get the  dentries
139 * to be copied in the dirent <array>.
140 ******************************************************************************************
141 * @ inode      : [in]  local pointer on directory inode.
142 * @ array      : [in]  local pointer on array of dirents.
143 * @ max_dirent : [in]  max number of slots in dirent array.
144 * @ min_dentry : [in]  index of first dentry to be copied into array.
145 * @ detailed   : [in]  dynamic inode creation if true.
146 * @ entries    : [out] number of dentries actually copied into array.
147 * @ done       : [out] Boolean true when last entry found.
148 * @ return 0 if success / return -1 if failure.
149 *****************************************************************************************/
150error_t devfs_get_user_dir( struct vfs_inode_s * inode,
151                            struct dirent      * array,
152                            uint32_t             max_dirent,
153                            uint32_t             min_dentry,
154                            bool_t               detailed,
155                            uint32_t           * entries,
156                            bool_t             * done );
[407]157
[612]158
[23]159#endif  /* _DEVFS_H_ */
Note: See TracBrowser for help on using the repository browser.