Merge 'for-linus' branch of rsync://rsync.kernel.org/pub/scm/linux/kernel/git/shaggy...
[linux-2.6] / drivers / usb / misc / uss720.c
1 /*****************************************************************************/
2
3 /*
4  *      uss720.c  --  USS720 USB Parport Cable.
5  *
6  *      Copyright (C) 1999
7  *          Thomas Sailer (sailer@ife.ee.ethz.ch)
8  *
9  *      This program is free software; you can redistribute it and/or modify
10  *      it under the terms of the GNU General Public License as published by
11  *      the Free Software Foundation; either version 2 of the License, or
12  *      (at your option) any later version.
13  *
14  *      This program is distributed in the hope that it will be useful,
15  *      but WITHOUT ANY WARRANTY; without even the implied warranty of
16  *      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17  *      GNU General Public License for more details.
18  *
19  *      You should have received a copy of the GNU General Public License
20  *      along with this program; if not, write to the Free Software
21  *      Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
22  *
23  *  Based on parport_pc.c
24  *
25  *  History:
26  *   0.1  04.08.99  Created
27  *   0.2  07.08.99  Some fixes mainly suggested by Tim Waugh
28  *                  Interrupt handling currently disabled because
29  *                  usb_request_irq crashes somewhere within ohci.c
30  *                  for no apparent reason (that is for me, anyway)
31  *                  ECP currently untested
32  *   0.3  10.08.99  fixing merge errors
33  *   0.4  13.08.99  Added Vendor/Product ID of Brad Hard's cable
34  *   0.5  20.09.99  usb_control_msg wrapper used
35  *        Nov01.00  usb_device_table support by Adam J. Richter
36  *        08.04.01  Identify version on module load.  gb
37  *
38  */
39
40 /*****************************************************************************/
41
42 #include <linux/module.h>
43 #include <linux/socket.h>
44 #include <linux/parport.h>
45 #include <linux/init.h>
46 #include <linux/usb.h>
47 #include <linux/delay.h>
48
49 /*
50  * Version Information
51  */
52 #define DRIVER_VERSION "v0.5"
53 #define DRIVER_AUTHOR "Thomas M. Sailer, sailer@ife.ee.ethz.ch"
54 #define DRIVER_DESC "USB Parport Cable driver for Cables using the Lucent Technologies USS720 Chip"
55
56 /* --------------------------------------------------------------------- */
57
58 struct parport_uss720_private {
59         struct usb_device *usbdev;
60         void *irqhandle;
61         unsigned int irqpipe;
62         unsigned char reg[7];  /* USB registers */
63 };
64
65 /* --------------------------------------------------------------------- */
66
67 static int get_1284_register(struct parport *pp, unsigned char reg, unsigned char *val)
68 {
69         struct parport_uss720_private *priv = pp->private_data;
70         struct usb_device *usbdev = priv->usbdev;
71         static const unsigned char regindex[9] = {
72                 4, 0, 1, 5, 5, 0, 2, 3, 6
73         };
74         int ret;
75
76         if (!usbdev)
77                 return -1;
78         ret = usb_control_msg(usbdev, usb_rcvctrlpipe(usbdev,0), 3, 0xc0, ((unsigned int)reg) << 8, 0, priv->reg, 7, 1000);
79         if (ret != 7) {
80                 printk(KERN_DEBUG "uss720: get_1284_register(%d) failed, status 0x%x expected 7\n",
81                        (unsigned int)reg, ret);
82                 ret = -1;
83         } else {
84 #if 0
85                 printk(KERN_DEBUG "uss720: get_1284_register(%d) return %02x %02x %02x %02x %02x %02x %02x\n",
86                        (unsigned int)reg, (unsigned int)priv->reg[0], (unsigned int)priv->reg[1],
87                        (unsigned int)priv->reg[2], (unsigned int)priv->reg[3], (unsigned int)priv->reg[4],
88                        (unsigned int)priv->reg[5], (unsigned int)priv->reg[6]);
89 #endif
90                 /* if nAck interrupts are enabled and we have an interrupt, call the interrupt procedure */
91                 if (priv->reg[2] & priv->reg[1] & 0x10)
92                         parport_generic_irq(0, pp, NULL);
93                 ret = 0;
94         }
95         if (val)
96                 *val = priv->reg[(reg >= 9) ? 0 : regindex[reg]];
97         return ret;
98 }
99
100 static int set_1284_register(struct parport *pp, unsigned char reg, unsigned char val)
101 {
102         struct parport_uss720_private *priv = pp->private_data;
103         struct usb_device *usbdev = priv->usbdev;
104         int ret;
105
106         if (!usbdev)
107                 return -1;
108         ret = usb_control_msg(usbdev, usb_sndctrlpipe(usbdev,0), 4, 0x40, (((unsigned int)reg) << 8) | val, 0, NULL, 0, 1000);
109         if (ret) {
110                 printk(KERN_DEBUG "uss720: set_1284_register(%u,0x%02x) failed, status 0x%x\n", 
111                        (unsigned int)reg, (unsigned int)val, ret);
112         } else {
113 #if 0
114                 printk(KERN_DEBUG "uss720: set_1284_register(%u,0x%02x)\n", 
115                        (unsigned int)reg, (unsigned int)val);
116 #endif
117         }
118         return ret;
119 }
120
121 /* --------------------------------------------------------------------- */
122
123 /* ECR modes */
124 #define ECR_SPP 00
125 #define ECR_PS2 01
126 #define ECR_PPF 02
127 #define ECR_ECP 03
128 #define ECR_EPP 04
129
130 /* Safely change the mode bits in the ECR */
131 static int change_mode(struct parport *pp, int m)
132 {
133         struct parport_uss720_private *priv = pp->private_data;
134         int mode;
135
136         if (get_1284_register(pp, 6, NULL))
137                 return -EIO;
138         /* Bits <7:5> contain the mode. */
139         mode = (priv->reg[2] >> 5) & 0x7;
140         if (mode == m)
141                 return 0;
142         /* We have to go through mode 000 or 001 */
143         if (mode > ECR_PS2 && m > ECR_PS2)
144                 if (change_mode(pp, ECR_PS2))
145                         return -EIO;
146
147         if (m <= ECR_PS2 && !(priv->reg[1] & 0x20)) {
148                 /* This mode resets the FIFO, so we may
149                  * have to wait for it to drain first. */
150                 unsigned long expire = jiffies + pp->physport->cad->timeout;
151                 switch (mode) {
152                 case ECR_PPF: /* Parallel Port FIFO mode */
153                 case ECR_ECP: /* ECP Parallel Port mode */
154                         /* Poll slowly. */
155                         for (;;) {
156                                 if (get_1284_register(pp, 6, NULL))
157                                         return -EIO;
158                                 if (priv->reg[2] & 0x01)
159                                         break;
160                                 if (time_after_eq (jiffies, expire))
161                                         /* The FIFO is stuck. */
162                                         return -EBUSY;
163                                 msleep_interruptible(10);
164                                 if (signal_pending (current))
165                                         break;
166                         }
167                 }
168         }
169         /* Set the mode. */
170         if (set_1284_register(pp, 6, m << 5))
171                 return -EIO;
172         return 0;
173 }
174
175 /*
176  * Clear TIMEOUT BIT in EPP MODE
177  */
178 static int clear_epp_timeout(struct parport *pp)
179 {
180         unsigned char stat;
181
182         if (get_1284_register(pp, 1, &stat))
183                 return 1;
184         return stat & 1;
185 }
186
187 /*
188  * Access functions.
189  */
190 #if 0
191 static int uss720_irq(int usbstatus, void *buffer, int len, void *dev_id)
192 {
193         struct parport *pp = (struct parport *)dev_id;
194         struct parport_uss720_private *priv = pp->private_data; 
195
196         if (usbstatus != 0 || len < 4 || !buffer)
197                 return 1;
198         memcpy(priv->reg, buffer, 4);
199         /* if nAck interrupts are enabled and we have an interrupt, call the interrupt procedure */
200         if (priv->reg[2] & priv->reg[1] & 0x10)
201                 parport_generic_irq(0, pp, NULL);
202         return 1;
203 }
204 #endif
205
206 static void parport_uss720_write_data(struct parport *pp, unsigned char d)
207 {
208         set_1284_register(pp, 0, d);
209 }
210
211 static unsigned char parport_uss720_read_data(struct parport *pp)
212 {
213         unsigned char ret;
214
215         if (get_1284_register(pp, 0, &ret))
216                 return 0;
217         return ret;
218 }
219
220 static void parport_uss720_write_control(struct parport *pp, unsigned char d)
221 {
222         struct parport_uss720_private *priv = pp->private_data; 
223
224         d = (d & 0xf) | (priv->reg[1] & 0xf0);
225         if (set_1284_register(pp, 2, d))
226                 return;
227         priv->reg[1] = d;
228 }
229
230 static unsigned char parport_uss720_read_control(struct parport *pp)
231 {
232         struct parport_uss720_private *priv = pp->private_data; 
233         return priv->reg[1] & 0xf; /* Use soft copy */
234 }
235
236 static unsigned char parport_uss720_frob_control(struct parport *pp, unsigned char mask, unsigned char val)
237 {
238         struct parport_uss720_private *priv = pp->private_data; 
239         unsigned char d;
240
241         mask &= 0x0f;
242         val &= 0x0f;
243         d = (priv->reg[1] & (~mask)) ^ val;
244         if (set_1284_register(pp, 2, d))
245                 return 0;
246         priv->reg[1] = d;
247         return d & 0xf;
248 }
249
250 static unsigned char parport_uss720_read_status(struct parport *pp)
251 {
252         unsigned char ret;
253
254         if (get_1284_register(pp, 1, &ret))
255                 return 0;
256         return ret & 0xf8;
257 }
258
259 static void parport_uss720_disable_irq(struct parport *pp)
260 {
261         struct parport_uss720_private *priv = pp->private_data; 
262         unsigned char d;
263
264         d = priv->reg[1] & ~0x10;
265         if (set_1284_register(pp, 2, d))
266                 return;
267         priv->reg[1] = d;
268 }
269
270 static void parport_uss720_enable_irq(struct parport *pp)
271 {
272         struct parport_uss720_private *priv = pp->private_data; 
273         unsigned char d;
274
275         d = priv->reg[1] | 0x10;
276         if (set_1284_register(pp, 2, d))
277                 return;
278         priv->reg[1] = d;
279 }
280
281 static void parport_uss720_data_forward (struct parport *pp)
282 {
283         struct parport_uss720_private *priv = pp->private_data; 
284         unsigned char d;
285
286         d = priv->reg[1] & ~0x20;
287         if (set_1284_register(pp, 2, d))
288                 return;
289         priv->reg[1] = d;
290 }
291
292 static void parport_uss720_data_reverse (struct parport *pp)
293 {
294         struct parport_uss720_private *priv = pp->private_data; 
295         unsigned char d;
296
297         d = priv->reg[1] | 0x20;
298         if (set_1284_register(pp, 2, d))
299                 return;
300         priv->reg[1] = d;
301 }
302
303 static void parport_uss720_init_state(struct pardevice *dev, struct parport_state *s)
304 {
305         s->u.pc.ctr = 0xc | (dev->irq_func ? 0x10 : 0x0);
306         s->u.pc.ecr = 0x24;
307 }
308
309 static void parport_uss720_save_state(struct parport *pp, struct parport_state *s)
310 {
311         struct parport_uss720_private *priv = pp->private_data; 
312
313         if (get_1284_register(pp, 2, NULL))
314                 return;
315         s->u.pc.ctr = priv->reg[1];
316         s->u.pc.ecr = priv->reg[2];
317 }
318
319 static void parport_uss720_restore_state(struct parport *pp, struct parport_state *s)
320 {
321         set_1284_register(pp, 2, s->u.pc.ctr);
322         set_1284_register(pp, 6, s->u.pc.ecr);
323         get_1284_register(pp, 2, NULL);
324 }
325
326 static size_t parport_uss720_epp_read_data(struct parport *pp, void *buf, size_t length, int flags)
327 {
328         struct parport_uss720_private *priv = pp->private_data; 
329         size_t got = 0;
330
331         if (change_mode(pp, ECR_EPP))
332                 return 0;
333         for (; got < length; got++) {
334                 if (get_1284_register(pp, 4, (char *)buf))
335                         break;
336                 buf++;
337                 if (priv->reg[0] & 0x01) {
338                         clear_epp_timeout(pp);
339                         break;
340                 }
341         }
342         change_mode(pp, ECR_PS2);
343         return got;
344 }
345
346 static size_t parport_uss720_epp_write_data(struct parport *pp, const void *buf, size_t length, int flags)
347 {
348 #if 0
349         struct parport_uss720_private *priv = pp->private_data; 
350         size_t written = 0;
351
352         if (change_mode(pp, ECR_EPP))
353                 return 0;
354         for (; written < length; written++) {
355                 if (set_1284_register(pp, 4, (char *)buf))
356                         break;
357                 ((char*)buf)++;
358                 if (get_1284_register(pp, 1, NULL))
359                         break;
360                 if (priv->reg[0] & 0x01) {
361                         clear_epp_timeout(pp);
362                         break;
363                 }
364         }
365         change_mode(pp, ECR_PS2);
366         return written;
367 #else
368         struct parport_uss720_private *priv = pp->private_data;
369         struct usb_device *usbdev = priv->usbdev;
370         int rlen;
371         int i;
372
373         if (!usbdev)
374                 return 0;
375         if (change_mode(pp, ECR_EPP))
376                 return 0;
377         i = usb_bulk_msg(usbdev, usb_sndbulkpipe(usbdev, 1), (void *)buf, length, &rlen, 20000);
378         if (i)
379                 printk(KERN_ERR "uss720: sendbulk ep 1 buf %p len %Zu rlen %u\n", buf, length, rlen);
380         change_mode(pp, ECR_PS2);
381         return rlen;
382 #endif
383 }
384
385 static size_t parport_uss720_epp_read_addr(struct parport *pp, void *buf, size_t length, int flags)
386 {
387         struct parport_uss720_private *priv = pp->private_data; 
388         size_t got = 0;
389
390         if (change_mode(pp, ECR_EPP))
391                 return 0;
392         for (; got < length; got++) {
393                 if (get_1284_register(pp, 3, (char *)buf))
394                         break;
395                 buf++;
396                 if (priv->reg[0] & 0x01) {
397                         clear_epp_timeout(pp);
398                         break;
399                 }
400         }
401         change_mode(pp, ECR_PS2);
402         return got;
403 }
404
405 static size_t parport_uss720_epp_write_addr(struct parport *pp, const void *buf, size_t length, int flags)
406 {
407         struct parport_uss720_private *priv = pp->private_data; 
408         size_t written = 0;
409
410         if (change_mode(pp, ECR_EPP))
411                 return 0;
412         for (; written < length; written++) {
413                 if (set_1284_register(pp, 3, *(char *)buf))
414                         break;
415                 buf++;
416                 if (get_1284_register(pp, 1, NULL))
417                         break;
418                 if (priv->reg[0] & 0x01) {
419                         clear_epp_timeout(pp);
420                         break;
421                 }
422         }
423         change_mode(pp, ECR_PS2);
424         return written;
425 }
426
427 static size_t parport_uss720_ecp_write_data(struct parport *pp, const void *buffer, size_t len, int flags)
428 {
429         struct parport_uss720_private *priv = pp->private_data;
430         struct usb_device *usbdev = priv->usbdev;
431         int rlen;
432         int i;
433
434         if (!usbdev)
435                 return 0;
436         if (change_mode(pp, ECR_ECP))
437                 return 0;
438         i = usb_bulk_msg(usbdev, usb_sndbulkpipe(usbdev, 1), (void *)buffer, len, &rlen, 20000);
439         if (i)
440                 printk(KERN_ERR "uss720: sendbulk ep 1 buf %p len %Zu rlen %u\n", buffer, len, rlen);
441         change_mode(pp, ECR_PS2);
442         return rlen;
443 }
444
445 static size_t parport_uss720_ecp_read_data(struct parport *pp, void *buffer, size_t len, int flags)
446 {
447         struct parport_uss720_private *priv = pp->private_data;
448         struct usb_device *usbdev = priv->usbdev;
449         int rlen;
450         int i;
451
452         if (!usbdev)
453                 return 0;
454         if (change_mode(pp, ECR_ECP))
455                 return 0;
456         i = usb_bulk_msg(usbdev, usb_rcvbulkpipe(usbdev, 2), buffer, len, &rlen, 20000);
457         if (i)
458                 printk(KERN_ERR "uss720: recvbulk ep 2 buf %p len %Zu rlen %u\n", buffer, len, rlen);
459         change_mode(pp, ECR_PS2);
460         return rlen;
461 }
462
463 static size_t parport_uss720_ecp_write_addr(struct parport *pp, const void *buffer, size_t len, int flags)
464 {
465         size_t written = 0;
466
467         if (change_mode(pp, ECR_ECP))
468                 return 0;
469         for (; written < len; written++) {
470                 if (set_1284_register(pp, 5, *(char *)buffer))
471                         break;
472                 buffer++;
473         }
474         change_mode(pp, ECR_PS2);
475         return written;
476 }
477
478 static size_t parport_uss720_write_compat(struct parport *pp, const void *buffer, size_t len, int flags)
479 {
480         struct parport_uss720_private *priv = pp->private_data;
481         struct usb_device *usbdev = priv->usbdev;
482         int rlen;
483         int i;
484
485         if (!usbdev)
486                 return 0;
487         if (change_mode(pp, ECR_PPF))
488                 return 0;
489         i = usb_bulk_msg(usbdev, usb_sndbulkpipe(usbdev, 1), (void *)buffer, len, &rlen, 20000);
490         if (i)
491                 printk(KERN_ERR "uss720: sendbulk ep 1 buf %p len %Zu rlen %u\n", buffer, len, rlen);
492         change_mode(pp, ECR_PS2);
493         return rlen;
494 }
495
496 /* --------------------------------------------------------------------- */
497
498 static struct parport_operations parport_uss720_ops = 
499 {
500         .owner =                THIS_MODULE,
501         .write_data =           parport_uss720_write_data,
502         .read_data =            parport_uss720_read_data,
503
504         .write_control =        parport_uss720_write_control,
505         .read_control =         parport_uss720_read_control,
506         .frob_control =         parport_uss720_frob_control,
507
508         .read_status =          parport_uss720_read_status,
509
510         .enable_irq =           parport_uss720_enable_irq,
511         .disable_irq =          parport_uss720_disable_irq,
512
513         .data_forward =         parport_uss720_data_forward,
514         .data_reverse =         parport_uss720_data_reverse,
515
516         .init_state =           parport_uss720_init_state,
517         .save_state =           parport_uss720_save_state,
518         .restore_state =        parport_uss720_restore_state,
519
520         .epp_write_data =       parport_uss720_epp_write_data,
521         .epp_read_data =        parport_uss720_epp_read_data,
522         .epp_write_addr =       parport_uss720_epp_write_addr,
523         .epp_read_addr =        parport_uss720_epp_read_addr,
524
525         .ecp_write_data =       parport_uss720_ecp_write_data,
526         .ecp_read_data =        parport_uss720_ecp_read_data,
527         .ecp_write_addr =       parport_uss720_ecp_write_addr,
528
529         .compat_write_data =    parport_uss720_write_compat,
530         .nibble_read_data =     parport_ieee1284_read_nibble,
531         .byte_read_data =       parport_ieee1284_read_byte,
532 };
533
534 /* --------------------------------------------------------------------- */
535
536 static int uss720_probe(struct usb_interface *intf,
537                         const struct usb_device_id *id)
538 {
539         struct usb_device *usbdev = interface_to_usbdev(intf);
540         struct usb_host_interface *interface;
541         struct usb_host_endpoint *endpoint;
542         struct parport_uss720_private *priv;
543         struct parport *pp;
544         int i;
545
546         printk(KERN_DEBUG "uss720: probe: vendor id 0x%x, device id 0x%x\n",
547                le16_to_cpu(usbdev->descriptor.idVendor),
548                le16_to_cpu(usbdev->descriptor.idProduct));
549
550         /* our known interfaces have 3 alternate settings */
551         if (intf->num_altsetting != 3)
552                 return -ENODEV;
553
554         i = usb_set_interface(usbdev, intf->altsetting->desc.bInterfaceNumber, 2);
555         printk(KERN_DEBUG "uss720: set inteface result %d\n", i);
556
557         interface = intf->cur_altsetting;
558
559         /*
560          * Allocate parport interface 
561          */
562         printk(KERN_INFO "uss720: (C) 1999 by Thomas Sailer, <sailer@ife.ee.ethz.ch>\n");
563
564         if (!(priv = kmalloc(sizeof(struct parport_uss720_private), GFP_KERNEL)))
565                 return -ENOMEM;
566         if (!(pp = parport_register_port(0, PARPORT_IRQ_NONE, PARPORT_DMA_NONE, &parport_uss720_ops))) {
567                 printk(KERN_WARNING "usb-uss720: could not register parport\n");
568                 goto probe_abort;
569         }
570
571         pp->private_data = priv;
572         priv->usbdev = usbdev;
573         pp->modes = PARPORT_MODE_PCSPP | PARPORT_MODE_TRISTATE | PARPORT_MODE_EPP | PARPORT_MODE_ECP | PARPORT_MODE_COMPAT;
574
575         /* set the USS720 control register to manual mode, no ECP compression, enable all ints */
576         set_1284_register(pp, 7, 0x00);
577         set_1284_register(pp, 6, 0x30);  /* PS/2 mode */
578         set_1284_register(pp, 2, 0x0c);
579         /* debugging */
580         get_1284_register(pp, 0, NULL);
581         printk("uss720: reg: %02x %02x %02x %02x %02x %02x %02x\n",
582                priv->reg[0], priv->reg[1], priv->reg[2], priv->reg[3], priv->reg[4], priv->reg[5], priv->reg[6]);
583
584         endpoint = &interface->endpoint[2];
585         printk(KERN_DEBUG "uss720: epaddr %d interval %d\n", endpoint->desc.bEndpointAddress, endpoint->desc.bInterval);
586 #if 0
587         priv->irqpipe = usb_rcvctrlpipe(usbdev, endpoint->bEndpointAddress);
588         i = usb_request_irq(usbdev, priv->irqpipe,
589                                   uss720_irq, endpoint->bInterval,
590                                   pp, &priv->irqhandle);
591         if (i) {
592                 printk (KERN_WARNING "usb-uss720: usb_request_irq failed (0x%x)\n", i);
593                 goto probe_abort_port;
594         }
595 #endif
596         parport_announce_port(pp);
597
598         usb_set_intfdata (intf, pp);
599         return 0;
600
601 #if 0
602 probe_abort_port:
603         parport_put_port(pp);
604 #endif
605 probe_abort:
606         kfree(priv);
607         return -ENODEV;
608 }
609
610 static void uss720_disconnect(struct usb_interface *intf)
611 {
612         struct parport *pp = usb_get_intfdata (intf);
613         struct parport_uss720_private *priv;
614
615         usb_set_intfdata (intf, NULL);
616         if (pp) {
617                 priv = pp->private_data;
618                 parport_remove_port(pp);
619 #if 0
620                 usb_release_irq(usbdev, priv->irqhandle, priv->irqpipe);
621 #endif
622                 priv->usbdev = NULL;
623                 parport_put_port(pp);
624                 kfree(priv);
625         }
626 }
627
628 /* table of cables that work through this driver */
629 static struct usb_device_id uss720_table [] = {
630         { USB_DEVICE(0x047e, 0x1001) },
631         { USB_DEVICE(0x0557, 0x2001) },
632         { USB_DEVICE(0x0729, 0x1284) },
633         { USB_DEVICE(0x1293, 0x0002) },
634         { }                                             /* Terminating entry */
635 };
636
637 MODULE_DEVICE_TABLE (usb, uss720_table);
638
639
640 static struct usb_driver uss720_driver = {
641         .owner =        THIS_MODULE,
642         .name =         "uss720",
643         .probe =        uss720_probe,
644         .disconnect =   uss720_disconnect,
645         .id_table =     uss720_table,
646 };
647
648 /* --------------------------------------------------------------------- */
649
650 MODULE_AUTHOR( DRIVER_AUTHOR );
651 MODULE_DESCRIPTION( DRIVER_DESC );
652 MODULE_LICENSE("GPL");
653
654 static int __init uss720_init(void)
655 {
656         int retval;
657         retval = usb_register(&uss720_driver);
658         if (retval)
659                 goto out;
660
661         info(DRIVER_VERSION ":" DRIVER_DESC);
662 out:
663         return retval;
664 }
665
666 static void __exit uss720_cleanup(void)
667 {
668         usb_deregister(&uss720_driver);
669 }
670
671 module_init(uss720_init);
672 module_exit(uss720_cleanup);
673
674 /* --------------------------------------------------------------------- */