1.\" $NetBSD: rump_etfs.3,v 1.4 2015/06/12 17:50:01 dholland Exp $ 2.\" 3.\" Copyright (c) 2010 Antti Kantee. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd October 27, 2014 27.Dt RUMP_ETFS 3 28.Os 29.Sh NAME 30.Nm rump_etfs 31.Nd rump kernel host file system interface 32.Sh LIBRARY 33rump kernel (librump, \-lrump) 34.Sh SYNOPSIS 35.In rump/rump.h 36.Ft int 37.Fo rump_pub_etfs_register 38.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype" 39.Fc 40.Ft int 41.Fo rump_pub_etfs_register_withsize 42.Fa "const char *key" "const char *hostpath" "enum rump_etfs_type ftype" 43.Fa "uint64_t begin" "uint64_t size" 44.Fc 45.Ft void 46.Fn rump_boot_etfs_register "struct rump_boot_etfs *eb" 47.Ft int 48.Fn rump_pub_etfs_remove "const char *key" 49.Sh DESCRIPTION 50The rump ExtraTerrestrial File System 51.Nm ( ) 52is used to provide access to the host file system namespace 53within a rump kernel. 54.Pp 55The operation is based on registered 56.Fa key 57values which each map to a 58.Fa hostpath . 59A key must be an absolute path (i.e. begin with 60.Dq / ) . 61Multiple leading slashes are collapsed to one (i.e. 62.Dq /key 63is the same as 64.Dq //key ) . 65The rest of the path, including slashes, is compared verbatim (i.e. 66.Dq /key/path 67does not match 68.Dq /key//path ) . 69.Pp 70The 71.Fa hostpath 72is interpreted in host system context for the current working directory 73and can be either absolute or relative. 74.Pp 75The 76.Fa key 77is accessible from all rump kernel clients, both local and remote. 78Note: the keys are not visible via readdir, so you will not see 79them in directory listings. 80.Pp 81The 82.Fa ftype 83parameter specifies how the etfs file will be presented and does not 84have to match the host type, although some limitations apply. 85Possible values are: 86.Bl -tag -width RUMP_ETFS_DIR_SUBDIRSXXX 87.It Dv RUMP_ETFS_REG 88regular file. 89.It Dv RUMP_ETFS_BLK 90block device. 91This is often used when mapping file system images. 92.It Dv RUMP_ETFS_CHR 93character device. 94.It Dv RUMP_ETFS_DIR 95directory. 96This option is valid only when 97.Fa hostpath 98is a directory. 99The immediate children of the host directory will be accessible 100inside a rump kernel. 101.It Dv RUMP_ETFS_DIR_SUBDIRS 102directory. 103This option is valid only when 104.Fa hostpath 105is a directory. 106This option recursively applies to all subdirectories, and allows 107a rump kernel to access an entire directory tree. 108.El 109.Pp 110The interfaces are: 111.Bl -tag -width xxxx 112.It Fn rump_pub_etfs_register "key" "hostpath" "ftype" 113Map 114.Fa key 115to a file of type 116.Fa ftype 117with the contents of 118.Fa hostpath . 119.It Fn rump_pub_etfs_register_withsize "key" "hostpath" "ftype" "begin" "size" 120Like the above, but map only 121.Fa [ begin , begin+size ] 122from 123.Fa hostpath . 124This is useful when mapping disk images where only one partition is 125relevant to the application. 126If 127.Ar size 128is given the special value 129.Dv RUMP_ETFS_SIZE_ENDOFF , 130the underlying file is mapped from 131.Ar begin 132to the end of the file. 133.It Fn rump_boot_etfs_register "eb" 134Unlike the above interfaces, 135.Fn rump_boot_etfs_register 136can and must be called before 137.Fn rump_init . 138It causes an etfs key to be available immediately when the root file 139system is mounted as part of 140.Fn rump_init . 141The intended use is for example for firmware images to be available 142immediately when device driver autoconfiguration is run as part of 143.Fn rump_init . 144.Pp 145To use 146.Fn rump_boot_etfs_register , 147the client fills out 148.Fa eb . 149The layout of 150.Fa eb 151is as follows: 152.Bd -literal 153struct rump_boot_etfs { 154 /* client initializes */ 155 const char *eb_key; 156 const char *eb_hostpath; 157 enum rump_etfs_type eb_type; 158 uint64_t eb_begin; 159 uint64_t eb_size; 160 161 /* rump kernel initializes */ 162 struct rump_boot_etfs *_eb_next; 163 int eb_status; 164}; 165.Ed 166.Pp 167All of the client fields must be initialized before the call. 168See 169.Fn rump_pub_etfs_register_withsize 170for descriptions of the fields. 171After the function has been called, the client may not touch the 172structure memory or the pathname pointers. 173After 174.Fn rump_init 175returns, the client may check the status of the registration from 176.Fa eb_status 177and free the structure. 178A value of \-1 designates that the etfs registration was not 179performed, 0 designates success and a value larger than 0 designates 180an errno. 181The client must serialize calls to 182.Fn rump_boot_etfs_register . 183.It Fn rump_pub_etfs_remove "key" 184Remove etfs mapping for 185.Fa key . 186This routine may be called only if the file related to the mapping 187is not in use. 188.El 189.Sh RETURN VALUES 190.Nm 191routines return 0 on success or an errno indicating the reason for failure. 192.Sh EXAMPLES 193Map a host image file to a mountable 194.Pa /dev/harddisk 195path using window offsets from the disklabel. 196.Bd -literal -offset indent 197rump_pub_etfs_register_withsize("/dev/harddisk", "disk.img", 198 RUMP_ETFS_BLK, 199 pp->p_offset << DEV_BSHIFT, pp->p_size << DEV_BSHIFT); 200.Ed 201.Pp 202Make the host kernel module directory hierarchy available within the 203rump kernel. 204.Bd -literal -offset indent 205rump_pub_etfs_register("/stand/i386/5.99.41", 206 "/stand/i386/5.99.41", RUMP_ETFS_DIR_SUBDIRS); 207.Ed 208.Sh SEE ALSO 209.Xr rump 3 210.Sh HISTORY 211.Nm 212first appeared in 213.Nx 6.0 . 214