share/man/man4/man4.prep/nvram.4

   1 .\" $NetBSD: nvram.4,v 1.4 2009/05/27 19:24:00 snj Exp $
   2 .\"
   3 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Tim Rightnour
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd March 1, 2007
  31 .Dt NVRAM 4 prep
  32 .Os
  33 .Sh NAME
  34 .Nm nvram
  35 .Nd PReP nvram interface
  36 .Sh SYNOPSIS
  37 .In machine/nvram.h
  38 .Sh DESCRIPTION
  39 The file
  40 .Nm /dev/nvram
  41 is an interface to the PReP NVRAM, including the Global Environment Area.
  42 This interface is highly stylized;
  43 ioctls are used for all operations.
  44 These ioctls refer to individual variables in the
  45 Global Environment Area and their values.
  46 .Pp
  47 The calls that take and/or return a variable
  48 use a pointer to an
  49 .Li int
  50 variable for this purpose;
  51 others use a pointer to an
  52 .Li struct pnviocdesc
  53 descriptor,
  54 which contains a variable and two counted strings.
  55 The first string comprises the fields
  56 .Li pnv_namelen
  57 (an
  58 .Li int )
  59 and
  60 .Li pnv_name
  61 (a
  62 .Li "char *" ) ,
  63 giving the name of a field.
  64 The second string comprises the fields
  65 .Li pnv_buflen
  66 and
  67 .Li pnv_buf ,
  68 used analogously.
  69 These two counted strings work in a
  70 .Dq value-result
  71 fashion.
  72 At entry to the ioctl,
  73 the counts are expected to reflect the buffer size;
  74 on return,
  75 the counts are updated to reflect the buffer contents.
  76 .Pp
  77 The following ioctls are supported:
  78 .Bl -tag -width PNVIOCGETNEXTNAME
  79 .It PNVIOCGETNEXTNAME
  80 Takes a variable name and returns the name of the following variable.
  81 If a
  82 .Dv NULL
  83 is passed as the variable name, the first variable name
  84 will be returned.
  85 If the last variable is given as an argument, the ioctl will return
  86 .Er EINVAL .
  87 .It Dv PNVIOCGET
  88 Fills in the value of the named property for the given variable.
  89 If no such property is associated with that variable,
  90 the value length is set to \-1.
  91 If the named property exists but has no value,
  92 the value length is set to 0.
  93 .It Dv PNVIOCSET
  94 Writes the given value under the given name.
  95 .It Dv PNVIOCGETNUMGE
  96 Returns the number of variables in the Global Environment Area.
  97 .El
  98 .Sh FILES
  99 .Pa /dev/nvram
 100 .Sh ERRORS
 101 The following may result in rejection of an operation:
 102 .Bl -tag -width Er
 103 .It Bq Er EINVAL
 104 The given variable name does not exist; or
 105 the buffer set up to retrieve values from the nvram was not large enough
 106 to hold the result.
 107 .El
 108 .Sh SEE ALSO
 109 .Xr ioctl 2
 110 .Pp
 111 .Pa PowerPC Reference Platform Specification Version 1.1, Section 5.5
 112 .Sh BUGS
 113 Due to limitations within the
 114 .Nm
 115 itself, these functions run at elevated priority
 116 and may adversely affect system performance.
 117 .Pp
 118 .Dv PNVIOCSET
 119 is not currently supported, making the
 120 .Nm
 121 driver read-only at this time.