Contiki-NG
ext-flash.c
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2014, Texas Instruments Incorporated - http://www.ti.com/
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
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  * 3. Neither the name of the copyright holder nor the names of its
14  * contributors may be used to endorse or promote products derived
15  * from this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
18  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
19  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
20  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
21  * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
22  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
28  * OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 /*---------------------------------------------------------------------------*/
31 /**
32  * \addtogroup ext-flash
33  * @{
34  *
35  * \file
36  * Implementation of a generic external SPI flash driver
37  */
38 /*---------------------------------------------------------------------------*/
39 #include "contiki.h"
40 #include "ext-flash.h"
41 #include "dev/spi.h"
42 #include "gpio-hal.h"
43 #include "sys/log.h"
44 
45 #include <stdint.h>
46 #include <stdbool.h>
47 /*---------------------------------------------------------------------------*/
48 #ifndef EXT_FLASH_SPI_CONTROLLER
49 
50 #define EXT_FLASH_SPI_CONTROLLER 0xFF /* No controller */
51 
52 #define EXT_FLASH_SPI_PIN_SCK GPIO_HAL_PIN_UNKNOWN
53 #define EXT_FLASH_SPI_PIN_MOSI GPIO_HAL_PIN_UNKNOWN
54 #define EXT_FLASH_SPI_PIN_MISO GPIO_HAL_PIN_UNKNOWN
55 #define EXT_FLASH_SPI_PIN_CS GPIO_HAL_PIN_UNKNOWN
56 
57 #define EXT_FLASH_DEVICE_ID 0xFF
58 #define EXT_FLASH_MID 0xFF
59 
60 #define EXT_FLASH_PROGRAM_PAGE_SIZE 256
61 #define EXT_FLASH_ERASE_SECTOR_SIZE 4096
62 
63 #endif /* EXT_FLASH_SPI_CONTROLLER */
64 /*---------------------------------------------------------------------------*/
65 /* Log configuration */
66 #define LOG_MODULE "ext-flash"
67 #define LOG_LEVEL LOG_LEVEL_NONE
68 /*---------------------------------------------------------------------------*/
69 /* Instruction codes */
70 
71 #define BLS_CODE_PROGRAM 0x02 /**< Page Program */
72 #define BLS_CODE_READ 0x03 /**< Read Data */
73 #define BLS_CODE_READ_STATUS 0x05 /**< Read Status Register */
74 #define BLS_CODE_WRITE_ENABLE 0x06 /**< Write Enable */
75 #define BLS_CODE_SECTOR_ERASE 0x20 /**< Sector Erase */
76 #define BLS_CODE_MDID 0x90 /**< Manufacturer Device ID */
77 
78 #define BLS_CODE_PD 0xB9 /**< Power down */
79 #define BLS_CODE_RPD 0xAB /**< Release Power-Down */
80 /*---------------------------------------------------------------------------*/
81 /* Erase instructions */
82 
83 #define BLS_CODE_ERASE_4K 0x20 /**< Sector Erase */
84 #define BLS_CODE_ERASE_32K 0x52
85 #define BLS_CODE_ERASE_64K 0xD8
86 #define BLS_CODE_ERASE_ALL 0xC7 /**< Mass Erase */
87 /*---------------------------------------------------------------------------*/
88 /* Bitmasks of the status register */
89 
90 #define BLS_STATUS_SRWD_BM 0x80
91 #define BLS_STATUS_BP_BM 0x0C
92 #define BLS_STATUS_WEL_BM 0x02
93 #define BLS_STATUS_WIP_BM 0x01
94 
95 #define BLS_STATUS_BIT_BUSY 0x01 /**< Busy bit of the status register */
96 /*---------------------------------------------------------------------------*/
97 #define VERIFY_PART_LOCKED -2
98 #define VERIFY_PART_ERROR -1
99 #define VERIFY_PART_POWERED_DOWN 0
100 #define VERIFY_PART_OK 1
101 /*---------------------------------------------------------------------------*/
102 static const spi_device_t flash_spi_configuration_default = {
103 #if GPIO_HAL_PORT_PIN_NUMBERING
104  .port_spi_sck = EXT_FLASH_SPI_PORT_SCK,
105  .port_spi_miso = EXT_FLASH_SPI_PORT_MISO,
106  .port_spi_mosi = EXT_FLASH_SPI_PORT_MOSI,
107  .port_spi_cs = EXT_FLASH_SPI_PORT_CS,
108 #endif
109  .spi_controller = EXT_FLASH_SPI_CONTROLLER,
110  .pin_spi_sck = EXT_FLASH_SPI_PIN_SCK,
111  .pin_spi_miso = EXT_FLASH_SPI_PIN_MISO,
112  .pin_spi_mosi = EXT_FLASH_SPI_PIN_MOSI,
113  .pin_spi_cs = EXT_FLASH_SPI_PIN_CS,
114  .spi_bit_rate = 4000000,
115  .spi_pha = 0,
116  .spi_pol = 0
117 };
118 /*---------------------------------------------------------------------------*/
119 /**
120  * Get spi configuration, return default configuration if NULL
121  */
122 static const spi_device_t *
124 {
125  if(conf == NULL) {
126  return &flash_spi_configuration_default;
127  }
128  return conf;
129 }
130 /*---------------------------------------------------------------------------*/
131 /**
132  * Clear external flash CSN line
133  */
134 static bool
135 select_on_bus(const spi_device_t *flash_spi_configuration)
136 {
137  if(spi_select(flash_spi_configuration) == SPI_DEV_STATUS_OK) {
138  return true;
139  }
140  return false;
141 }
142 /*---------------------------------------------------------------------------*/
143 /**
144  * Set external flash CSN line
145  */
146 static void
147 deselect(const spi_device_t *flash_spi_configuration)
148 {
149  spi_deselect(flash_spi_configuration);
150 }
151 /*---------------------------------------------------------------------------*/
152 /**
153  * \brief Wait till previous erase/program operation completes.
154  * \return True when successful.
155  */
156 static bool
157 wait_ready(const spi_device_t *flash_spi_configuration)
158 {
159  bool ret;
160  const uint8_t wbuf[1] = { BLS_CODE_READ_STATUS };
161 
162  if(select_on_bus(flash_spi_configuration) == false) {
163  return false;
164  }
165 
166  ret = spi_write(flash_spi_configuration, wbuf, sizeof(wbuf));
167 
168  if(ret != SPI_DEV_STATUS_OK) {
169  deselect(flash_spi_configuration);
170  return false;
171  }
172 
173  for(;;) {
174  uint8_t buf;
175  /* Note that this temporary implementation is not
176  * energy efficient.
177  * Thread could have yielded while waiting for flash
178  * erase/program to complete.
179  */
180  ret = spi_read(flash_spi_configuration, &buf, sizeof(buf));
181 
182  if(ret != SPI_DEV_STATUS_OK) {
183  /* Error */
184  deselect(flash_spi_configuration);
185  return false;
186  }
187 
188  if(!(buf & BLS_STATUS_BIT_BUSY)) {
189  /* Now ready */
190  break;
191  }
192  }
193  deselect(flash_spi_configuration);
194  return true;
195 }
196 /*---------------------------------------------------------------------------*/
197 /**
198  * \brief Verify the flash part.
199  * \retval VERIFY_PART_OK The part was identified successfully
200  * \retval VERIFY_PART_ERROR There was an error communicating with the part
201  * \retval VERIFY_PART_POWERED_DOWN Communication was successful, but the part
202  * was powered down
203  */
204 static uint8_t
205 verify_part(const spi_device_t *flash_spi_configuration)
206 {
207  const uint8_t wbuf[] = { BLS_CODE_MDID, 0xFF, 0xFF, 0x00 };
208  uint8_t rbuf[2] = { 0, 0 };
209  bool ret;
210 
211  if(select_on_bus(flash_spi_configuration) == false) {
212  return VERIFY_PART_LOCKED;
213  }
214 
215  if(spi_write(flash_spi_configuration, wbuf, sizeof(wbuf)) != SPI_DEV_STATUS_OK) {
216  deselect(flash_spi_configuration);
217  return VERIFY_PART_ERROR;
218  }
219 
220  ret = spi_read(flash_spi_configuration, rbuf, sizeof(rbuf));
221  deselect(flash_spi_configuration);
222  if(ret != SPI_DEV_STATUS_OK) {
223  return VERIFY_PART_ERROR;
224  }
225 
226  LOG_DBG("Verify: %02x %02x\n", rbuf[0], rbuf[1]);
227 
228  if(rbuf[0] != EXT_FLASH_MID || rbuf[1] != EXT_FLASH_DEVICE_ID) {
229  return VERIFY_PART_POWERED_DOWN;
230  }
231  return VERIFY_PART_OK;
232 }
233 /*---------------------------------------------------------------------------*/
234 /**
235  * \brief Put the device in power save mode. No access to data; only
236  * the status register is accessible.
237  */
238 static bool
239 power_down(const spi_device_t *flash_spi_configuration)
240 {
241  uint8_t cmd;
242  uint8_t i;
243 
244  /* First, wait for the device to be ready */
245  if(wait_ready(flash_spi_configuration) == false) {
246  /* Entering here will leave the device in standby instead of powerdown */
247  return false;
248  }
249 
250  cmd = BLS_CODE_PD;
251  if(select_on_bus(flash_spi_configuration) == false) {
252  return false;
253  }
254 
255  if(spi_write_byte(flash_spi_configuration, cmd) != SPI_DEV_STATUS_OK) {
256  deselect(flash_spi_configuration);
257  return false;
258  }
259  deselect(flash_spi_configuration);
260 
261  i = 0;
262  while(i < 10) {
263  if(verify_part(flash_spi_configuration) == VERIFY_PART_POWERED_DOWN) {
264  /* Device is powered down */
265  return true;
266  }
267  i++;
268  }
269 
270  /* Should not be required */
271  deselect(flash_spi_configuration);
272  return false;
273 }
274 /*---------------------------------------------------------------------------*/
275 /**
276  * \brief Take device out of power save mode and prepare it for normal operation
277  * \return True if the command was written successfully
278  */
279 static bool
280 power_standby(const spi_device_t *flash_spi_configuration)
281 {
282  uint8_t cmd;
283  bool success;
284 
285  cmd = BLS_CODE_RPD;
286  if(select_on_bus(flash_spi_configuration) == false) {
287  return false;
288  }
289 
290  success = (spi_write(flash_spi_configuration, &cmd, sizeof(cmd)) == SPI_DEV_STATUS_OK);
291 
292  if(success) {
293  success = wait_ready(flash_spi_configuration) == true ? true : false;
294  }
295 
296  deselect(flash_spi_configuration);
297 
298  return success;
299 }
300 /*---------------------------------------------------------------------------*/
301 /**
302  * \brief Enable write.
303  * \return True when successful.
304  */
305 static bool
306 write_enable(const spi_device_t *flash_spi_configuration)
307 {
308  bool ret;
309  const uint8_t wbuf[] = { BLS_CODE_WRITE_ENABLE };
310 
311  if(select_on_bus(flash_spi_configuration) == false) {
312  return false;
313  }
314 
315  ret = (spi_write(flash_spi_configuration, wbuf, sizeof(wbuf)) == SPI_DEV_STATUS_OK);
316  deselect(flash_spi_configuration);
317 
318  if(ret == false) {
319  return false;
320  }
321  return true;
322 }
323 /*---------------------------------------------------------------------------*/
324 bool
326 {
327  const spi_device_t *flash_spi_configuration;
328 
329  flash_spi_configuration = get_spi_conf(conf);
330 
331  /* Check if platform has ext-flash */
332  if(flash_spi_configuration->pin_spi_sck == GPIO_HAL_PIN_UNKNOWN) {
333  return false;
334  }
335 
336  if(spi_acquire(flash_spi_configuration) != SPI_DEV_STATUS_OK) {
337  return false;
338  }
339  /* Default output to clear chip select */
340  deselect(flash_spi_configuration);
341 
342  /* Put the part is standby mode */
343  power_standby(flash_spi_configuration);
344 
345  if(verify_part(flash_spi_configuration) == VERIFY_PART_OK) {
346  return true;
347  }
348 
349  /* Failed to verify */
350  spi_release(flash_spi_configuration);
351  return false;
352 }
353 /*---------------------------------------------------------------------------*/
354 bool
356 {
357  bool ret;
358  const spi_device_t *flash_spi_configuration;
359 
360  flash_spi_configuration = get_spi_conf(conf);
361 
362  /* Put the part in low power mode */
363  ret = power_down(flash_spi_configuration);
364 
365  /* SPI is released no matter if power_down() succeeds or fails */
366  if(spi_release(flash_spi_configuration) != SPI_DEV_STATUS_OK) {
367  return false;
368  }
369 
370  return ret;
371 }
372 /*---------------------------------------------------------------------------*/
373 bool
374 ext_flash_read(const spi_device_t *conf, uint32_t offset, uint32_t length, uint8_t *buf)
375 {
376  uint8_t wbuf[4];
377  bool ret;
378 
379  const spi_device_t *flash_spi_configuration;
380 
381  flash_spi_configuration = get_spi_conf(conf);
382 
383  /* Wait till previous erase/program operation completes */
384  if(wait_ready(flash_spi_configuration) == false) {
385  return false;
386  }
387 
388  /*
389  * SPI is driven with very low frequency (1MHz < 33MHz fR spec)
390  * in this implementation, hence it is not necessary to use fast read.
391  */
392  wbuf[0] = BLS_CODE_READ;
393  wbuf[1] = (offset >> 16) & 0xff;
394  wbuf[2] = (offset >> 8) & 0xff;
395  wbuf[3] = offset & 0xff;
396 
397  if(select_on_bus(flash_spi_configuration) == false) {
398  return false;
399  }
400 
401  if(spi_write(flash_spi_configuration, wbuf, sizeof(wbuf)) != SPI_DEV_STATUS_OK) {
402  /* failure */
403  deselect(flash_spi_configuration);
404  return false;
405  }
406 
407  ret = (spi_read(flash_spi_configuration, buf, length) == SPI_DEV_STATUS_OK);
408 
409  deselect(flash_spi_configuration);
410 
411  return ret;
412 }
413 /*---------------------------------------------------------------------------*/
414 bool
415 ext_flash_write(const spi_device_t *conf, uint32_t offset, uint32_t length, const uint8_t *buf)
416 {
417  uint8_t wbuf[4];
418  uint32_t ilen; /* interim length per instruction */
419 
420  const spi_device_t *flash_spi_configuration;
421 
422  flash_spi_configuration = get_spi_conf(conf);
423 
424  while(length > 0) {
425  /* Wait till previous erase/program operation completes */
426  if(wait_ready(flash_spi_configuration) == false) {
427  return false;
428  }
429 
430  if(write_enable(flash_spi_configuration) == false) {
431  return false;
432  }
433 
434  ilen = EXT_FLASH_PROGRAM_PAGE_SIZE - (offset % EXT_FLASH_PROGRAM_PAGE_SIZE);
435  if(length < ilen) {
436  ilen = length;
437  }
438 
439  wbuf[0] = BLS_CODE_PROGRAM;
440  wbuf[1] = (offset >> 16) & 0xff;
441  wbuf[2] = (offset >> 8) & 0xff;
442  wbuf[3] = offset & 0xff;
443 
444  offset += ilen;
445  length -= ilen;
446 
447  /* Upto 100ns CS hold time (which is not clear
448  * whether it's application only inbetween reads)
449  * is not imposed here since above instructions
450  * should be enough to delay
451  * as much. */
452  if(select_on_bus(flash_spi_configuration) == false) {
453  return false;
454  }
455 
456  if(spi_write(flash_spi_configuration, wbuf, sizeof(wbuf)) != SPI_DEV_STATUS_OK) {
457  /* failure */
458  deselect(flash_spi_configuration);
459  return false;
460  }
461 
462  if(spi_write(flash_spi_configuration, buf, ilen) != SPI_DEV_STATUS_OK) {
463  /* failure */
464  deselect(flash_spi_configuration);
465  return false;
466  }
467  buf += ilen;
468  deselect(flash_spi_configuration);
469  }
470 
471  return true;
472 }
473 /*---------------------------------------------------------------------------*/
474 bool
475 ext_flash_erase(const spi_device_t *conf, uint32_t offset, uint32_t length)
476 {
477  /*
478  * Note that Block erase might be more efficient when the floor map
479  * is well planned for OTA, but to simplify this implementation,
480  * sector erase is used blindly.
481  */
482  uint8_t wbuf[4];
483  uint32_t i, numsectors;
484  uint32_t endoffset = offset + length - 1;
485 
486  const spi_device_t *flash_spi_configuration;
487 
488  flash_spi_configuration = get_spi_conf(conf);
489 
490  offset = (offset / EXT_FLASH_ERASE_SECTOR_SIZE) * EXT_FLASH_ERASE_SECTOR_SIZE;
491  numsectors = (endoffset - offset + EXT_FLASH_ERASE_SECTOR_SIZE - 1) / EXT_FLASH_ERASE_SECTOR_SIZE;
492 
493  wbuf[0] = BLS_CODE_SECTOR_ERASE;
494 
495  for(i = 0; i < numsectors; i++) {
496  /* Wait till previous erase/program operation completes */
497  if(wait_ready(flash_spi_configuration) == false) {
498  return false;
499  }
500 
501  if(write_enable(flash_spi_configuration) == false) {
502  return false;
503  }
504 
505  wbuf[1] = (offset >> 16) & 0xff;
506  wbuf[2] = (offset >> 8) & 0xff;
507  wbuf[3] = offset & 0xff;
508 
509  if(select_on_bus(flash_spi_configuration) == false) {
510  return false;
511  }
512 
513  if(spi_write(flash_spi_configuration, wbuf, sizeof(wbuf)) != SPI_DEV_STATUS_OK) {
514  /* failure */
515  deselect(flash_spi_configuration);
516  return false;
517  }
518  deselect(flash_spi_configuration);
519 
520  offset += EXT_FLASH_ERASE_SECTOR_SIZE;
521  }
522 
523  return true;
524 }
525 /*---------------------------------------------------------------------------*/
526 bool
528 {
529  if(ext_flash_open(conf) == false) {
530  return false;
531  }
532 
533  if(ext_flash_close(conf) == false) {
534  return false;
535  }
536 
537  LOG_INFO("Flash init successful\n");
538 
539  return true;
540 }
541 /*---------------------------------------------------------------------------*/
542 /** @} */
#define BLS_CODE_WRITE_ENABLE
Write Enable.
Definition: ext-flash.c:74
#define BLS_CODE_PROGRAM
Page Program.
Definition: ext-flash.c:71
spi_status_t spi_select(const spi_device_t *dev)
Selects the SPI peripheral.
Definition: spi.c:68
static void deselect(const spi_device_t *flash_spi_configuration)
Set external flash CSN line.
Definition: ext-flash.c:147
bool ext_flash_read(const spi_device_t *conf, uint32_t offset, uint32_t length, uint8_t *buf)
Read storage content.
Definition: ext-flash.c:374
static bool write_enable(const spi_device_t *flash_spi_configuration)
Enable write.
Definition: ext-flash.c:306
spi_status_t spi_read(const spi_device_t *dev, uint8_t *buf, int size)
Reads a buffer from an SPI device.
Definition: spi.c:140
spi_status_t spi_write_byte(const spi_device_t *dev, uint8_t data)
Writes a single byte to an SPI device.
Definition: spi.c:98
#define BLS_CODE_READ_STATUS
Read Status Register.
Definition: ext-flash.c:73
#define GPIO_HAL_PIN_UNKNOWN
Unknown GPIO.
Definition: gpio-hal.h:194
#define BLS_CODE_PD
Power down.
Definition: ext-flash.c:78
bool ext_flash_open(const spi_device_t *conf)
Initialize storage driver.
Definition: ext-flash.c:325
bool ext_flash_erase(const spi_device_t *conf, uint32_t offset, uint32_t length)
Erase storage sectors corresponding to the range.
Definition: ext-flash.c:475
Header file for the SPI HAL.
static bool power_down(const spi_device_t *flash_spi_configuration)
Put the device in power save mode.
Definition: ext-flash.c:239
static bool select_on_bus(const spi_device_t *flash_spi_configuration)
Clear external flash CSN line.
Definition: ext-flash.c:135
spi_status_t spi_write(const spi_device_t *dev, const uint8_t *data, int size)
Writes a buffer to an SPI device.
Definition: spi.c:112
spi_status_t spi_acquire(const spi_device_t *dev)
Locks and then opens an SPI controller.
Definition: spi.c:46
spi_status_t spi_deselect(const spi_device_t *dev)
Deselects the SPI peripheral.
Definition: spi.c:80
bool ext_flash_close(const spi_device_t *conf)
Close the storage driver.
Definition: ext-flash.c:355
static bool wait_ready(const spi_device_t *flash_spi_configuration)
Wait till previous erase/program operation completes.
Definition: ext-flash.c:157
#define BLS_CODE_MDID
Manufacturer Device ID.
Definition: ext-flash.c:76
Header file for the external SPI flash API.
static bool power_standby(const spi_device_t *flash_spi_configuration)
Take device out of power save mode and prepare it for normal operation.
Definition: ext-flash.c:280
bool ext_flash_init(const spi_device_t *conf)
Initialise the external flash.
Definition: ext-flash.c:527
SPI Device Configuration.
Definition: spi.h:100
spi_status_t spi_release(const spi_device_t *dev)
Closes and then unlocks an SPI controller.
Definition: spi.c:57
#define BLS_CODE_RPD
Release Power-Down.
Definition: ext-flash.c:79
#define BLS_CODE_READ
Read Data.
Definition: ext-flash.c:72
Header file for the GPIO HAL.
Header file for the logging system
#define BLS_CODE_SECTOR_ERASE
Sector Erase.
Definition: ext-flash.c:75
#define BLS_STATUS_BIT_BUSY
Busy bit of the status register.
Definition: ext-flash.c:95
static uint8_t verify_part(const spi_device_t *flash_spi_configuration)
Verify the flash part.
Definition: ext-flash.c:205
bool ext_flash_write(const spi_device_t *conf, uint32_t offset, uint32_t length, const uint8_t *buf)
Write to storage sectors.
Definition: ext-flash.c:415
static const spi_device_t * get_spi_conf(const spi_device_t *conf)
Get spi configuration, return default configuration if NULL.
Definition: ext-flash.c:123