xref: /freebsd/share/man/man4/mx25l.4 (revision 8ccc0d235c226d84112561d453c49904398d085c) 
1.\"
2.\" SPDX-License-Identifier: BSD-2-Clause
3.\"
4.\" Copyright (c) 2019 Ian Lepore <ian@freebsd.org>
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\"
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
27.Dd November 11, 2025
28.Dt MX25L 4
29.Os
30.Sh NAME
31.Nm mx25l
32.Nd SpiFlash compatible non-volatile storage devices driver
33.Sh SYNOPSIS
34.Cd device mx25l
35.Pp
36In
37.Xr loader.conf 5 :
38.Cd mx25l_load="YES"
39.Sh DESCRIPTION
40The
41.Nm
42driver provides support for the family of non-volatile storage
43devices known collectively as SpiFlash(tm).
44SpiFlash chips typically have part numbers beginning with EN25,
45IS25, MX25, S25, SST25, or W25.
46.Pp
47The
48.Nm
49driver uses opcode 0x9f to read the manufacturer and device ID
50data to determine whether the device is supported.
51The device ID is looked up using a table of data within the driver
52which describes the attributes of each supported device,
53such as block size, sector size, and device capacity.
54When a supported device is found, the
55.Nm
56driver creates a disk device and makes it accessible at
57.Pa /dev/flash/spi? .
58The new disk device is then tasted by the available
59.Xr geom 4
60modules as with any disk device.
61.Sh HARDWARE
62The
63.Nm
64driver supports the following spi flash memory devices:
65.Pp
66.Bl -bullet -compact
67.It
68AT25DF641
69.It
70EN25F32
71.It
72EN25P32
73.It
74EN25P64
75.It
76EN25Q32
77.It
78EN25Q64
79.It
80GD25Q64
81.It
82M25P32
83.It
84M25P64
85.It
86MX25L1606E
87.It
88MX25LL128
89.It
90MX25LL256
91.It
92MX25LL32
93.It
94MX25LL64
95.It
96N25Q64
97.It
98S25FL032
99.It
100S25FL064
101.It
102S25FL128
103.It
104S25FL256S
105.It
106SST25VF010A
107.It
108SST25VF032B
109.It
110W25Q128
111.It
112W25Q256
113.It
114W25Q32
115.It
116W25Q64
117.It
118W25Q64BV
119.It
120W25X32
121.It
122W25X64
123.El
124.Sh FDT CONFIGURATION
125On an
126.Xr fdt 4
127based system, the
128.Nm
129device is defined as a slave device subnode
130of the SPI bus controller node.
131All properties documented in the
132.Va spibus.txt
133bindings document can be used with the
134.Nm
135device.
136The most commonly-used ones are documented below.
137.Pp
138The following properties are required in the
139.Nm
140device subnode:
141.Bl -tag -width indent
142.It Va compatible
143Must be the string "jedec,spi-nor".
144.It Va reg
145Chip select address of device.
146.It Va spi-max-frequency
147The maximum bus frequency to use when communicating with this slave device.
148Actual bus speed may be lower, depending on the capabilities of the SPI
149bus controller hardware.
150.El
151.Pp
152The following properties are optional for the
153.Nm
154device subnode:
155.Bl -tag -width indent
156.It Va spi-cpha
157Empty property indicating the slave device requires shifted clock
158phase (CPHA) mode.
159.It Va spi-cpol
160Empty property indicating the slave device requires inverse clock
161polarity (CPOL) mode.
162.It Va spi-cs-high
163Empty property indicating the slave device requires chip select active high.
164.El
165.Sh HINTS CONFIGURATION
166On a
167.Xr device.hints 5
168based system, such as
169.Li MIPS ,
170these values are configurable for
171.Nm :
172.Bl -tag -width indent
173.It Va hint.mx25l.%d.at
174The spibus the
175.Nm
176instance is attached to.
177.It Va hint.mx25l.%d.clock
178The maximum bus frequency to use when communicating with this device.
179Actual bus speed may be lower, depending on the capabilities of the SPI
180bus controller hardware.
181.It Va hint.mx25l.%d.cs
182The chip-select number to assert when performing I/O for this device.
183Set the high bit (1 << 31) to invert the logic level of the chip select line.
184.It Va hint.mx25l.%d.mode
185The SPI mode (0-3) to use when communicating with this device.
186.El
187.Sh FILES
188.Bl -tag -width /dev/flash/spi?
189.It Pa /dev/flash/spi?
190Provides read/write access to the storage device.
191.El
192.Sh SEE ALSO
193.Xr fdt 4 ,
194.Xr geom 4
195.Sh HISTORY
196The
197.Nm
198driver first appeared in
199.Fx 8.0 .
200