[people/ms/u-boot.git] / doc / driver-model / UDM-watchdog.txt

The U-Boot Driver Model Project
===============================
Watchdog device subsystem analysis
==================================

Tomas Hlavacek <tmshlvck@gmail.com>
2012-03-09

I) Overview
-----------

U-Boot currently implements an API for HW watchdog devices as explicit drivers
in drivers/watchdog directory. There are also drivers for both hardware and
software watchdog on particular CPUs implemented in arch/*/cpu/*/cpu.c. There
are macros in include/watchdog.h that selects between SW and HW watchdog and
assembly SW implementation.

The current common interface comprises of one set out of these two possible
variants:

    1)
    void watchdog_reset(void);
    int watchdog_disable(void);
    int watchdog_init(void);

    2)
    void hw_watchdog_reset(void);
    void hw_watchdog_init(void);

The watchdog implementations are also spread through board/*/*.c that in
some cases. The API and semantics is in most cases same as the above
mentioned common functions.


II) Approach
------------

  1) New API
  ----------

  In the UDM each watchdog driver would register itself by a function

    int watchdog_device_register(struct instance *i,
				 const struct watchdog_device_ops *o);

  The structure being defined as follows:

    struct watchdog_device_ops {
	int (*disable)(struct instance *i);
	void (*reset)(struct instance *i);
    };

  The watchdog_init() function will be dissolved into probe() function.

  2) Conversion thougths
  ----------------------

  Conversion of watchdog implementations to a new API could be divided
  to three subsections: a) HW implementations, which are mostly compliant
  to the above mentioned API; b) SW implementations, which are compliant
  to the above mentioned API and c) SW implementations that are not compliant
  to the API and has to be rectified or partially rewritten.

III) Analysis of in-tree drivers
--------------------------------

  1) drivers/watchdog/at91sam9_wdt.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  2) drivers/watchdog/ftwdt010_wdt.c
  ----------------------------------
  The driver is ad-hoc HW watchdog. Conversion has to take into account
  driver parts spread in include/faraday/*. Restructuring the driver and
  code cleanup has to be considered.


  3) arch/arm/cpu/arm1136/mx31/timer.c
  ------------------------------------
  The driver is semi-standard ad-hoc HW watchdog. Conversion has to take
  into account driver parts spread in the timer.c file.


  4) arch/arm/cpu/arm926ejs/davinci/timer.c
  -----------------------------------------
  The driver is ad-hoc semi-standard HW watchdog. Conversion has to take
  into account driver parts spread in the timer.c file.


  5) arch/arm/cpu/armv7/omap-common/hwinit-common.c
  -------------------------------------------------
  The driver is non-standard ad-hoc HW watchdog. Conversion is possible
  but functions has to be renamed and constants moved to another places.


  6) arch/arm/cpu/armv7/omap3/board.c
  -----------------------------------
  The driver is non-standard ad-hoc HW watchdog. Conversion is possible
  but functions has to be renamed and constants moved to another places.


  7) arch/blackfin/cpu/watchdog.c
  -------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  8) arch/m68k/cpu/mcf523x/cpu.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  9) arch/m68k/cpu/mcf52x2/cpu.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  10) arch/m68k/cpu/mcf532x/cpu.c
  -------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  11) arch/m68k/cpu/mcf547x_8x/cpu.c
  ----------------------------------
  The driver is standard HW watchdog (there is slight naming convention
  violation that has to be rectified). Simple conversion is possible.


  12) arch/powerpc/cpu/74xx_7xx/cpu.c
  -----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  13) arch/powerpc/cpu/mpc512x/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  14) arch/powerpc/cpu/mpc5xx/cpu.c
  ---------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  15) arch/powerpc/cpu/mpc5xxx/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  16) arch/powerpc/cpu/mpc8260/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  17) arch/powerpc/cpu/mpc83xx/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  18) arch/powerpc/cpu/mpc85xx/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  19) arch/powerpc/cpu/mpc86xx/cpu.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  20) arch/powerpc/cpu/mpc8xx/cpu.c

  The driver is standard HW watchdog. Simple conversion is possible.


  21) arch/powerpc/cpu/ppc4xx/cpu.c
  ---------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  22) arch/sh/cpu/sh2/watchdog.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  23) arch/sh/cpu/sh3/watchdog.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  24) arch/sh/cpu/sh4/watchdog.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  25) board/amcc/luan/luan.c
  --------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  26) board/amcc/yosemite/yosemite.c
  ----------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  27) board/apollon/apollon.c
  ---------------------------
  The driver is standard HW watchdog however the watchdog_init()
  function is called in early initialization. Simple conversion is possible.


  28) board/bmw/m48t59y.c
  -----------------------
  Special watchdog driver. Dead code. To be removed.


  29) board/davedenx/qong/qong.c
  ------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  30) board/dvlhost/watchdog.c
  ----------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  31) board/eNET/eNET.c
  ---------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  32) board/eltec/elppc/elppc.c
  -----------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  33) board/enbw/enbw_cmc/enbw_cmc.c
  ----------------------------------
  Only function proxy call. Code cleanup needed.


  34) board/freescale/mx31pdk/mx31pdk.c
  -------------------------------------
  Only function proxy call. Code cleanup needed.


  35) board/gth2/gth2.c
  ---------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  36) board/lwmon5/lwmon5.c
  -------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  37) board/manroland/mucmc52/mucmc52.c
  -------------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  38) board/manroland/uc101/uc101.c
  ---------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  39) board/mousse/m48t59y.c
  --------------------------
  Special watchdog driver. Dead code. To be removed.


  40) board/mvblue/mvblue.c
  -------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  41) board/netphone/netphone.c
  -----------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  42) board/netta/netta.c
  -----------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  43) board/netta2/netta2.c
  -------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  44) board/omicron/calimain/calimain.c
  -------------------------------------
  Only function proxy call. Code cleanup needed.


  46) board/pcs440ep/pcs440ep.c
  -----------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  47) board/stx/stxxtc/stxxtc.c
  -----------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  48) board/ti/omap2420h4/omap2420h4.c
  ------------------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  49) board/ttcontrol/vision2/vision2.c
  -------------------------------------
  The driver is standard HW watchdog but namespace is polluted by
  non-standard macros. Simple conversion is possible, code cleanup
  needed.


  50) board/v38b/v38b.c
  ---------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  51) board/ve8313/ve8313.c
  -------------------------
  The driver is standard HW watchdog. Simple conversion is possible.


  52) board/w7o/watchdog.c
  ------------------------
  The driver is standard HW watchdog. Simple conversion is possible.
Commit	Line	Data
f07563a7 TH	1	The U-Boot Driver Model Project
	2	===============================
	3	Watchdog device subsystem analysis
	4	==================================
	5
	6	Tomas Hlavacek <tmshlvck@gmail.com>
	7	2012-03-09
	8
	9	I) Overview
	10	-----------
	11
	12	U-Boot currently implements an API for HW watchdog devices as explicit drivers
	13	in drivers/watchdog directory. There are also drivers for both hardware and
	14	software watchdog on particular CPUs implemented in arch//cpu//cpu.c. There
	15	are macros in include/watchdog.h that selects between SW and HW watchdog and
	16	assembly SW implementation.
	17
	18	The current common interface comprises of one set out of these two possible
	19	variants:
	20
	21	1)
	22	void watchdog_reset(void);
	23	int watchdog_disable(void);
	24	int watchdog_init(void);
	25
	26	2)
	27	void hw_watchdog_reset(void);
	28	void hw_watchdog_init(void);
	29
	30	The watchdog implementations are also spread through board//.c that in
	31	some cases. The API and semantics is in most cases same as the above
	32	mentioned common functions.
	33
	34
	35	II) Approach
	36	------------
	37
	38	1) New API
	39	----------
	40
	41	In the UDM each watchdog driver would register itself by a function
	42
	43	int watchdog_device_register(struct instance *i,
93e14596	44	const struct watchdog_device_ops *o);
f07563a7 TH	45
	46	The structure being defined as follows:
	47
	48	struct watchdog_device_ops {
93e14596 WD	49	int (disable)(struct instance i);
93e14596 WD	50	void (reset)(struct instance i);
f07563a7 TH	51	};
	52
	53	The watchdog_init() function will be dissolved into probe() function.
	54
	55	2) Conversion thougths
	56	----------------------
	57
	58	Conversion of watchdog implementations to a new API could be divided
	59	to three subsections: a) HW implementations, which are mostly compliant
	60	to the above mentioned API; b) SW implementations, which are compliant
	61	to the above mentioned API and c) SW implementations that are not compliant
	62	to the API and has to be rectified or partially rewritten.
	63
	64	III) Analysis of in-tree drivers
	65	--------------------------------
	66
	67	1) drivers/watchdog/at91sam9_wdt.c
	68	----------------------------------
	69	The driver is standard HW watchdog. Simple conversion is possible.
	70
	71
	72	2) drivers/watchdog/ftwdt010_wdt.c
	73	----------------------------------
	74	The driver is ad-hoc HW watchdog. Conversion has to take into account
	75	driver parts spread in include/faraday/*. Restructuring the driver and
	76	code cleanup has to be considered.
	77
	78
	79	3) arch/arm/cpu/arm1136/mx31/timer.c
	80	------------------------------------
	81	The driver is semi-standard ad-hoc HW watchdog. Conversion has to take
	82	into account driver parts spread in the timer.c file.
	83
	84
	85	4) arch/arm/cpu/arm926ejs/davinci/timer.c
	86	-----------------------------------------
	87	The driver is ad-hoc semi-standard HW watchdog. Conversion has to take
	88	into account driver parts spread in the timer.c file.
	89
	90
	91	5) arch/arm/cpu/armv7/omap-common/hwinit-common.c
	92	-------------------------------------------------
	93	The driver is non-standard ad-hoc HW watchdog. Conversion is possible
	94	but functions has to be renamed and constants moved to another places.
	95
	96
	97	6) arch/arm/cpu/armv7/omap3/board.c
	98	-----------------------------------
	99	The driver is non-standard ad-hoc HW watchdog. Conversion is possible
	100	but functions has to be renamed and constants moved to another places.
	101
	102
	103	7) arch/blackfin/cpu/watchdog.c
	104	-------------------------------
	105	The driver is standard HW watchdog. Simple conversion is possible.
	106
	107
	108	8) arch/m68k/cpu/mcf523x/cpu.c
	109	------------------------------
	110	The driver is standard HW watchdog. Simple conversion is possible.
	111
	112
	113	9) arch/m68k/cpu/mcf52x2/cpu.c
	114	------------------------------
115	The driver is standard HW watchdog. Simple conversion is possible.
116
117
118	10) arch/m68k/cpu/mcf532x/cpu.c
119	-------------------------------
120	The driver is standard HW watchdog. Simple conversion is possible.
121
122
123	11) arch/m68k/cpu/mcf547x_8x/cpu.c
124	----------------------------------
125	The driver is standard HW watchdog (there is slight naming convention
126	violation that has to be rectified). Simple conversion is possible.
127
128
129	12) arch/powerpc/cpu/74xx_7xx/cpu.c
130	-----------------------------------
131	The driver is standard HW watchdog. Simple conversion is possible.
132
133
134	13) arch/powerpc/cpu/mpc512x/cpu.c
135	----------------------------------
136	The driver is standard HW watchdog. Simple conversion is possible.
137
138
139	14) arch/powerpc/cpu/mpc5xx/cpu.c
140	---------------------------------
141	The driver is standard HW watchdog. Simple conversion is possible.
142
143
144	15) arch/powerpc/cpu/mpc5xxx/cpu.c
145	----------------------------------
146	The driver is standard HW watchdog. Simple conversion is possible.
147
148
149	16) arch/powerpc/cpu/mpc8260/cpu.c
150	----------------------------------
151	The driver is standard HW watchdog. Simple conversion is possible.
152
153
154	17) arch/powerpc/cpu/mpc83xx/cpu.c
155	----------------------------------
156	The driver is standard HW watchdog. Simple conversion is possible.
157
158
159	18) arch/powerpc/cpu/mpc85xx/cpu.c
160	----------------------------------
161	The driver is standard HW watchdog. Simple conversion is possible.
162
163
164	19) arch/powerpc/cpu/mpc86xx/cpu.c
165	----------------------------------
166	The driver is standard HW watchdog. Simple conversion is possible.
167
168
169	20) arch/powerpc/cpu/mpc8xx/cpu.c
170
171	The driver is standard HW watchdog. Simple conversion is possible.
172
173
174	21) arch/powerpc/cpu/ppc4xx/cpu.c
175	---------------------------------
176	The driver is standard HW watchdog. Simple conversion is possible.
177
178
179	22) arch/sh/cpu/sh2/watchdog.c
180	------------------------------
181	The driver is standard HW watchdog. Simple conversion is possible.
182
183
184	23) arch/sh/cpu/sh3/watchdog.c
185	------------------------------
186	The driver is standard HW watchdog. Simple conversion is possible.
187
188
189	24) arch/sh/cpu/sh4/watchdog.c
190	------------------------------
191	The driver is standard HW watchdog. Simple conversion is possible.
192
193
194	25) board/amcc/luan/luan.c
195	--------------------------
196	The driver is standard HW watchdog. Simple conversion is possible.
197
198
199	26) board/amcc/yosemite/yosemite.c
200	----------------------------------
201	The driver is standard HW watchdog. Simple conversion is possible.
202
203
204	27) board/apollon/apollon.c
205	---------------------------
206	The driver is standard HW watchdog however the watchdog_init()
207	function is called in early initialization. Simple conversion is possible.
208
209
210	28) board/bmw/m48t59y.c
211	-----------------------
212	Special watchdog driver. Dead code. To be removed.
213
214
215	29) board/davedenx/qong/qong.c
216	------------------------------
217	The driver is standard HW watchdog. Simple conversion is possible.
218
219
220	30) board/dvlhost/watchdog.c
221	----------------------------
222	The driver is standard HW watchdog. Simple conversion is possible.
223
224
225	31) board/eNET/eNET.c
226	---------------------
227	The driver is standard HW watchdog. Simple conversion is possible.
228
229
230	32) board/eltec/elppc/elppc.c
231	-----------------------------
232	The driver is standard HW watchdog. Simple conversion is possible.
233
234
235	33) board/enbw/enbw_cmc/enbw_cmc.c
236	----------------------------------
237	Only function proxy call. Code cleanup needed.
238
239
240	34) board/freescale/mx31pdk/mx31pdk.c
241	-------------------------------------
242	Only function proxy call. Code cleanup needed.
243
244
245	35) board/gth2/gth2.c
246	---------------------
247	The driver is standard HW watchdog. Simple conversion is possible.
248
249
250	36) board/lwmon5/lwmon5.c
251	-------------------------
252	The driver is standard HW watchdog. Simple conversion is possible.
253
254
255	37) board/manroland/mucmc52/mucmc52.c
256	-------------------------------------
257	The driver is standard HW watchdog. Simple conversion is possible.
258
259
260	38) board/manroland/uc101/uc101.c
261	---------------------------------
262	The driver is standard HW watchdog. Simple conversion is possible.
263
264
265	39) board/mousse/m48t59y.c
266	--------------------------
267	Special watchdog driver. Dead code. To be removed.
268
269
270	40) board/mvblue/mvblue.c
271	-------------------------
272	The driver is standard HW watchdog. Simple conversion is possible.
273
274
275	41) board/netphone/netphone.c
276	-----------------------------
277	The driver is standard HW watchdog. Simple conversion is possible.
278
279
280	42) board/netta/netta.c
281	-----------------------
282	The driver is standard HW watchdog. Simple conversion is possible.
283
284
285	43) board/netta2/netta2.c
286	-------------------------
287	The driver is standard HW watchdog. Simple conversion is possible.
288
289
290	44) board/omicron/calimain/calimain.c
291	-------------------------------------
292	Only function proxy call. Code cleanup needed.
293
294
f07563a7 TH	295	46) board/pcs440ep/pcs440ep.c
	296	-----------------------------
	297	The driver is standard HW watchdog. Simple conversion is possible.
	298
	299
	300	47) board/stx/stxxtc/stxxtc.c
	301	-----------------------------
	302	The driver is standard HW watchdog. Simple conversion is possible.
	303
	304
	305	48) board/ti/omap2420h4/omap2420h4.c
	306	------------------------------------
	307	The driver is standard HW watchdog. Simple conversion is possible.
	308
	309
	310	49) board/ttcontrol/vision2/vision2.c
	311	-------------------------------------
	312	The driver is standard HW watchdog but namespace is polluted by
	313	non-standard macros. Simple conversion is possible, code cleanup
	314	needed.
	315
	316
	317	50) board/v38b/v38b.c
	318	---------------------
	319	The driver is standard HW watchdog. Simple conversion is possible.
	320
	321
	322	51) board/ve8313/ve8313.c
	323	-------------------------
	324	The driver is standard HW watchdog. Simple conversion is possible.
	325
	326
	327	52) board/w7o/watchdog.c
	328	------------------------
	329	The driver is standard HW watchdog. Simple conversion is possible.