SPIFReducedBlockDevice.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 #ifndef MBED_RSPIF_BLOCK_DEVICE_H
00017 #define MBED_RSPIF_BLOCK_DEVICE_H
00018 
00019 #include "SPI.h"
00020 #include "DigitalOut.h"
00021 #include "BlockDevice.h"
00022 
00023 /** Reduced BlockDevice for SPI based flash devices
00024  *  *Should only be used by Boot Loader*
00025  *
00026  *  @code
00027  *  // Here's an example using the SPI flash device on K82F
00028  *  #include "mbed.h"
00029  *  #include "SPIFReducedBlockDevice.h"
00030  *
00031  *  // Create flash device on SPI bus with PTE5 as chip select
00032  *  SPIFReducedBlockDevice rspif(PTE2, PTE4, PTE1, PTE5);
00033  *
00034  *  int main() {
00035  *      printf("reduced spif test\n");
00036  *
00037  *      // Initialize the Reduced SPI flash device and print the memory layout
00038  *      rspif.init();
00039  *      printf("rspif size: %llu\n",         rspif.size());
00040  *      printf("rspif read size: %llu\n",    rspif.get_read_size());
00041  *      printf("rspif program size: %llu\n", rspif.get_program_size());
00042  *      printf("rspif erase size: %llu\n",   rspif.get_erase_size());
00043  *
00044  *      // Write "Hello World!" to the first block
00045  *      char *buffer = (char*)malloc(rspif.get_erase_size());
00046  *      sprintf(buffer, "Hello World!\n");
00047  *      rspif.erase(0, rspif.get_erase_size());
00048  *      rspif.program(buffer, 0, rspif.get_erase_size());
00049  *
00050  *      // Read back what was stored
00051  *      rspif.read(buffer, 0, rspif.get_erase_size());
00052  *      printf("%s", buffer);
00053  *
00054  *      // Deinitialize the device
00055  *      rspif.deinit();
00056  *  }
00057  *  @endcode
00058  */
00059 class SPIFReducedBlockDevice : public BlockDevice {
00060 public:
00061     /** Creates a SPIFReducedBlockDevice on a SPI bus specified by pins
00062      *
00063      *  @param mosi     SPI master out, slave in pin
00064      *  @param miso     SPI master in, slave out pin
00065      *  @param sclk     SPI clock pin
00066      *  @param csel     SPI chip select pin
00067      *  @param freq     Clock speed of the SPI bus (defaults to 40MHz)
00068      */
00069     SPIFReducedBlockDevice(PinName mosi, PinName miso, PinName sclk, PinName csel, int freq = 40000000);
00070 
00071     /** Initialize a block device
00072      *
00073      *  @return         0 on success or a negative error code on failure
00074      */
00075     virtual int init();
00076 
00077     /** Deinitialize a block device
00078      *
00079      *  @return         0 on success or a negative error code on failure
00080      */
00081     virtual int deinit();
00082 
00083     /** Read blocks from a block device
00084      *
00085      *  @param buffer   Buffer to write blocks to
00086      *  @param addr     Address of block to begin reading from
00087      *  @param size     Size to read in bytes, must be a multiple of read block size
00088      *  @return         0 on success, negative error code on failure
00089      */
00090     virtual int read(void *buffer, bd_addr_t addr, bd_size_t size);
00091 
00092     /** Program blocks to a block device
00093      *
00094      *  The blocks must have been erased prior to being programmed
00095      *
00096      *  @param buffer   Buffer of data to write to blocks
00097      *  @param addr     Address of block to begin writing to
00098      *  @param size     Size to write in bytes, must be a multiple of program block size
00099      *  @return         0 on success, negative error code on failure
00100      */
00101     virtual int program(const void *buffer, bd_addr_t addr, bd_size_t size);
00102 
00103     /** Erase blocks on a block device
00104      *
00105      *  The state of an erased block is undefined until it has been programmed
00106      *
00107      *  @param addr     Address of block to begin erasing
00108      *  @param size     Size to erase in bytes, must be a multiple of erase block size
00109      *  @return         0 on success, negative error code on failure
00110      */
00111     virtual int erase(bd_addr_t addr, bd_size_t size);
00112 
00113     /** Get the size of a readable block
00114      *
00115      *  @return         Size of a readable block in bytes
00116      */
00117     virtual bd_size_t get_read_size() const;
00118 
00119     /** Get the size of a programable block
00120      *
00121      *  @return         Size of a programable block in bytes
00122      *  @note Must be a multiple of the read size
00123      */
00124     virtual bd_size_t get_program_size() const;
00125 
00126     /** Get the size of a eraseable block
00127      *
00128      *  @return         Size of a eraseable block in bytes
00129      *  @note Must be a multiple of the program size
00130      */
00131     virtual bd_size_t get_erase_size() const;
00132 
00133     /** Get the size of a eraseable block
00134      *
00135      *  @param addr     Address of block to query erase size
00136      *  @return         Size of a eraseable block in bytes
00137      *  @note Must be a multiple of the program size
00138      */
00139     virtual bd_size_t get_erase_size(bd_addr_t addr) const;
00140 
00141     /** Get the value of storage byte after it was erased
00142      *
00143      *  If get_erase_value returns a non-negative byte value, the underlying
00144      *  storage is set to that value when erased, and storage containing
00145      *  that value can be programmed without another erase.
00146      *
00147      *  @return         The value of storage when erased, or -1 if you can't
00148      *                  rely on the value of erased storage
00149      */
00150     virtual int get_erase_value() const;
00151 
00152     /** Get the total size of the underlying device
00153      *
00154      *  @return         Size of the underlying device in bytes
00155      */
00156     virtual bd_size_t size() const;
00157 
00158 private:
00159     // Master side hardware
00160     mbed::SPI _spi;
00161     mbed::DigitalOut _cs;
00162 
00163     // Device configuration discovered through sfdp
00164     bd_size_t _size;
00165 
00166     // Internal functions
00167     int _wren();
00168     int _sync();
00169     void _cmdread(uint8_t op, uint32_t addrc, uint32_t retc,
00170                   uint32_t addr, uint8_t *rets);
00171     void _cmdwrite(uint8_t op, uint32_t addrc, uint32_t argc,
00172                    uint32_t addr, const uint8_t *args);
00173 };
00174 #endif