share/man/man9/nvmem.9

   1 .\" Copyright (c) 2018 Emmanuel Vadot <manu@freebsd.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  13 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  14 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  15 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  16 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  17 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  18 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  19 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  20 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  21 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22 .\"
  23 .\" $FreeBSD$
  24 .\"
  25 .Dd July 24, 2018
  26 .Dt nvmem 9
  27 .Os
  28 .Sh NAME
  29 .Nm nvmem
  30 .Nm nvmem_get_cell_len ,
  31 .Nm nvmem_read_cell_by_name ,
  32 .Nm nvmem_read_cell_by_idx ,
  33 .Nm nvmem_write_cell_by_name ,
  34 .Nm nvmem_write_cell_by_idx ,
  35 .Sh SYNOPSIS
  36 .Cd "options EXT_RESOURCES"
  37 .Cd "options FDT"
  38 .Cd "device nvmem"
  39 .In sys/extres/nvmem/nvmem.h
  40 .Ft int
  41 .Fn nvmem_get_cell_len "phandle_t node" "const char *name"
  42 .Ft int
  43 .Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen"
  44 .Ft int
  45 .Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen"
  46 .Ft int
  47 .Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen"
  48 .Ft int
  49 .Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen"
  50 .Sh DESCRIPTION
  51 On some embedded boards, the manufacturer stored some data on a NVMEM
  52 (Non-Volatile Memory), this is generally stored in some eeprom or fuses.
  53 .Pp
  54 The
  55 .Nm
  56 API consist of helpers functions for consumer and device methods for
  57 providers.
  58 .Sh FUNCTIONS
  59 .Bl -tag -width indent
  60 .It Fn nvmem_get_cell_len  "phandle_t node" "const char *name"
  61 Get the size of the cell base on the reg property on the node.
  62 Return the size or ENOENT if the cell name wasn't found
  63 .It Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen"
  64 Get the cell content based on the name.
  65 Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found,
  66 EINVAL if the size isn't correct.
  67 .It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen"
  68 Get the cell content based on the id.
  69 Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found,
  70 EINVAL if the size isn't correct.
  71 .It Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen"
  72 Write the cell content based on the name.
  73 Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found,
  74 EINVAL if the size isn't correct.
  75 .It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen"
  76 Write the cell content based on the id.
  77 Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found,
  78 EINVAL if the size isn't correct.
  79 .El
  80 .Sh DEVICE METHODS
  81 .Bl -tag -width indent
  82 .It Fn nvmem_read "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer"
  83 Provider device method to read a cell content.
  84 .It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer"
  85 Provider device method to write a cell content.
  86 .El
  87 .Sh EXAMPLES
  88 Consider this DTS
  89 .Bd -literal
  90 /* Provider */
  91 eeprom: eeprom@20000 {
  92         board_id: id@0 {
  93                 reg = <0x0 0x4>;
  94         };
  95 };
  96 /* Consumer */
  97 device@30000 {
  98         ...
  99
 100         nvmem-cells = <&board_id>
 101         nvmem-cell-names = "boardid";
 102 };
 103 .Ed
 104 .Pp
 105 The device driver for eeprom@20000 needs to expose itself as a provider
 106 .Bd -literal
 107 #include "nvmem_if.h"
 108
 109 int
 110 foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer)
 111 {
 112         /* Read the data */
 113 }
 114
 115 int
 116 foo_attach(device_t dev)
 117 {
 118         phandle_t node;
 119
 120         node = ofw_bus_get_node(dev);
 121         ...
 122         /* Registering the device so the consumers can find us */
 123         OF_device_register_xref(OF_xref_from_node(node), dev);
 124
 125         ...
 126 }
 127
 128 static device_method_t foo_methods[] = {
 129         ...
 130
 131         /* nvmem interface */
 132         DEVMETHOD(nvmem_read, foo_nvmem_read),
 133
 134         /* Terminate method list */
 135         DEVMETHOD_END
 136 };
 137 .Ed
 138 .Pp
 139 The consumer device driver for device@30000 can now read the nvmem data
 140 .Bd -literal
 141 int
 142 bar_attach(device_t dev)
 143 {
 144         phandle_t node;
 145         uint32_t boardid;
 146
 147         ...
 148         node = ofw_bus_get_node(dev);
 149         nvmem_read_cell_by_name(node, "boardid", (void *)&boardid, sizeof(boardid));
 150         ...
 151 }
 152 .Ed
 153 .Sh HISTORY
 154 The nvmem related function first appear in
 155 .Fx 12.0 .
 156 The nvmem interface and manual page was written by
 157 .An Emmanuel Vadot Aq Mt manu@FreeBSD.org .