NFC eeprom doc

Author: paul-szczepanek-arm

docs/reference/contributing/connectivity/NFCEEPROMDriver.md

@@ -0,0 +1,84 @@
+## NFC EEPROM Driver porting guide
+
+NFC EEPROM provides low level operations needed to create an NFC TAG. The device usually allows for reading and writing into a shared memory by one device at a time through one of two channels. One is the radio channel used by external devices interacting with the device. The other is wired to the MCU. Either device needs to obtain a session before performing its operations. Session is released as the last step or through a timeout.
+
+### Class hierarchy
+
+The `NFCTarget` uses an implementation of `NFCEEPROMDriver` as the backend that delivers the fundamental operations needed to access and modify the memory containing the NDEF messages. The instance of the class is created by the target implementation of `NFCTarget`.
+
+Your implementation will inherit from `NFCEEPROMDriver` and implement all the public methods therein.
+
+### Required methods
+
+`NFCEEPROMDriver` defines the following pure virtual functions:
+
+- `void reset()`
+- `size_t read_max_size()`
+- `void start_session(bool force = false)`
+- `void end_session()`
+- `void read_bytes(uint32_t address, uint8_t* bytes, size_t count)`
+- `void write_bytes(uint32_t address, const uint8_t* bytes, size_t count)`
+- `void write_size(size_t count)`
+- `void read_size()`
+- `void erase_bytes(uint32_t address, size_t size)`
+
+#### Implementing `reset`
+
+This will be called during initialisation and may be called repeatedly. This must be safe to be called at any time and should return when the device is ready for operation.
+
+#### Implementing `read_max_size`
+
+This must return synchronously the (effective) size of the EEPROM memory available to NDEF messages (not including the memory required by other files).
+
+#### Implementing `start_session` and `end_session`
+
+These open and close the communication wit the device. The `start_session` has an extra parameter that indicates the session should be started even if it would kill the RF session in the process if one is already opened. Otherwise the `open_session` should trigger the `on_session_opened` with the parameter set to false (failure) if an RF session is already opened. 
+
+#### Implementing `read_bytes` and `write_bytes`
+
+Both methods contain the `address` which is to be used as the starting offset in the file. This starts at the beginning of the body of the file where NDEF messages may be written. Any headers must be accounted for in the offset and size calculations. The `count` parameters are the maximum sizes of the operations but the operation may return less than the requested counts.
+
+The events `on_bytes_read` and `on_bytes_written` must return the number of bytes successfully read or written in case the maximum size of the operation the device allows is smaller than the request operation. It's up to the caller to call these function multiple times with appropriate offsets as required.
+
+#### Implementing `read_size` and `write_size`
+
+These read and write the limits used by the write and read operations. Writing beyond the set size must be truncated to the set size.
+
+#### Implementing `erase_bytes`
+
+This is the equivalent of calling `write_bytes` with a buffer filled with `0`. Like `write_bytes` it must return the number of bytes successfully set to `0`.
+
+### Asynchronous operation
+
+Depending on your hardware you may support synchronous or asynchronous operation.
+
+The `NFCEEPROMDriver` is designed with asynchronous operation in mind and the results of long operation are communicated through events. These must be used even if your implementation is synchronous.
+
+In asynchronous implementations you may use an `EventQueue` to schedule processing caused by interrupts. The `NFCTarget` has set up your event queue which you can get by calling:
+`EventQueue* event_queue()`
+
+You may initiate your event processing by calling `call()` on the event queue.
+
+For example:
+
+if your event management is done in a function called `manage_event` then you should call `event_queue()->call(&manage_event);`. The `EventQueue` also accepts passed in parameters and objects for non-static method calls - please see the `EventQueue` documentation for details on calling function on the queue.
+    
+#### Communicating events back to the NFCTarget
+
+All events shall call function in the `Delegate` class object that has been set by the `NFCTarget`. Delegate is accessible through:
+`Delegate* delegate()`
+
+It implements the following methods:
+
+- `void on_session_started(bool success)`
+- `void on_session_ended(bool success)`
+- `void on_bytes_read(size_t count)`
+- `void on_bytes_written(size_t count)`
+- `void on_size_written(bool success)`
+- `void on_size_read(bool success, size_t size)`
+- `void on_bytes_erased(size_t count)`
+
+### Testing
+
+Run tests with:
+`mbed test -m [mcu] -t [toolchain] -n mbed-os-tests-nfceeprom*`.