1.\" 2.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org> 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.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.Dd March 2, 2019 26.Dt AT45D 4 27.Os 28.Sh NAME 29.Nm at45d 30.Nd driver for DataFlash(tm) non-volatile storage devices 31.Sh SYNOPSIS 32To compile this driver into the kernel, 33place the following line in your 34kernel configuration file: 35.Bd -ragged -offset indent 36.Cd "device at45d" 37.Ed 38.Pp 39Alternatively, to load the driver as a 40module at boot time, place the following line in 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43at45d_load="YES" 44.Ed 45.Sh DESCRIPTION 46The 47.Nm 48driver provides support for the family of non-volatile storage 49devices known collectively as DataFlash(tm). 50DataFlash chips typically have part numbers beginning with AT45DB. 51The 52.Nm 53driver supports only the SPI bus versions of each AT45DB device, 54indicated by the last digit of the part number being 1 or 2. 55.Pp 56The 57.Nm 58driver uses opcode 0x9f to read the manufacturer and device ID 59data to determine whether the device is supported. 60The device ID is looked up using a table of data within the driver 61which describes the attributes of each supported device, 62such as block size, sector size, and device capacity. 63When a supported device is found, the 64.Nm 65driver creates a disk device and makes it accessible at 66.Pa /dev/flash/at45d? . 67The new disk device is then tasted by the available 68.Xr geom 4 69modules as with any disk device. 70.Sh HARDWARE 71The 72.Nm 73driver provides support for the following devices: 74.Pp 75.Bl -bullet -compact 76.It 77AT45DB011B 78.It 79AT45DB021B 80.It 81AT45DB041x 82.It 83AT45DB081B 84.It 85AT45DB161x 86.It 87AT45DB321x 88.It 89AT45DB321x 90.It 91AT45DB641E 92.It 93AT45DB642x 94.El 95.Sh FDT CONFIGURATION 96On an 97.Xr fdt 4 98based system, the 99.Nm 100device is defined as a slave device subnode 101of the SPI bus controller node. 102All properties documented in the 103.Va spibus.txt 104bindings document can be used with the 105.Nm 106device. 107The most commonly-used ones are documented below. 108.Pp 109The following properties are required in the 110.Nm 111device subnode: 112.Bl -tag -width indent 113.It Va compatible 114Must be the string "atmel,at45". 115.It Va reg 116Chip select address of device. 117.It Va spi-max-frequency 118The maximum bus frequency to use when communicating with this slave device. 119Actual bus speed may be lower, depending on the capabilities of the SPI 120bus controller hardware. 121.El 122.Pp 123The following properties are optional for the 124.Nm 125device subnode: 126.Bl -tag -width indent 127.It Va freebsd,sectorsize 128The sector size of the disk created for this storage device. 129It must be a multiple of the device's page size. 130The default is the device page size. 131.It Va spi-cpha 132Empty property indicating the slave device requires shifted clock 133phase (CPHA) mode. 134.It Va spi-cpol 135Empty property indicating the slave device requires inverse clock 136polarity (CPOL) mode. 137.It Va spi-cs-high 138Empty property indicating the slave device requires chip select active high. 139.El 140.Sh HINTS CONFIGURATION 141On a 142.Xr device.hints 5 143based system, such as 144.Li MIPS , 145these values are configurable for 146.Nm : 147.Bl -tag -width indent 148.It Va hint.at45d.%d.at 149The spibus the 150.Nm 151instance is attached to. 152.It Va hint.at45d.%d.clock 153The maximum bus frequency to use when communicating with this device. 154Actual bus speed may be lower, depending on the capabilities of the SPI 155bus controller hardware. 156.It Va hint.at45d.%d.cs 157The chip-select number to assert when performing I/O for this device. 158Set the high bit (1 << 31) to invert the logic level of the chip select line. 159.It Va hint.at45d.%d.mode 160The SPI mode (0-3) to use when communicating with this device. 161.It Va hint.at45d.%d.sectorsize 162The sector size of the disk created for this storage device. 163It must be a multiple of the device's page size. 164The default is the device page size. 165.El 166.Sh FILES 167.Bl -tag -width /dev/flash/at45d? 168.It Pa /dev/flash/at45d? 169Provides read/write access to the storage device. 170.It Pa /dev/flash/spi? 171An alias for the 172.Pa /dev/at45d? 173device, for backwards compatibility with older versions of the driver. 174.El 175.Sh SEE ALSO 176.Xr fdt 4 , 177.Xr geom 4 178.Sh HISTORY 179The 180.Nm 181driver first appeared in 182.Fx 6.0 . 183