freebsd-skq/share/man/man4/geom_map.4

.\"
.\" 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 June 8, 2015
.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 "options 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 UZIP map/rootfs.uzip 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 Mt ray@ddteam.net .