1 files changed, 211 insertions, 0 deletions
diff --git a/share/man/man4/geom_map.4 b/share/man/man4/geom_map.4
new file mode 100644
index 0000000..6af91be
--- /dev/null
+++ b/share/man/man4/geom_map.4
@@ -0,0 +1,211 @@
+.\"
+.\" Copyright (c) 2011 Aleksandr Rybalko
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 17, 2011
+.Dt GEOM_MAP 4
+.Os
+.Sh NAME
+.Nm geom_map
+.Nd "GEOM module that maps defined items as separate partitions"
+.Sh SYNOPSIS
+To compile this driver into the kernel,
+place the following line in your
+kernel configuration file:
+.Bd -ragged -offset indent
+.Cd "device geom_map"
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+framework provides support for mapping defined parts of the media.
+Basically it is helpful for embedded devices where in the one continuous
+flash are loader, kernel and rootfs parts.
+.Nm
+allows making them available as separate parts and protects the loader from
+being overwritten.
+.Pp
+At boot time
+.Nm
+partitions are listed (only with bootverbose) as:
+.Bd -literal -offset indent
+MAP: 0x30000, data=0x30000 "/dev/map/bootloader"
+MAP: 30000x10000, data=0x10000 "/dev/map/factory"
+MAP: 40000x7a0000, data=0x7a0000 "/dev/map/upgrade"
+MAP: search key ".!/bin/sh" from 0x100000, step 0x10000
+MAP: 40000x110000, data=0x110000 "/dev/map/kernel"
+MAP: search key ".!/bin/sh" from 0x100000, step 0x10000
+MAP: 150000x690000, data=0x690000 "/dev/map/rootfs"
+MAP: 7e0000x20000, data=0x20000 "/dev/map/config"
+.Ed
+.Pp
+The current
+.Nm
+configuration can be accessed with the following
+.Xr sysctl 8
+nodes:
+.Va kern.geom.conftxt , kern.geom.confxml ,
+and
+.Va kern.geom.confdot
+or by using
+.Dq Li "geom map list" .
+.Bd -literal -offset indent
+# sysctl -n kern.geom.conftxt
+0 MD md0 10485760 512 u 0 s 512 f 0 fs 0 l 10485760 t malloc
+0 DISK cfid0 8388608 4 hd 0 sc 0
+1 MAP map/config 131072 4 i 5 o 8257536 entry 0 dsize 131072
+1 MAP map/rootfs 6881280 4 i 4 o 1376256 entry 0 dsize 6881280
+2 UNCOMPRESS map/rootfs.uncompress 18677760 512
+1 MAP map/kernel 1114112 4 i 3 o 262144 entry 0 dsize 1114112
+1 MAP map/upgrade 7995392 4 i 2 o 262144 entry 0 dsize 7995392
+1 MAP map/factory 65536 4 i 1 o 196608 entry 0 dsize 65536
+1 MAP map/bootloader 196608 4 i 0 o 0 entry 0 dsize 196608
+.Ed
+.Pp
+Driver configuration can be done in
+.Xr device.hints 5 .
+List of used parameters:
+.Bl -tag -width indent
+.It Va at
+select media to attach
+.It Va name
+name of partition (will create device
+.Pa /dev/map/ Ns Ar that_name )
+.It Va start
+offset from the beginning of the parent media to start of the mapped partition.
+This field can also have a special value
+.Qq Li search: Ns Ar searchstart Ns Li : Ns Ar searchstep Ns Li : Ns Ar searchkey ,
+where:
+.Bl -tag -width indent
+.It Ar searchstart
+offset from the beginning of the parent media where search will be started
+.It Ar searchstep
+value of the increment used while searching for the partition boundary markers
+.It Ar searchkey
+key which will be used to find partition boundary markers.
+The wildcard
+.Ql .\&
+can be used to match any character on that position
+.El
+.It Va end
+offset from the beginning of the parent media to the end of the mapped partition.
+This field can also have the special value
+.Qq Li search: Ns Ar searchstart Ns Li : Ns Ar searchstep Ns Li : Ns Ar searchkey ,
+as described above.
+.It Va offset
+offset where the data of the mapped partition begins
+.El
+.Pp
+Each record contains the start address (in bytes) from the media begin, size
+(in bytes), offset where the data of mapped partition begins, and the name of
+new device.
+.Bd -literal -offset indent
+MAP: 150000x690000, data=0x690000 "/dev/map/rootfs"
+.Ed
+.Bd -literal
+00150000 - start address
+00690000 - size
+00000000 - data begin from zero offset
+00690000 - data size
+"map/rootfs" - new media will be accessible via /dev/map/rootfs dev.
+.Ed
+.Sh EXAMPLES
+If we need to implement layout shown above, we need to define the following
+hints:
+.Bd -literal -offset indent
+hint.map.0.at="cfid0"
+hint.map.0.start=0x00000000
+hint.map.0.end=0x00030000
+hint.map.0.name="bootloader"
+hint.map.0.readonly=1
+.Ed
+.Pp
+This defines
+.Pa /dev/map/bootloader
+at disk
+.Pa cfid0
+starting at
+.Li 0x00000000
+and ending at
+.Li 0x00030000 ,
+it is also marked as readonly.
+.Bd -literal -offset indent
+hint.map.1.at="cfid0"
+hint.map.1.start=0x00030000
+hint.map.1.end=0x00040000
+hint.map.1.name="factory"
+
+hint.map.2.at="cfid0"
+hint.map.2.start=0x00040000
+hint.map.2.end=0x007e0000
+hint.map.2.name="upgrade"
+
+hint.map.3.at="cfid0"
+hint.map.3.name="kernel"
+hint.map.3.start=0x00040000
+hint.map.3.end="search:0x00100000:0x10000:.!/bin/sh"
+.Ed
+.Pp
+This defines
+.Pa /dev/map/kernel
+at disk
+.Pa cfid0
+starting at
+.Li 0x00040000 ,
+but the end position must be searched by finding the key
+.Dq Li ".!/bin/sh" ,
+from offset
+.Li 0x00100000
+to the end of media with step
+.Li 0x10000 .
+The real marker in this case is
+.Dq Li "#!/bin/sh" ,
+but
+.Ql #
+terminates the line when the hints file is parsed, so we need to use wildcard
+.Ql .\&
+instead of
+.Ql # .
+.Bd -literal -offset indent
+hint.map.4.at="cfid0"
+hint.map.4.name="rootfs"
+hint.map.4.start="search:0x00100000:0x10000:.!/bin/sh"
+hint.map.4.end=0x007e0000
+
+hint.map.5.at="cfid0"
+hint.map.5.start=0x007e0000
+hint.map.5.end=0x00800000
+hint.map.5.name="config"
+.Ed
+.Sh SEE ALSO
+.Xr geom 4 ,
+.Xr geom 8 ,
+.Xr sysctl 8
+.Sh AUTHORS
+The
+.Nm
+driver was written by
+.An "Aleksandr Rybalko" Aq ray@ddteam.net .