.\" Copyright (C) 2020 Mattia Biondi, Mikey Goldweber, Renzo Davoli
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License,
.\" as published by the Free Software Foundation, either version 3
.\" of the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA.
.\"
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "UMPS3-MKDEV" "1" "December 2022" "" "General Commands Manual"
.hy
.SH NAME
.PP
\f[V]umps3-mkdev\f[R] \[en] The umps3-mkdev device creation utility
.SH SYNOPSIS
.PP
\f[V]umps3-mkdev\f[R] -d \f[I]DISKFILE\f[R] [\f[I]DISKOPTIONS\f[R]]
.PD 0
.P
.PD
\f[V]umps3-mkdev\f[R] -f \f[I]FLASHFILE\f[R] \f[I]FILE\f[R]
[\f[I]FLASHOPTIONS\f[R]]
.SH DESCRIPTION
.PP
The command-line \f[V]umps3-mkdev\f[R] utility is used to create the
files that represent disk and flash devices.
.TP
\f[V]DISKS\f[R]:
Disks in uMPS3 are \[lq]direct access\[rq] nonvolatile read/write
devices.
The \f[V]umps3-mkdev\f[R] utility allows one to create an empty disk
only; this way an OS developer may elect any desired disk data
organization.
.TP
\f[V]\f[R]
The created \f[I]DISKFILE\f[R] represents the entire disk contents, even
when empty.
Hence this file may be very large.
It is recommended to create small disks which can be used to represent a
little portion of an otherwise very large disk unit.
.TP
\f[V]\f[R]
As with real disks, differing performance statistics result in differing
simulated drive performance.
E.g.
a faster rotation speed results in less latency delay and a smaller
sector data occupancy percentage results in shorter read/write times.
.TP
\f[V]\f[R]
The default values for all these parameters are shown when entering the
\f[V]umps3-mkdev\f[R] alone without any parameters.
.TP
\f[V]FLASH DEVICES\f[R]:
Flash devices in uMPS3 are \[lq]random access\[rq] nonvolatile
read/write devices.
A uMPS3 flash device is essentially equivalent to a seek-free
one-dimensional disk drive.
The \f[V]umps3-mkdev\f[R] utility allows one to create both slow flash
devices (e.g.\ USB stick) or fast flash devices (e.g.\ SSDs).
Furthermore, the utility allows one to create both empty flash devices
as well as ones preloaded with a specific file.
.TP
\f[V]\f[R]
The created \f[I]FLASHFILE\f[R] represents the entire device contents,
even when empty.
Hence this file may be very large.
It is recommended to create small flash devices which can be used to
represent a little portion of an otherwise very large device.
.TP
\f[V]\f[R]
uMPS3 caps the maximum block size for flash devices at 2\[ha]24.
This translates to a maximum device size of 64GB.
.TP
\f[V]\f[R]
As with real flash devices, read operations are faster than write
operations.
The read speed for uMPS3 flash devices is fixed at 75% of the device
write time in microseconds.
.TP
\f[V]\f[R]
The default values for all these parameters are shown when entering the
\f[V]umps3-mkdev\f[R] alone without any parameters.
.SH OPTIONS
.TP
\f[V]-d\f[R]
instructs the utility to build a disk file image.
.TP
\f[V]-f\f[R]
instructs the utility to build a flash device file image.
.SH FILES
.TP
\f[V]DISKFILE\f[R]
is the name of the disk file image to be created.
.TP
\f[V]FLASHFILE\f[R]
is the name of the flash device file image to be created.
.TP
\f[V]FILE\f[R]
is the name of the file to be preloaded onto the device beginning with
block 0.
If one wishes to create an empty flash device but still specify some of
the additional parameters, use \f[V]/dev/null\f[R] as the \f[I]FILE\f[R]
argument.
To load a flash device with a collection of files, it is recommended to
initially create a single \f[V].tar\f[R] file from the collection and
then use this single \f[V].tar\f[R] file for this parameter.
We recommend the \f[V].tar\f[R] file format due to its simple structure.
.SH DISKOPTIONS
.PP
[\f[I]CYL\f[R] [\f[I]HEAD\f[R] [\f[I]SECT\f[R] [\f[I]RPM\f[R]
[\f[I]SEEKT\f[R] [\f[I]DATAS\f[R]]]]]]]
.TP
\f[V]CYL\f[R]:
Number of cylinders: [1..65535], default = 32
.TP
\f[V]HEAD\f[R]:
Number of heads/surfaces: [1..255], default = 2
.TP
\f[V]SECT\f[R]:
Number of 4KB sectors/tracks: [1..255], default = 8
.TP
\f[V]RPM\f[R]:
Disk rotations per minute: [360..10800], default = 3600
.TP
\f[V]SEEKT\f[R]:
Average cylinder to cylinder seek time in microseconds: [1..10000],
default = 100
.TP
\f[V]DATAS\f[R]:
Sector data occupation %: [10%..90%], default = 80%
.SH FLASHOPTIONS
.PP
[\f[I]BLOCKS\f[R] [\f[I]WT\f[R]]]
.TP
\f[V]BLOCKS\f[R]:
Number of blocks: [1..0xFFFFFF], default = 512
.TP
\f[V]WT\f[R]:
Average write time in microseconds: [1..10000], default = 1000
.SH AUTHOR
.PP
Mauro Morsiani
.PD 0
.P
.PD
Mattia Biondi \f[I]mattiabiondi1\[at]gmail.com\f[R]
.PD 0
.P
.PD
Contributors can be listed on GitHub.
.SH BUGS
.PP
Report issues on GitHub:
\f[I]https://github.com/virtualsquare/umps3\f[R]
.SH SEE ALSO
.PP
\f[V]umps3\f[R](1), \f[V]umps3-elf2umps\f[R](1),
\f[V]umps3-objdump\f[R](1)
.PP
Full documentation at: \f[I]https://github.com/virtualsquare/umps3\f[R]
.PD 0
.P
.PD
Project wiki: \f[I]https://wiki.virtualsquare.org/#!umps/umps.md\f[R]
.SH COPYRIGHT
.PP
2004, Mauro Morsiani
.PD 0
.P
.PD
2020, Mattia Biondi \f[I]mattiabiondi1\[at]gmail.com\f[R]