NFCEEPROMDriver.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 
00017 #ifndef MBED_NFC_EEPROM_DRIVER_H
00018 #define MBED_NFC_EEPROM_DRIVER_H
00019 
00020 #include <stdint.h>
00021 
00022 #include "events/EventQueue.h"
00023 
00024 namespace mbed {
00025 namespace nfc {
00026 
00027 /**
00028  * @addtogroup nfc
00029  * @{
00030  */
00031 
00032 /**
00033  * The abstraction for a NFC EEPROM driver.
00034  * Implementers need to derive from this class and implement its methods.
00035  */
00036 class NFCEEPROMDriver  {
00037 public:
00038     /**
00039      * Construct a NFCEEPROM driver instance.
00040      */
00041     NFCEEPROMDriver();
00042 
00043     /**
00044      * NFCEEPROM driver destructor.
00045      */
00046     virtual ~NFCEEPROMDriver();
00047 
00048     /**
00049      * The NFCEEPROMDriver delegate.
00050      * Methods in this class are called by the driver on completion of long-running operations.
00051      */
00052     struct Delegate {
00053         /**
00054          * Completion of session start operation.
00055          *
00056          * @param[in] success whether this operation succeeded
00057          */
00058         virtual void on_session_started(bool success) = 0;
00059 
00060         /**
00061          * Completion of session end operation.
00062          *
00063          * @param[in] success whether this operation succeeded
00064          */
00065         virtual void on_session_ended(bool success) = 0;
00066 
00067         /**
00068          * Completion of read operation.
00069          *
00070          * @param[in] count number of bytes actually read
00071          */
00072         virtual void on_bytes_read(size_t count) = 0;
00073 
00074         /**
00075          * Completion of write operation.
00076          *
00077          * @param[in] count number of bytes actually written
00078          */
00079         virtual void on_bytes_written(size_t count) = 0;
00080 
00081         /**
00082          * Completion of size retrieval operation.
00083          *
00084          * @param[in] success whether this operation succeeded
00085          * @param[out] size the current addressable memory size
00086          */
00087         virtual void on_size_read(bool success, size_t size) = 0;
00088 
00089         /**
00090          * Completion of size setting operation.
00091          *
00092          * @param[in] success whether this operation succeeded
00093          */
00094         virtual void on_size_written(bool success) = 0;
00095 
00096         /**
00097          * Completion of erasing operation.
00098          *
00099          * @param[in] count number of bytes actually erased
00100          */
00101         virtual void on_bytes_erased(size_t count) = 0;
00102 
00103     protected:
00104         ~Delegate() {}
00105     };
00106 
00107     /**
00108      * Set the delegate that will receive events generated by this EEPROM.
00109      *
00110      * @param[in] delegate the delegate instance to use
00111      */
00112     void set_delegate(Delegate *delegate);
00113 
00114     /**
00115      * Set the event queue that will be used to schedule event handling
00116      *
00117      * @param[in] queue the queue instance to use
00118      */
00119     void set_event_queue(events::EventQueue *queue);
00120 
00121     /**
00122      * Reset and initialize the EEPROM.
00123      * This method should complete synchronously.
00124      */
00125     virtual void reset() = 0;
00126 
00127     /**
00128      * Get the maximum memory size addressable by the EEPROM.
00129      */
00130     virtual size_t read_max_size() = 0;
00131 
00132     /**
00133      * Start a session of operations (reads, writes, erases, size gets/sets).
00134      * This method is called prior to any memory access to allow the underlying implementation
00135      * to disable the RF interface or abort the transaction if it's being used.
00136      * This method should complete asynchronously by calling has_started_session().
00137      */
00138     virtual void start_session(bool force = true) = 0; // This could lock the chip's RF interface
00139 
00140     /**
00141      * End a session.
00142      * This method should complete asynchronously by calling has_ended_session().
00143      */
00144     virtual void end_session() = 0;
00145 
00146     /**
00147      * Read bytes from memory.
00148      * @param[in] address the virtual address (starting from 0) from which to start the read.
00149      * @param[out] bytes a buffer in which the read bytes will be stored.
00150      *  This buffer should remain valid till the callback is called.
00151      * @param[in] count the number of bytes to read.
00152      * This method should complete asynchronously by calling has_read_bytes().
00153      */
00154     virtual void read_bytes(uint32_t address, uint8_t *bytes, size_t count) = 0;
00155 
00156     /**
00157      * Write bytes to memory.
00158      * @param[in] address the virtual address (starting from 0) from which to start the write.
00159      * @param[in] bytes a buffer from to copy.
00160      *  This buffer should remain valid till the callback is called.
00161      * @param[in] count the number of bytes to write.
00162      * This method should complete asynchronously by calling has_written_bytes().
00163      */
00164     virtual void write_bytes(uint32_t address, const uint8_t *bytes, size_t count) = 0;
00165 
00166     /**
00167      * Retrieve the size of the addressable memory.
00168      * This method should complete asynchronously by calling has_gotten_size().
00169      */
00170     virtual void read_size() = 0;
00171 
00172     /**
00173      * Set the size of the addressable memory.
00174      * @param[in] count the number of addressable bytes.
00175      * This method should complete asynchronously by calling has_set_size().
00176      */
00177     virtual void write_size(size_t count) = 0;
00178 
00179     /**
00180      * Erase bytes from memory.
00181      * @param[in] address the virtual address (starting from 0) from which to start erasing.
00182      * @param[in] size the number of bytes to erase.
00183      * This method should complete asynchronously by calling has_erased_bytes().
00184      */
00185     virtual void erase_bytes(uint32_t address, size_t size) = 0;
00186 
00187 protected:
00188     Delegate *delegate();
00189     events::EventQueue *event_queue();
00190 
00191 private:
00192     Delegate *_delegate;
00193     events::EventQueue *_event_queue;
00194 };
00195 
00196 /**
00197  * @}
00198  */
00199 
00200 } // namespace nfc
00201 } // namespace mbed
00202 
00203 #endif