share/man/man4/mx25l.4

   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 .\" $FreeBSD$
  26 .\"
  27 .Dd February 26, 2019
  28 .Dt MX25L 4
  29 .Os
  30 .Sh NAME
  31 .Nm mx25l
  32 .Nd driver for SpiFlash(tm) compatible non-volatile storage devices
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel,
  35 place the following line in your
  36 kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device mx25l"
  39 .Ed
  40 .Pp
  41 Alternatively, to load the driver as a
  42 module at boot time, place the following line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 mx25l_load="YES"
  46 .Ed
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 driver provides support for the family of non-volatile storage
  51 devices known collectively as SpiFlash(tm).
  52 SpiFlash chips typically have part numbers beginning with EN25,
  53 IS25, MX25, S25, SST25, or W25.
  54 .Pp
  55 The
  56 .Nm
  57 driver uses opcode 0x9f to read the manufacturer and device ID
  58 data to determine whether the device is supported.
  59 The device ID is looked up using a table of data within the driver
  60 which describes the attributes of each supported device,
  61 such as block size, sector size, and device capacity.
  62 When a supported device is found, the
  63 .Nm
  64 driver creates a disk device and makes it accessible at
  65 .Pa /dev/flash/mx25l? .
  66 The new disk device is then tasted by the available
  67 .Xr geom 4
  68 modules as with any disk device.
  69 .Sh HARDWARE
  70 The
  71 .Nm
  72 driver provides support for the following devices:
  73 .Pp
  74 .Bl -bullet -compact
  75 .It
  76 AT25DF641
  77 .It
  78 EN25F32
  79 .It
  80 EN25P32
  81 .It
  82 EN25P64
  83 .It
  84 EN25Q32
  85 .It
  86 EN25Q64
  87 .It
  88 GD25Q64
  89 .It
  90 M25P32
  91 .It
  92 M25P64
  93 .It
  94 MX25L1606E
  95 .It
  96 MX25LL128
  97 .It
  98 MX25LL256
  99 .It
 100 MX25LL32
 101 .It
 102 MX25LL64
 103 .It
 104 S25FL032
 105 .It
 106 S25FL064
 107 .It
 108 S25FL128
 109 .It
 110 S25FL256S
 111 .It
 112 SST25VF010A
 113 .It
 114 SST25VF032B
 115 .It
 116 W25Q128
 117 .It
 118 W25Q256
 119 .It
 120 W25Q32
 121 .It
 122 W25Q64
 123 .It
 124 W25Q64BV
 125 .It
 126 W25X32
 127 .It
 128 W25X64
 129 .El
 130 .Sh FDT CONFIGURATION
 131 On an
 132 .Xr fdt 4
 133 based system, the
 134 .Nm
 135 device is defined as a slave device subnode
 136 of the SPI bus controller node.
 137 All properties documented in the
 138 .Va spibus.txt
 139 bindings document can be used with the
 140 .Nm
 141 device.
 142 The most commonly-used ones are documented below.
 143 .Pp
 144 The following properties are required in the
 145 .Nm
 146 device subnode:
 147 .Bl -tag -width indent
 148 .It Va compatible
 149 Must be the string "jedec,spi-nor".
 150 .It Va reg
 151 Chip select address of device.
 152 .It Va spi-max-frequency
 153 The maximum bus frequency to use when communicating with this slave device.
 154 Actual bus speed may be lower, depending on the capabilities of the SPI
 155 bus controller hardware.
 156 .El
 157 .Pp
 158 The following properties are optional for the
 159 .Nm
 160 device subnode:
 161 .Bl -tag -width indent
 162 .It Va spi-cpha
 163 Empty property indicating the slave device requires shifted clock
 164 phase (CPHA) mode.
 165 .It Va spi-cpol
 166 Empty property indicating the slave device requires inverse clock
 167 polarity (CPOL) mode.
 168 .It Va spi-cs-high
 169 Empty property indicating the slave device requires chip select active high.
 170 .El
 171 .Sh HINTS CONFIGURATION
 172 On a
 173 .Xr device.hints 5
 174 based system, such as
 175 .Li MIPS ,
 176 these values are configurable for
 177 .Nm :
 178 .Bl -tag -width indent
 179 .It Va hint.mx25l.%d.at
 180 The spibus the
 181 .Nm
 182 instance is attached to.
 183 .It Va hint.mx25l.%d.clock
 184 The maximum bus frequency to use when communicating with this device.
 185 Actual bus speed may be lower, depending on the capabilities of the SPI
 186 bus controller hardware.
 187 .It Va hint.mx25l.%d.cs
 188 The chip-select number to assert when performing I/O for this device.
 189 Set the high bit (1 << 31) to invert the logic level of the chip select line.
 190 .It Va hint.mx25l.%d.mode
 191 The SPI mode (0-3) to use when communicating with this device.
 192 .El
 193 .Sh FILES
 194 .Bl -tag -width /dev/flash/mx25l?
 195 .It Pa /dev/flash/mx25l?
 196 Provides read/write access to the storage device.
 197 .It Pa /dev/flash/spi?
 198 An alias for the
 199 .Pa /dev/mx25l?
 200 device, for backwards compatibility with older versions of the driver.
 201 .El
 202 .Sh SEE ALSO
 203 .Xr fdt 4 ,
 204 .Xr geom 4
 205 .Sh HISTORY
 206 The
 207 .Nm
 208 driver first appeared in
 209 .Fx 8.0 .