hsk_libs-dev  163:b63ae088cc97
High Speed Karlsruhe XC878 library collection
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
hsk_adc.h
Go to the documentation of this file.
1 /** \file
2  * HSK Analog Digital Conversion headers
3  *
4  * This library provides access to all 8 ADC channels. Each channel can be
5  * provided with a pointer. Every completed conversion is written to the
6  * address provided by the pointer.
7  * The target memory can be protected for read access by msking the interrupts
8  * with EADC.
9  *
10  * The conversion time can be freely configured in a wide range. Even
11  * short conversion times like 5µs yield good precission.
12  *
13  * In order to keep the conversion going a service function hsk_adc_service()
14  * has to be called on a regular basis. This prevents locking up of the
15  * CPU due to an overload of interrupts, the ADC module can provide a new
16  * conversion result every 30 clock cycles.
17  *
18  * Making the hsk_adc_service() call only as often as needed reduces the
19  * drain on the analogue input and reduces flickering.
20  *
21  * Alternatively hsk_adc_request() can be used to request single just in time
22  * conversions.
23  *
24  * @author kami
25  */
26 
27 #ifndef _HSK_ADC_H_
28 #define _HSK_ADC_H_
29 
30 /*
31  * Required for SDCC to propagate ISR prototypes.
32  */
33 #ifdef SDCC
34 #include "../hsk_isr/hsk_isr.isr"
35 #endif /* SDCC */
36 
37 
38 /**
39  * 10 bit ADC resolution.
40  */
41 #define ADC_RESOLUTION_10 0
42 
43 /**
44  * 8 bit ADC resultion.
45  */
46 #define ADC_RESOLUTION_8 1
47 
48 /**
49  * Typedef for ADC channel ids.
50  */
51 typedef ubyte hsk_adc_channel;
52 
53 /**
54  * Initialize the AD conversion.
55  *
56  * The shortest possible conversion time is 1.25µs, the longest is 714.75µs.
57  * The given value will be rounded down.
58  *
59  * Note if hsk_adc_service() is not called in intervals shorter than convTime,
60  * there will be a waiting period between conversions. This prevents locking
61  * up of the controler with erratic interrupts.
62  *
63  * There is a 4 entry queue, for starting conversions, so it suffices to
64  * average the interval below convTime.
65  *
66  * All already open channels will be closed upon calling this function.
67  *
68  * @param resolution
69  * The conversion resolution, any of ADC_RESOLUTION_*
70  * @param convTime
71  * The desired conversion time in µs
72  */
73 void hsk_adc_init(ubyte resolution, uword __xdata convTime);
74 
75 /**
76  * Turns on ADC conversion, if previously deactivated.
77  */
78 void hsk_adc_enable(void);
79 
80 /**
81  * Turns off ADC conversion unit to converse power.
82  */
83 void hsk_adc_disable(void);
84 
85 /**
86  * Backwards compatibility hack.
87  *
88  * @deprecated
89  * Use hsk_adc_open10() or hsk_adc_open8() as appropriate
90  */
91 #define hsk_adc_open hsk_adc_open10
92 
93 /**
94  * Open the given ADC channel in 10 bit mode.
95  *
96  * @param channel
97  * The channel id
98  * @param target
99  * A pointer where to store conversion results
100  */
101 void hsk_adc_open10(const hsk_adc_channel channel,
102  uword * const target);
103 /**
104  * Open the given ADC channel in 8 bit mode.
105  *
106  * @param channel
107  * The channel id
108  * @param target
109  * A pointer where to store conversion results
110  */
111 void hsk_adc_open8(const hsk_adc_channel channel,
112  ubyte * const target);
113 
114 /**
115  * Close the given ADC channel.
116  *
117  * Stopp ADC if no more channels were left.
118  *
119  * @param channel
120  * The channel id
121  */
122 void hsk_adc_close(const hsk_adc_channel channel);
123 
124 /**
125  * A maintenance function that takes care of keeping AD conversions going.
126  * This has to be called repeatedly.
127  *
128  * There is a queue of up to 4 conversion jobs. One call of this function
129  * only adds one job to the queue.
130  *
131  * @retval 0
132  * No conversion request had been queued, either the queue is full or
133  * no channels have been configured
134  * @retval 1
135  * A conversion request has been added to the queue
136  */
137 bool hsk_adc_service(void);
138 
139 /**
140  * Requests an ADC for a specific channel.
141  *
142  * This function is an alternative to hsk_adc_service(). Make requests
143  * in time before the updated value is required.
144  *
145  * This function uses the same queue as hsk_adc_service(), if the queue is
146  * full it fails silently.
147  *
148  * @param channel
149  * The channel id
150  * @retval 0
151  * The queue is full
152  * @retval 1
153  * A conversion request has been added to the queue
154  */
155 bool hsk_adc_request(const hsk_adc_channel channel);
156 
157 /**
158  * Backwards compatibility hack.
159  *
160  * @deprecated
161  * Use hsk_adc_warmup10()
162  */
163 #define hsk_adc_warmup hsk_adc_warmup10
164 
165 /**
166  * Warm up 10 bit AD conversion.
167  *
168  * I.e. make sure all conversion targets have been initialized with a
169  * conversion result. This is a blocking function only intended for single
170  * use during the boot procedure.
171  *
172  * This function will not terminate unless interrupts are enabled.
173  *
174  * @note
175  * This function only works in 10 bit mode, because in 8 bit mode
176  * it is impossible to initialize targets with an invalid value.
177  */
178 void hsk_adc_warmup10(void);
179 
180 #endif /* _HSK_ADC_H_ */