Merge branch 'master' into freertos

1 files changed, 53 insertions, 90 deletions

diff --git a/src/gadc/driver.h b/src/gadc/driver.h
index 4427f4f0..e85eed48 100644
--- a/src/gadc/driver.h
+++ b/src/gadc/driver.h
@@ -27,30 +27,35 @@
 
 /**
  * @brief				The structure passed to start a timer conversion
- * @note				We use the structure instead of parameters purely to save
- * 						interrupt stack space which is very limited in some platforms.
  * @{
  */
-typedef struct GadcLldTimerData_t {
-	uint32_t		physdev;		/* @< A value passed to describe which physical ADC devices/channels to use. */
-	adcsample_t		*buffer;		/* @< The static buffer to put the ADC samples into. */
-	size_t			count;			/* @< The number of conversions to do before doing a callback and stopping the ADC. */
-	bool_t			now;			/* @< Trigger the first conversion now rather than waiting for the first timer interrupt (if possible) */
-	} GadcLldTimerData;
+typedef struct GadcTimerJob_t {
+	uint32_t		physdev;					// @< The physical device/s. The exact meaning of physdev is hardware dependent.
+	uint32_t		frequency;					// @< The frequency to sample
+	adcsample_t		*buffer;					// @< Where to put the samples
+	size_t			todo;						// @< How many conversions to do
+	size_t			done;						// @< How many conversions have already been done
+} GadcTimerJob;
 /* @} */
 
 /**
- * @brief				The structure passed to start a non-timer conversion
- * @note				We use the structure instead of parameters purely to save
- * 						interrupt stack space which is very limited in some platforms.
+ * @brief				The structure passed to do a single conversion
  * @{
  */
-typedef struct GadcLldNonTimerData_t {
-	uint32_t		physdev;		/* @< A value passed to describe which physical ADC devices/channels to use. */
-	adcsample_t		*buffer;		/* @< The static buffer to put the ADC samples into. */
-	} GadcLldNonTimerData;
+typedef struct GadcNonTimerJob_t {
+	uint32_t				physdev;			// @< The physical device/s. The exact meaning of physdev is hardware dependent.
+	adcsample_t				*buffer;			// @< Where to put the samples.
+	} GadcNonTimerJob;
 /* @} */
 
+/*===========================================================================*/
+/* External declarations.                                                    */
+/*===========================================================================*/
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /**
  * @brief				These routines are the callbacks that the driver uses.
  * @details				Defined in the high level GADC code.
@@ -58,40 +63,21 @@ typedef struct GadcLldNonTimerData_t {
  * @notapi
  * @{
  */
-
-/**
- * @param[in] adcp		The ADC driver
- * @param[in] buffer	The sample buffer
- * @param[in] n			The amount of samples
- */
-extern void GADC_ISR_CompleteI(ADCDriver *adcp, adcsample_t *buffer, size_t n);
-
-/**
- * @param[in] adcp 		The ADC driver
- * @param[in] err 		ADC error
- */
-extern void GADC_ISR_ErrorI(ADCDriver *adcp, adcerror_t err);
+	/**
+	 * @brief	Indicate that some data has been placed into the buffer for the current job
+	 *
+	 * @param[in] n		The number of samples placed in the buffer
+	 *
+	 * @note		Calling this with n = 0 causes the current job to be terminated early or aborted.
+	 * 				It can be called in this mode on an ADC conversion error. Any job will then be
+	 * 				restarted by the high level code as appropriate.
+	 */
+	void gadcGotDataI(size_t n);
 /**
  * @}
  */
 
 /**
- * @brief				This can be incremented by the low level driver if a timer interrupt is missed.
- * @details				Defined in the high level GADC code.
- *
- * @notapi
- */
-extern volatile bool_t GADC_Timer_Missed;
-
-/*===========================================================================*/
-/* External declarations.                                                    */
-/*===========================================================================*/
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-/**
  * @brief				Initialise the driver
  *
  * @api
@@ -99,86 +85,63 @@ extern "C" {
 void gadc_lld_init(void);
 
 /**
- * @brief				Get the number of samples in a conversion.
- * @details				Calculates and returns the number of samples per conversion for the specified physdev.
+ * @brief				Using the hardware dependant "physdev", return the number of samples for each conversion
  *
- * @note				A physdev describing a mono device would return 1, a stereo device would return 2.
- * 						For most ADC's physdev is a bitmap so it is only a matter of counting the bits.
+ * @param[in] physdev	The hardware dependent physical device descriptor
  *
- * @param[in] physdev	A value passed to describe which physical ADC devices/channels to use.
+ * @return				The number of samples per conversion
  *
- * @return				Number of samples of the convesion
  * @api
  */
-size_t gadc_lld_samples_per_conversion(uint32_t physdev);
+size_t gadc_lld_samplesperconversion(uint32_t physdev);
 
 /**
  * @brief				Start a periodic timer for high frequency conversions.
  *
- * @param[in] physdev		A value passed to describe which physical ADC devices/channels to use.
- * @param[in] frequency		The frequency to create ADC conversions
+ * @param[in] freq		The frequency for the timer
  *
- * @note				The exact meaning of physdev is hardware dependent. It describes the channels
- * 						the will be used later on when a "timer" conversion is actually scheduled.
- * @note				It is assumed that the timer is capable of free-running even when the ADC
- * 						is stopped or doing something else.
- * @details				When a timer interrupt occurs a conversion should start if these is a "timer" conversion
- * 						active.
- * @note				If the ADC is stopped, doesn't have a "timer" conversion active or is currently executing
- * 						a non-timer conversion then the interrupt can be ignored other than (optionally) incrementing
- * 						the GADC_Timer_Missed variable.
+ * @note				This will only be called if the timer is currently stopped.
  *
  * @api
+ * @iclass
  */
-void gadc_lld_start_timer(uint32_t physdev, uint32_t frequency);
+void gadc_lld_start_timerI(uint32_t freq);
 
 /**
  * @brief				Stop the periodic timer for high frequency conversions.
- * @details				Also stops any current "timer" conversion (but not a current "non-timer" conversion).
  *
- * @param[in] physdev	A value passed to describe which physical ADC devices/channels in use.
- *
- * @note				The exact meaning of physdev is hardware dependent.
+ * @note				This will only be called if the timer is currently running and all timer jobs
+ * 						have been completed/aborted.
  *
  * @api
+ * @iclass
  */
-void gadc_lld_stop_timer(uint32_t physdev);
+void gadc_lld_stop_timerI(void);
 
 /**
- * @brief				Start a "timer" conversion.
- * @details				Starts a series of conversions triggered by the timer.
+ * @brief				Start a set of high frequency conversions.
  *
- * @param[in] pgtd		Contains the parameters for the timer conversion.
+ * @note				This will only be called if the timer is currently running and the ADC should be ready for
+ * 						a new job.
  *
- * @note				The exact meaning of physdev is hardware dependent. It is likely described in the
- * 						drivers gadc_lld_config.h
- * @note				Some versions of ChibiOS actually call the callback function more than once, once
- * 						at the half-way point and once on completion. The high level code handles this.
- * @note				The driver should call @p GADC_ISR_CompleteI() when it completes the operation
- * 						(or at the half-way point), or @p GAD_ISR_ErrorI() on an error.
- * @note				The high level code ensures that this is not called while a non-timer conversion is in
- * 						progress
+ * @param[in] pjob		The job to be started.
  *
+ * @api
  * @iclass
  */
-void gadc_lld_adc_timerI(GadcLldTimerData *pgtd);
+void gadc_lld_timerjobI(GadcTimerJob *pjob);
 
 /**
- * @brief				Start a "non-timer" conversion.
- * @details				Starts a single conversion now.
+ * @brief				Start a non-timer conversion.
  *
- * @param[in] pgntd		Contains the parameters for the non-timer conversion.
+ * @note				This will only be called if the ADC should be ready for a new job.
  *
- * @note				The exact meaning of physdev is hardware dependent. It is likely described in the
- * 						drivers gadc_lld_config.h
- * @note				The driver should call @p GADC_ISR_CompleteI() when it completes the operation
- * 						or @p GAD_ISR_ErrorI() on an error.
- * @note				The high level code ensures that this is not called while a timer conversion is in
- * 						progress
+ * @param[in] pjob		The job to be started
  *
+ * @api
  * @iclass
  */
-void gadc_lld_adc_nontimerI(GadcLldNonTimerData *pgntd);
+void gadc_lld_nontimerjobI(GadcNonTimerJob *pjob);
 
 #ifdef __cplusplus
 }