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 51On 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 54The 55.Nm 56API consist of helpers functions for consumer and device methods for 57providers. 58.Sh FUNCTIONS 59.Bl -tag -width indent 60.It Fn nvmem_get_cell_len "phandle_t node" "const char *name" 61Get the size of the cell base on the reg property on the node. 62Return 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" 64Get the cell content based on the name. 65Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 66EINVAL if the size isn't correct. 67.It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 68Get the cell content based on the id. 69Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 70EINVAL 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" 72Write the cell content based on the name. 73Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 74EINVAL if the size isn't correct. 75.It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 76Write the cell content based on the id. 77Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 78EINVAL 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" 83Provider device method to read a cell content. 84.It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" 85Provider device method to write a cell content. 86.El 87.Sh EXAMPLES 88Consider this DTS 89.Bd -literal 90/* Provider */ 91eeprom: eeprom@20000 { 92 board_id: id@0 { 93 reg = <0x0 0x4>; 94 }; 95}; 96/* Consumer */ 97device@30000 { 98 ... 99 100 nvmem-cells = <&board_id> 101 nvmem-cell-names = "boardid"; 102}; 103.Ed 104.Pp 105The device driver for eeprom@20000 needs to expose itself as a provider 106.Bd -literal 107#include "nvmem_if.h" 108 109int 110foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer) 111{ 112 /* Read the data */ 113} 114 115int 116foo_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 128static 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 139The consumer device driver for device@30000 can now read the nvmem data 140.Bd -literal 141int 142bar_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 154The nvmem related function first appear in 155.Fx 12.0 . 156The nvmem interface and manual page was written by 157.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . 158