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: src/usr.sbin/kgzip/kgzip.8,v 1.3.2.3 2001/08/16 15:56:02 ru Exp $
  26 .\" $DragonFly: src/usr.sbin/kgzip/kgzip.8,v 1.3 2006/02/17 19:40:16 swildner Exp $
  27 .\"
  28 .Dd July 19, 1999
  29 .Dt KGZIP 8
  30 .Os
  31 .Sh NAME
  32 .Nm kgzip
  33 .Nd compress a kernel
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl cv
  37 .Op Fl f Ar format
  38 .Op Fl l Ar loader
  39 .Op Fl o Ar output
  40 .Ar file
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 utility compresses a kernel or some other bootable binary.  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.  This image is compressed using
  54 .Xr gzip 1
  55 and output as data in relocatable object format.
  56 .It
  57 The object file is linked with a special self-hosting loader, producing
  58 an executable suitable for booting with either the second- or
  59 third-level bootstraps.
  60 .El
  61 .Pp
  62 Supported object formats are 32-bit ELF and a.out ZMAGIC.
  63 .Pp
  64 If the
  65 .Ar file
  66 operand has a
  67 .Sq .o
  68 suffix, input is assumed to be for the link phase, and the first phase
  69 is omitted.
  70 .Pp
  71 The options are:
  72 .Bl -tag -width Fl
  73 .It Fl c
  74 Omit the link phase.
  75 .It Fl v
  76 Display object file information.
  77 .It Fl f Ar format
  78 Use
  79 .Ar format
  80 as the output format, where
  81 .Ar format
  82 is
  83 .Sq aout
  84 or
  85 .Sq elf .
  86 The default format is ELF.
  87 .It Fl l Ar loader
  88 Link
  89 .Ar loader
  90 as the loader.
  91 .It Fl o Ar output
  92 Name the output file
  93 .Ar output .
  94 The default is to use the input name with the suffix
  95 .Sq .o
  96 (for relocatables) or
  97 .Sq .kgz
  98 (for executables).
  99 .El
 100 .Sh NOTES
 101 Global variables equivalent to the following are defined in the output:
 102 .Bd -literal
 103 struct kgz_hdr {
 104     char        ident[4];       /* identification: "KGZ" */
 105     uint32_t    dload;          /* decoded image load address */
 106     uint32_t    dsize;          /* decoded image size */
 107     uint32_t    isize;          /* image size in memory */
 108     uint32_t    entry;          /* entry point */
 109     uint32_t    nsize;          /* encoded image size */
 110 } kgz;
 111
 112 uint8_t kgz_ndata[];            /* encoded data */
 113 .Ed
 114 .Pp
 115 The encoded data is simply
 116 .Xr gzip 1
 117 output: a header (with no optional fields); compressed data; and 32-bit
 118 CRC and size values.
 119 .Sh FILES
 120 .Bl -tag -width /usr/lib/kgzldr.o -compact
 121 .It Pa /usr/lib/kgzldr.o
 122 The default loader
 123 .El
 124 .Sh DIAGNOSTICS
 125 .Ex -std
 126 .Sh SEE ALSO
 127 .Xr gzip 1 ,
 128 .Xr ld 1 ,
 129 .Xr a.out 5 ,
 130 .Xr elf 5 ,
 131 .Xr boot 8 ,
 132 .Xr loader 8
 133 .Sh AUTHORS
 134 .An Robert Nordier Aq rnordier@FreeBSD.org .
 135 .Sh BUGS
 136 As symbols are lost, the usefulness of this utility for compressing
 137 kernels is limited to situations where
 138 .Xr loader 8
 139 cannot be used; otherwise the preferred method of compressing a kernel
 140 is simply to
 141 .Xr gzip 1
 142 it.