I2C DriverModel Thoughts

Ok, Driver Model, (big deep voice with Echo)

#define I2CMODE_MERGE_DATAQUEUE (BIT(0)) // all dq elements from this handle will be merged into the main dq,
                                         // and executed as soon as STOP
#define I2CMODE_ISOLATE_DATAQUEUE (BIT(1)) // this task's dq's are held in a separate queue only being processed
                                           // when this queue is complete (START -> STOP)
#define I2CMODE_PURGE_DATAQUEUE (BIT(2)) // this Task's remaining dq's are purged on CloseI2C(),
                                         // else a STOP is appended and flushed

typedef enum{
  I2C_SUCCESS = 0,
  I2C_MODE_INVALID, // wrong bits!
  I2C_HANDLE_INVALID, // Handle must be NULL on OPEN and NEVER changed during Use.
  I2C_DATAQUEUE_DELETED,
  I2C_DATAQUEUE_EMPTY,  // no dq elements exist for this handle 
  I2C_DATAQUEUE_RUNNING,  // dq elements for this Task are being handled by ISR
  I2C_DEV_ID_INVALID, // I2C device address Invalid see addQueueWriteI2C()
}I2CRESULTS_t
 
I2C_RESULTS_t OpenI2C(EventGroupHandle_t * taskHandle, uint32_t openMode);
/* taskHandle is created by OpenI2C, all subsequent calls will use it.
*/

I2C_RESULTS_t CloseI2C(EventGroupHandle_t taskHandle, uint32_t closeMode);
/* closeMode:
  I2CMODE_PURGE_DATAQUEUE -> this Task's remaining dq's are purged on CloseI2C(), dq's EG are set to error,Purge
  if any of this task dq exist in the running ISR, this call will hang until the ISR completes.

  taskHandle -> the EventGroup associated with this handle is deleted, all pending Waits receive 0 as group Value.
*/

I2C_RESULTS_t PurgeI2C(EventGroupHandle_t taskHandle);
/* only purges elements that have not been handed off to ISR, Once dq's have been added to Main Q and Main Q is active, they are out of range.
results:
  I2C_SUCCESS -> Elements Deleted from dq
  I2C_DATAQUEUE_EMPTY -> no element from this task exist in queue, either Isolated Queue or Main Queue.
  I2C_DATAQUEUE_RUNNING -> ISR is handling dq's from this task
*/

I2C_RESULTS_t FlushI2C(EventGroupHandle_t taskHandle);
/* Move dq's to Main Q, append STOP.  If this task's Mode is MERGE and other task's dq's are also in Main Q, then
  the Main Q is split at this task's last element(which gets a STOP).
results:
  I2C_SUCCESS -> Elements Deleted from dq
  I2C_DATAQUEUE_EMPTY -> no element from this task exist in queue, either Isolated Queue or Main Queue.
  I2C_DATAQUEUE_RUNNING -> ISR is handling dq's from this task
*/

I2C_RESULTS_t addQueueWriteI2C(EventGroupHandle_t taskHandle, uint16_t devId, uint8_t *buff, uint16_t buffLen, bool sendStop, EventGroupHandle_t dqEvent);
/* devId -> for 7bit 0..0x77,0x7C..0x7F
  for 10bit 0x7800..0x7B00
  sendStop -> if false, will queue.
      if True, may queue.  If the ISR is currently running this element will be queued and released after current ISR completes.  If ISR is not running, it will cause the ISR to be started.
  dqEvent -> if not NULL, this EventGroup will be updated on status change by both the ISR and Dispatcher
*/

I2C_RESULTS_t addQueueReadI2C(EventGroupHandle_t taskHandle, uint16_t devId, uint8_t *buff, uint16_t buffLen, bool sendStop, EventGroupHandle_t dqEvent);
/*

*/

I2C_RESULTS_t addQueueTransactI2C(EventGroupHandle_t taskHandle, uint16_t devId, uint8_t *writeBuff, uint16_t writeBuffLen, uint8_t *readBuff, uint16_t readBufLen, bool sendStop, EventGroupHandle_t dqEvent);
/*
this function is atomic. Both Write, and Read will execute in order. It may be queued if sendStop=false, or the ISR is currently Running.

sendStop -> only applied to the ReadBuffer.  The writeBuffer will always have its endStop=FALSE. 

dqEvent -> only applies to the ReadBuffer.  

*/