usr.sbin/kgzip/kgzip.8

   1 .\" Copyright (c) 1999 Global Technology Associates, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS
  17 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
  18 .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
  19 .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  20 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  21 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  22 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  23 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd July 19, 1999
  28 .Dt KGZIP 8
  29 .Os
  30 .Sh NAME
  31 .Nm kgzip
  32 .Nd compress a kernel
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl cv
  36 .Op Fl f Ar format
  37 .Op Fl l Ar loader
  38 .Op Fl o Ar output
  39 .Ar file
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 utility compresses a kernel or some other bootable binary.
  44 Operation
  45 is in two phases as follows:
  46 .Bl -enum
  47 .It
  48 A load image of the executable file is built which omits all but
  49 the
  50 .Sq text
  51 and
  52 .Sq data
  53 segments.
  54 This image is compressed using
  55 .Xr gzip 1
  56 and output as data in relocatable object format.
  57 .It
  58 The object file is linked with a special self-hosting loader, producing
  59 an executable suitable for booting with either the second- or
  60 third-level bootstraps.
  61 .El
  62 .Pp
  63 Supported object formats are 32-bit ELF and a.out ZMAGIC.
  64 .Pp
  65 If the
  66 .Ar file
  67 operand has a
  68 .Sq .o
  69 suffix, input is assumed to be for the link phase, and the first phase
  70 is omitted.
  71 .Pp
  72 The options are:
  73 .Bl -tag -width Fl
  74 .It Fl c
  75 Omit the link phase.
  76 .It Fl v
  77 Display object file information.
  78 .It Fl f Ar format
  79 Use
  80 .Ar format
  81 as the output format, where
  82 .Ar format
  83 is
  84 .Sq aout
  85 or
  86 .Sq elf .
  87 The default format is ELF.
  88 .It Fl l Ar loader
  89 Link
  90 .Ar loader
  91 as the loader.
  92 .It Fl o Ar output
  93 Name the output file
  94 .Ar output .
  95 The default is to use the input name with the suffix
  96 .Sq .o
  97 (for relocatables) or
  98 .Sq .kgz
  99 (for executables).
 100 .El
 101 .Sh NOTES
 102 Global variables equivalent to the following are defined in the output:
 103 .Bd -literal
 104 struct kgz_hdr {
 105     char        ident[4];       /* identification: "KGZ" */
 106     uint32_t    dload;          /* decoded image load address */
 107     uint32_t    dsize;          /* decoded image size */
 108     uint32_t    isize;          /* image size in memory */
 109     uint32_t    entry;          /* entry point */
 110     uint32_t    nsize;          /* encoded image size */
 111 } kgz;
 112
 113 uint8_t kgz_ndata[];            /* encoded data */
 114 .Ed
 115 .Pp
 116 The encoded data is simply
 117 .Xr gzip 1
 118 output: a header (with no optional fields); compressed data; and 32-bit
 119 CRC and size values.
 120 .Sh FILES
 121 .Bl -tag -width /usr/lib/kgzldr.o -compact
 122 .It Pa /usr/lib/kgzldr.o
 123 The default loader
 124 .El
 125 .Sh EXIT STATUS
 126 .Ex -std
 127 .Sh SEE ALSO
 128 .Xr gzip 1 ,
 129 .Xr ld 1 ,
 130 .Xr a.out 5 ,
 131 .Xr elf 5 ,
 132 .Xr boot 8 ,
 133 .Xr loader 8
 134 .Sh AUTHORS
 135 .An Robert Nordier Aq rnordier@FreeBSD.org .
 136 .Sh BUGS
 137 As symbols are lost, the usefulness of this utility for compressing
 138 kernels is limited to situations where
 139 .Xr loader 8
 140 cannot be used; otherwise the preferred method of compressing a kernel
 141 is simply to
 142 .Xr gzip 1
 143 it.