share/man/man4/geom_map.4

   1 .\"
   2 .\" Copyright (c) 2011 Aleksandr Rybalko
   3 .\" 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 .\" $FreeBSD$
  27 .\"
  28 .Dd May 17, 2011
  29 .Dt GEOM_MAP 4
  30 .Os
  31 .Sh NAME
  32 .Nm geom_map
  33 .Nd "GEOM module that maps defined items as separate partitions"
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel,
  36 place the following line in your
  37 kernel configuration file:
  38 .Bd -ragged -offset indent
  39 .Cd "device geom_map"
  40 .Ed
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 framework provides support for mapping defined parts of the media.
  45 Basically it is helpful for embedded devices where in the one continuous
  46 flash are loader, kernel and rootfs parts.
  47 .Nm
  48 allows making them available as separate parts and protects the loader from
  49 being overwritten.
  50 .Pp
  51 At boot time
  52 .Nm
  53 partitions are listed (only with bootverbose) as:
  54 .Bd -literal -offset indent
  55 MAP: 0x30000, data=0x30000 "/dev/map/bootloader"
  56 MAP: 30000x10000, data=0x10000 "/dev/map/factory"
  57 MAP: 40000x7a0000, data=0x7a0000 "/dev/map/upgrade"
  58 MAP: search key ".!/bin/sh" from 0x100000, step 0x10000
  59 MAP: 40000x110000, data=0x110000 "/dev/map/kernel"
  60 MAP: search key ".!/bin/sh" from 0x100000, step 0x10000
  61 MAP: 150000x690000, data=0x690000 "/dev/map/rootfs"
  62 MAP: 7e0000x20000, data=0x20000 "/dev/map/config"
  63 .Ed
  64 .Pp
  65 The current
  66 .Nm
  67 configuration can be accessed with the following
  68 .Xr sysctl 8
  69 nodes:
  70 .Va kern.geom.conftxt , kern.geom.confxml ,
  71 and
  72 .Va kern.geom.confdot
  73 or by using
  74 .Dq Li "geom map list" .
  75 .Bd -literal -offset indent
  76 # sysctl -n kern.geom.conftxt
  77 0 MD md0 10485760 512 u 0 s 512 f 0 fs 0 l 10485760 t malloc
  78 0 DISK cfid0 8388608 4 hd 0 sc 0
  79 1 MAP map/config 131072 4 i 5 o 8257536 entry 0 dsize 131072
  80 1 MAP map/rootfs 6881280 4 i 4 o 1376256 entry 0 dsize 6881280
  81 2 UNCOMPRESS map/rootfs.uncompress 18677760 512
  82 1 MAP map/kernel 1114112 4 i 3 o 262144 entry 0 dsize 1114112
  83 1 MAP map/upgrade 7995392 4 i 2 o 262144 entry 0 dsize 7995392
  84 1 MAP map/factory 65536 4 i 1 o 196608 entry 0 dsize 65536
  85 1 MAP map/bootloader 196608 4 i 0 o 0 entry 0 dsize 196608
  86 .Ed
  87 .Pp
  88 Driver configuration can be done in
  89 .Xr device.hints 5 .
  90 List of used parameters:
  91 .Bl -tag -width indent
  92 .It Va at
  93 select media to attach
  94 .It Va name
  95 name of partition (will create device
  96 .Pa /dev/map/ Ns Ar that_name )
  97 .It Va start
  98 offset from the beginning of the parent media to start of the mapped partition.
  99 This field can also have a special value
 100 .Qq Li search: Ns Ar searchstart Ns Li : Ns Ar searchstep Ns Li : Ns Ar searchkey ,
 101 where:
 102 .Bl -tag -width indent
 103 .It Ar searchstart
 104 offset from the beginning of the parent media where search will be started
 105 .It Ar searchstep
 106 value of the increment used while searching for the partition boundary markers
 107 .It Ar searchkey
 108 key which will be used to find partition boundary markers.
 109 The wildcard
 110 .Ql .\&
 111 can be used to match any character on that position
 112 .El
 113 .It Va end
 114 offset from the beginning of the parent media to the end of the mapped partition.
 115 This field can also have the special value
 116 .Qq Li search: Ns Ar searchstart Ns Li : Ns Ar searchstep Ns Li : Ns Ar searchkey ,
 117 as described above.
 118 .It Va offset
 119 offset where the data of the mapped partition begins
 120 .El
 121 .Pp
 122 Each record contains the start address (in bytes) from the media begin, size
 123 (in bytes), offset where the data of mapped partition begins, and the name of
 124 new device.
 125 .Bd -literal -offset indent
 126 MAP: 150000x690000, data=0x690000 "/dev/map/rootfs"
 127 .Ed
 128 .Bd -literal
 129 00150000 - start address
 130 00690000 - size
 131 00000000 - data begin from zero offset
 132 00690000 - data size
 133 "map/rootfs" - new media will be accessible via /dev/map/rootfs dev.
 134 .Ed
 135 .Sh EXAMPLES
 136 If we need to implement layout shown above, we need to define the following
 137 hints:
 138 .Bd -literal -offset indent
 139 hint.map.0.at="cfid0"
 140 hint.map.0.start=0x00000000
 141 hint.map.0.end=0x00030000
 142 hint.map.0.name="bootloader"
 143 hint.map.0.readonly=1
 144 .Ed
 145 .Pp
 146 This defines
 147 .Pa /dev/map/bootloader
 148 at disk
 149 .Pa cfid0
 150 starting at
 151 .Li 0x00000000
 152 and ending at
 153 .Li 0x00030000 ,
 154 it is also marked as readonly.
 155 .Bd -literal -offset indent
 156 hint.map.1.at="cfid0"
 157 hint.map.1.start=0x00030000
 158 hint.map.1.end=0x00040000
 159 hint.map.1.name="factory"
 160
 161 hint.map.2.at="cfid0"
 162 hint.map.2.start=0x00040000
 163 hint.map.2.end=0x007e0000
 164 hint.map.2.name="upgrade"
 165
 166 hint.map.3.at="cfid0"
 167 hint.map.3.name="kernel"
 168 hint.map.3.start=0x00040000
 169 hint.map.3.end="search:0x00100000:0x10000:.!/bin/sh"
 170 .Ed
 171 .Pp
 172 This defines
 173 .Pa /dev/map/kernel
 174 at disk
 175 .Pa cfid0
 176 starting at
 177 .Li 0x00040000 ,
 178 but the end position must be searched by finding the key
 179 .Dq Li ".!/bin/sh" ,
 180 from offset
 181 .Li 0x00100000
 182 to the end of media with step
 183 .Li 0x10000 .
 184 The real marker in this case is
 185 .Dq Li "#!/bin/sh" ,
 186 but
 187 .Ql #
 188 terminates the line when the hints file is parsed, so we need to use wildcard
 189 .Ql .\&
 190 instead of
 191 .Ql # .
 192 .Bd -literal -offset indent
 193 hint.map.4.at="cfid0"
 194 hint.map.4.name="rootfs"
 195 hint.map.4.start="search:0x00100000:0x10000:.!/bin/sh"
 196 hint.map.4.end=0x007e0000
 197
 198 hint.map.5.at="cfid0"
 199 hint.map.5.start=0x007e0000
 200 hint.map.5.end=0x00800000
 201 hint.map.5.name="config"
 202 .Ed
 203 .Sh SEE ALSO
 204 .Xr geom 4 ,
 205 .Xr geom 8 ,
 206 .Xr sysctl 8
 207 .Sh AUTHORS
 208 The
 209 .Nm
 210 driver was written by
 211 .An "Aleksandr Rybalko" Aq ray@ddteam.net .