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 FDT" 37.Cd "device nvmem" 38.In sys/extres/nvmem/nvmem.h 39.Ft int 40.Fn nvmem_get_cell_len "phandle_t node" "const char *name" 41.Ft int 42.Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" 43.Ft int 44.Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 45.Ft int 46.Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" 47.Ft int 48.Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 49.Sh DESCRIPTION 50On some embedded boards, the manufacturer stored some data on a NVMEM 51(Non-Volatile Memory), this is generally stored in some eeprom or fuses. 52.Pp 53The 54.Nm 55API consist of helpers functions for consumer and device methods for 56providers. 57.Sh FUNCTIONS 58.Bl -tag -width indent 59.It Fn nvmem_get_cell_len "phandle_t node" "const char *name" 60Get the size of the cell base on the reg property on the node. 61Return the size or ENOENT if the cell name wasn't found 62.It Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" 63Get the cell content based on the name. 64Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 65EINVAL if the size isn't correct. 66.It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 67Get the cell content based on the id. 68Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 69EINVAL if the size isn't correct. 70.It Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" 71Write the cell content based on the name. 72Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 73EINVAL if the size isn't correct. 74.It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" 75Write the cell content based on the id. 76Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, 77EINVAL if the size isn't correct. 78.El 79.Sh DEVICE METHODS 80.Bl -tag -width indent 81.It Fn nvmem_read "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" 82Provider device method to read a cell content. 83.It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" 84Provider device method to write a cell content. 85.El 86.Sh EXAMPLES 87Consider this DTS 88.Bd -literal 89/* Provider */ 90eeprom: eeprom@20000 { 91 board_id: id@0 { 92 reg = <0x0 0x4>; 93 }; 94}; 95/* Consumer */ 96device@30000 { 97 ... 98 99 nvmem-cells = <&board_id> 100 nvmem-cell-names = "boardid"; 101}; 102.Ed 103.Pp 104The device driver for eeprom@20000 needs to expose itself as a provider 105.Bd -literal 106#include "nvmem_if.h" 107 108int 109foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer) 110{ 111 /* Read the data */ 112} 113 114int 115foo_attach(device_t dev) 116{ 117 phandle_t node; 118 119 node = ofw_bus_get_node(dev); 120 ... 121 /* Registering the device so the consumers can find us */ 122 OF_device_register_xref(OF_xref_from_node(node), dev); 123 124 ... 125} 126 127static device_method_t foo_methods[] = { 128 ... 129 130 /* nvmem interface */ 131 DEVMETHOD(nvmem_read, foo_nvmem_read), 132 133 /* Terminate method list */ 134 DEVMETHOD_END 135}; 136.Ed 137.Pp 138The consumer device driver for device@30000 can now read the nvmem data 139.Bd -literal 140int 141bar_attach(device_t dev) 142{ 143 phandle_t node; 144 uint32_t boardid; 145 146 ... 147 node = ofw_bus_get_node(dev); 148 nvmem_read_cell_by_name(node, "boardid", (void *)&boardid, sizeof(boardid)); 149 ... 150} 151.Ed 152.Sh HISTORY 153The nvmem related function first appear in 154.Fx 12.0 . 155The nvmem interface and manual page was written by 156.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . 157