avf: add support for intel X722 NICs
[vpp.git] / src / plugins / avf / device.c
1 /*
2  *------------------------------------------------------------------
3  * Copyright (c) 2018 Cisco and/or its affiliates.
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *------------------------------------------------------------------
16  */
17
18 #include <vlib/vlib.h>
19 #include <vlib/unix/unix.h>
20 #include <vlib/pci/pci.h>
21 #include <vnet/ethernet/ethernet.h>
22
23 #include <avf/avf.h>
24
25 #define AVF_MBOX_LEN 64
26 #define AVF_MBOX_BUF_SZ 512
27 #define AVF_RXQ_SZ 512
28 #define AVF_TXQ_SZ 512
29 #define AVF_ITR_INT 8160
30
31 #define PCI_VENDOR_ID_INTEL                     0x8086
32 #define PCI_DEVICE_ID_INTEL_AVF                 0x1889
33 #define PCI_DEVICE_ID_INTEL_X710_VF             0x154c
34 #define PCI_DEVICE_ID_INTEL_X722_VF             0x37cd
35
36 avf_main_t avf_main;
37
38 static pci_device_id_t avf_pci_device_ids[] = {
39   {.vendor_id = PCI_VENDOR_ID_INTEL,.device_id = PCI_DEVICE_ID_INTEL_AVF},
40   {.vendor_id = PCI_VENDOR_ID_INTEL,.device_id = PCI_DEVICE_ID_INTEL_X710_VF},
41   {.vendor_id = PCI_VENDOR_ID_INTEL,.device_id = PCI_DEVICE_ID_INTEL_X722_VF},
42   {0},
43 };
44
45 static inline void
46 avf_irq_0_disable (avf_device_t * ad)
47 {
48   u32 dyn_ctl0 = 0, icr0_ena = 0;
49
50   dyn_ctl0 |= (3 << 3);         /* 11b = No ITR update */
51
52   avf_reg_write (ad, AVFINT_ICR0_ENA1, icr0_ena);
53   avf_reg_write (ad, AVFINT_DYN_CTL0, dyn_ctl0);
54   avf_reg_flush (ad);
55 }
56
57 static inline void
58 avf_irq_0_enable (avf_device_t * ad)
59 {
60   u32 dyn_ctl0 = 0, icr0_ena = 0;
61
62   icr0_ena |= (1 << 30);        /* [30] Admin Queue Enable */
63
64   dyn_ctl0 |= (1 << 0);         /* [0] Interrupt Enable */
65   dyn_ctl0 |= (1 << 1);         /* [1] Clear PBA */
66   //dyn_ctl0 |= (3 << 3);               /* [4:3] ITR Index, 11b = No ITR update */
67   dyn_ctl0 |= ((AVF_ITR_INT / 2) << 5); /* [16:5] ITR Interval in 2us steps */
68
69   avf_irq_0_disable (ad);
70   avf_reg_write (ad, AVFINT_ICR0_ENA1, icr0_ena);
71   avf_reg_write (ad, AVFINT_DYN_CTL0, dyn_ctl0);
72   avf_reg_flush (ad);
73 }
74
75 static inline void
76 avf_irq_n_disable (avf_device_t * ad, u8 line)
77 {
78   u32 dyn_ctln = 0;
79
80   avf_reg_write (ad, AVFINT_DYN_CTLN (line), dyn_ctln);
81   avf_reg_flush (ad);
82 }
83
84 static inline void
85 avf_irq_n_enable (avf_device_t * ad, u8 line)
86 {
87   u32 dyn_ctln = 0;
88
89   dyn_ctln |= (1 << 0);         /* [0] Interrupt Enable */
90   dyn_ctln |= (1 << 1);         /* [1] Clear PBA */
91   dyn_ctln |= ((AVF_ITR_INT / 2) << 5); /* [16:5] ITR Interval in 2us steps */
92
93   avf_irq_n_disable (ad, line);
94   avf_reg_write (ad, AVFINT_DYN_CTLN (line), dyn_ctln);
95   avf_reg_flush (ad);
96 }
97
98
99 clib_error_t *
100 avf_aq_desc_enq (vlib_main_t * vm, avf_device_t * ad, avf_aq_desc_t * dt,
101                  void *data, int len)
102 {
103   avf_main_t *am = &avf_main;
104   clib_error_t *err = 0;
105   avf_aq_desc_t *d, dc;
106   int n_retry = 5;
107
108   d = &ad->atq[ad->atq_next_slot];
109   clib_memcpy (d, dt, sizeof (avf_aq_desc_t));
110   d->flags |= AVF_AQ_F_RD | AVF_AQ_F_SI;
111   if (len)
112     d->datalen = len;
113   if (len)
114     {
115       u64 pa;
116       pa = ad->atq_bufs_pa + ad->atq_next_slot * AVF_MBOX_BUF_SZ;
117       d->addr_hi = (u32) (pa >> 32);
118       d->addr_lo = (u32) pa;
119       clib_memcpy (ad->atq_bufs + ad->atq_next_slot * AVF_MBOX_BUF_SZ, data,
120                    len);
121       d->flags |= AVF_AQ_F_BUF;
122     }
123
124   if (ad->flags & AVF_DEVICE_F_ELOG)
125     clib_memcpy (&dc, d, sizeof (avf_aq_desc_t));
126
127   CLIB_MEMORY_BARRIER ();
128   vlib_log_debug (am->log_class, "%U", format_hexdump, data, len);
129   ad->atq_next_slot = (ad->atq_next_slot + 1) % AVF_MBOX_LEN;
130   avf_reg_write (ad, AVF_ATQT, ad->atq_next_slot);
131   avf_reg_flush (ad);
132
133 retry:
134   vlib_process_suspend (vm, 10e-6);
135
136   if (((d->flags & AVF_AQ_F_DD) == 0) || ((d->flags & AVF_AQ_F_CMP) == 0))
137     {
138       if (--n_retry == 0)
139         {
140           err = clib_error_return (0, "adminq enqueue timeout [opcode 0x%x]",
141                                    d->opcode);
142           goto done;
143         }
144       goto retry;
145     }
146
147   clib_memcpy (dt, d, sizeof (avf_aq_desc_t));
148   if (d->flags & AVF_AQ_F_ERR)
149     return clib_error_return (0, "adminq enqueue error [opcode 0x%x, retval "
150                               "%d]", d->opcode, d->retval);
151
152 done:
153   if (ad->flags & AVF_DEVICE_F_ELOG)
154     {
155       /* *INDENT-OFF* */
156       ELOG_TYPE_DECLARE (el) =
157         {
158           .format = "avf[%d] aq enq: s_flags 0x%x r_flags 0x%x opcode 0x%x "
159             "datalen %d retval %d",
160           .format_args = "i4i2i2i2i2i2",
161         };
162       struct
163         {
164           u32 dev_instance;
165           u16 s_flags;
166           u16 r_flags;
167           u16 opcode;
168           u16 datalen;
169           u16 retval;
170         } *ed;
171       ed = ELOG_DATA (&vm->elog_main, el);
172       ed->dev_instance = ad->dev_instance;
173       ed->s_flags = dc.flags;
174       ed->r_flags = d->flags;
175       ed->opcode = dc.opcode;
176       ed->datalen = dc.datalen;
177       ed->retval = d->retval;
178       /* *INDENT-ON* */
179     }
180
181   return err;
182 }
183
184 clib_error_t *
185 avf_cmd_rx_ctl_reg_write (vlib_main_t * vm, avf_device_t * ad, u32 reg,
186                           u32 val)
187 {
188   clib_error_t *err;
189   avf_aq_desc_t d = {.opcode = 0x207,.param1 = reg,.param3 = val };
190   err = avf_aq_desc_enq (vm, ad, &d, 0, 0);
191
192   if (ad->flags & AVF_DEVICE_F_ELOG)
193     {
194       /* *INDENT-OFF* */
195       ELOG_TYPE_DECLARE (el) =
196         {
197           .format = "avf[%d] rx ctl reg write: reg 0x%x val 0x%x ",
198           .format_args = "i4i4i4",
199         };
200       struct
201         {
202           u32 dev_instance;
203           u32 reg;
204           u32 val;
205         } *ed;
206       ed = ELOG_DATA (&vm->elog_main, el);
207       ed->dev_instance = ad->dev_instance;
208       ed->reg = reg;
209       ed->val = val;
210       /* *INDENT-ON* */
211     }
212   return err;
213 }
214
215 clib_error_t *
216 avf_rxq_init (vlib_main_t * vm, avf_device_t * ad, u16 qid)
217 {
218   avf_main_t *am = &avf_main;
219   avf_rxq_t *rxq;
220   clib_error_t *error = 0;
221   u32 n_alloc, i;
222
223   vec_validate_aligned (ad->rxqs, qid, CLIB_CACHE_LINE_BYTES);
224   rxq = vec_elt_at_index (ad->rxqs, qid);
225   rxq->size = AVF_RXQ_SZ;
226   rxq->next = 0;
227   rxq->descs = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
228                                            rxq->size * sizeof (avf_rx_desc_t),
229                                            2 * CLIB_CACHE_LINE_BYTES);
230   memset (rxq->descs, 0, rxq->size * sizeof (avf_rx_desc_t));
231   vec_validate_aligned (rxq->bufs, rxq->size, CLIB_CACHE_LINE_BYTES);
232   rxq->qrx_tail = ad->bar0 + AVF_QRX_TAIL (qid);
233
234   n_alloc = vlib_buffer_alloc (vm, rxq->bufs, rxq->size - 8);
235
236   if (n_alloc == 0)
237     return clib_error_return (0, "buffer allocation error");
238
239   rxq->n_bufs = n_alloc;
240   avf_rx_desc_t *d = rxq->descs;
241   for (i = 0; i < n_alloc; i++)
242     {
243       if (ad->flags & AVF_DEVICE_F_IOVA)
244         {
245           vlib_buffer_t *b = vlib_get_buffer (vm, rxq->bufs[i]);
246           d->qword[0] = pointer_to_uword (b->data);
247         }
248       else
249         d->qword[0] =
250           vlib_get_buffer_data_physical_address (vm, rxq->bufs[i]);
251       d++;
252     }
253   return 0;
254 }
255
256 clib_error_t *
257 avf_txq_init (vlib_main_t * vm, avf_device_t * ad, u16 qid)
258 {
259   avf_main_t *am = &avf_main;
260   avf_txq_t *txq;
261   clib_error_t *error = 0;
262
263   if (qid >= ad->num_queue_pairs)
264     {
265       qid = qid % ad->num_queue_pairs;
266       txq = vec_elt_at_index (ad->txqs, qid);
267       if (txq->lock == 0)
268         clib_spinlock_init (&txq->lock);
269       ad->flags |= AVF_DEVICE_F_SHARED_TXQ_LOCK;
270       return 0;
271     }
272
273   vec_validate_aligned (ad->txqs, qid, CLIB_CACHE_LINE_BYTES);
274   txq = vec_elt_at_index (ad->txqs, qid);
275   txq->size = AVF_TXQ_SZ;
276   txq->next = 0;
277   txq->descs = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
278                                            txq->size * sizeof (avf_tx_desc_t),
279                                            2 * CLIB_CACHE_LINE_BYTES);
280   vec_validate_aligned (txq->bufs, txq->size, CLIB_CACHE_LINE_BYTES);
281   txq->qtx_tail = ad->bar0 + AVF_QTX_TAIL (qid);
282   return 0;
283 }
284
285 typedef struct
286 {
287   u16 vsi_id;
288   u16 flags;
289 } virtchnl_promisc_info_t;
290
291 void
292 avf_arq_slot_init (avf_device_t * ad, u16 slot)
293 {
294   avf_aq_desc_t *d;
295   u64 pa = ad->arq_bufs_pa + slot * AVF_MBOX_BUF_SZ;
296   d = &ad->arq[slot];
297   memset (d, 0, sizeof (avf_aq_desc_t));
298   d->flags = AVF_AQ_F_BUF;
299   d->datalen = AVF_MBOX_BUF_SZ;
300   d->addr_hi = (u32) (pa >> 32);
301   d->addr_lo = (u32) pa;
302 }
303
304 static inline uword
305 avf_dma_addr (vlib_main_t * vm, avf_device_t * ad, void *p)
306 {
307   avf_main_t *am = &avf_main;
308   return (ad->flags & AVF_DEVICE_F_IOVA) ?
309     pointer_to_uword (p) :
310     vlib_physmem_virtual_to_physical (vm, am->physmem_region, p);
311 }
312
313 static void
314 avf_adminq_init (vlib_main_t * vm, avf_device_t * ad)
315 {
316   u64 pa;
317   int i;
318
319   /* VF MailBox Transmit */
320   memset (ad->atq, 0, sizeof (avf_aq_desc_t) * AVF_MBOX_LEN);
321   ad->atq_bufs_pa = avf_dma_addr (vm, ad, ad->atq_bufs);
322
323   pa = avf_dma_addr (vm, ad, ad->atq);
324   avf_reg_write (ad, AVF_ATQT, 0);      /* Tail */
325   avf_reg_write (ad, AVF_ATQH, 0);      /* Head */
326   avf_reg_write (ad, AVF_ATQLEN, AVF_MBOX_LEN | (1 << 31));     /* len & ena */
327   avf_reg_write (ad, AVF_ATQBAL, (u32) pa);     /* Base Address Low */
328   avf_reg_write (ad, AVF_ATQBAH, (u32) (pa >> 32));     /* Base Address High */
329
330   /* VF MailBox Receive */
331   memset (ad->arq, 0, sizeof (avf_aq_desc_t) * AVF_MBOX_LEN);
332   ad->arq_bufs_pa = avf_dma_addr (vm, ad, ad->arq_bufs);
333
334   for (i = 0; i < AVF_MBOX_LEN; i++)
335     avf_arq_slot_init (ad, i);
336
337   pa = avf_dma_addr (vm, ad, ad->arq);
338
339   avf_reg_write (ad, AVF_ARQH, 0);      /* Head */
340   avf_reg_write (ad, AVF_ARQT, 0);      /* Head */
341   avf_reg_write (ad, AVF_ARQLEN, AVF_MBOX_LEN | (1 << 31));     /* len & ena */
342   avf_reg_write (ad, AVF_ARQBAL, (u32) pa);     /* Base Address Low */
343   avf_reg_write (ad, AVF_ARQBAH, (u32) (pa >> 32));     /* Base Address High */
344   avf_reg_write (ad, AVF_ARQT, AVF_MBOX_LEN - 1);       /* Tail */
345
346   ad->atq_next_slot = 0;
347   ad->arq_next_slot = 0;
348 }
349
350 clib_error_t *
351 avf_send_to_pf (vlib_main_t * vm, avf_device_t * ad, virtchnl_ops_t op,
352                 void *in, int in_len, void *out, int out_len)
353 {
354   clib_error_t *err;
355   avf_aq_desc_t *d, dt = {.opcode = 0x801,.v_opcode = op };
356   u32 head;
357   int n_retry = 5;
358
359
360   /* supppres interrupt in the next adminq receive slot
361      as we are going to wait for response
362      we only need interrupts when event is received */
363   d = &ad->arq[ad->arq_next_slot];
364   d->flags |= AVF_AQ_F_SI;
365
366   if ((err = avf_aq_desc_enq (vm, ad, &dt, in, in_len)))
367     return err;
368
369 retry:
370   head = avf_get_u32 (ad->bar0, AVF_ARQH);
371
372   if (ad->arq_next_slot == head)
373     {
374       if (--n_retry == 0)
375         return clib_error_return (0, "timeout");
376       vlib_process_suspend (vm, 10e-3);
377       goto retry;
378     }
379
380   d = &ad->arq[ad->arq_next_slot];
381
382   if (d->v_opcode == VIRTCHNL_OP_EVENT)
383     {
384       void *buf = ad->arq_bufs + ad->arq_next_slot * AVF_MBOX_BUF_SZ;
385       virtchnl_pf_event_t *e;
386
387       if ((d->datalen != sizeof (virtchnl_pf_event_t)) ||
388           ((d->flags & AVF_AQ_F_BUF) == 0))
389         return clib_error_return (0, "event message error");
390
391       vec_add2 (ad->events, e, 1);
392       clib_memcpy (e, buf, sizeof (virtchnl_pf_event_t));
393       avf_arq_slot_init (ad, ad->arq_next_slot);
394       ad->arq_next_slot++;
395       n_retry = 5;
396       goto retry;
397     }
398
399   if (d->v_opcode != op)
400     {
401       err = clib_error_return (0, "unexpected message receiver [v_opcode = %u"
402                                "expected %u]", d->v_opcode, op);
403       goto done;
404     }
405
406   if (d->v_retval)
407     {
408       err = clib_error_return (0, "error [v_opcode = %u, v_retval %d]",
409                                d->v_opcode, d->v_retval);
410       goto done;
411     }
412
413   if (d->flags & AVF_AQ_F_BUF)
414     {
415       void *buf = ad->arq_bufs + ad->arq_next_slot * AVF_MBOX_BUF_SZ;
416       clib_memcpy (out, buf, out_len);
417     }
418
419   avf_arq_slot_init (ad, ad->arq_next_slot);
420   avf_reg_write (ad, AVF_ARQT, ad->arq_next_slot);
421   avf_reg_flush (ad);
422   ad->arq_next_slot = (ad->arq_next_slot + 1) % AVF_MBOX_LEN;
423
424 done:
425
426   if (ad->flags & AVF_DEVICE_F_ELOG)
427     {
428       /* *INDENT-OFF* */
429       ELOG_TYPE_DECLARE (el) =
430         {
431           .format = "avf[%d] send to pf: v_opcode %s (%d) v_retval 0x%x",
432           .format_args = "i4t4i4i4",
433           .n_enum_strings = VIRTCHNL_N_OPS,
434           .enum_strings = {
435 #define _(v, n) [v] = #n,
436               foreach_virtchnl_op
437 #undef _
438           },
439         };
440       struct
441         {
442           u32 dev_instance;
443           u32 v_opcode;
444           u32 v_opcode_val;
445           u32 v_retval;
446         } *ed;
447       ed = ELOG_DATA (&vm->elog_main, el);
448       ed->dev_instance = ad->dev_instance;
449       ed->v_opcode = op;
450       ed->v_opcode_val = op;
451       ed->v_retval = d->v_retval;
452       /* *INDENT-ON* */
453     }
454   return err;
455 }
456
457 clib_error_t *
458 avf_op_version (vlib_main_t * vm, avf_device_t * ad,
459                 virtchnl_version_info_t * ver)
460 {
461   clib_error_t *err = 0;
462   virtchnl_version_info_t myver = {
463     .major = VIRTCHNL_VERSION_MAJOR,
464     .minor = VIRTCHNL_VERSION_MINOR,
465   };
466
467   err = avf_send_to_pf (vm, ad, VIRTCHNL_OP_VERSION, &myver,
468                         sizeof (virtchnl_version_info_t), ver,
469                         sizeof (virtchnl_version_info_t));
470
471   if (err)
472     return err;
473
474   return err;
475 }
476
477 clib_error_t *
478 avf_op_get_vf_resources (vlib_main_t * vm, avf_device_t * ad,
479                          virtchnl_vf_resource_t * res)
480 {
481   clib_error_t *err = 0;
482   u32 bitmap = (VIRTCHNL_VF_OFFLOAD_L2 | VIRTCHNL_VF_OFFLOAD_RSS_AQ |
483                 VIRTCHNL_VF_OFFLOAD_RSS_REG | VIRTCHNL_VF_OFFLOAD_WB_ON_ITR |
484                 VIRTCHNL_VF_OFFLOAD_VLAN | VIRTCHNL_VF_OFFLOAD_RX_POLLING);
485
486   err = avf_send_to_pf (vm, ad, VIRTCHNL_OP_GET_VF_RESOURCES, &bitmap,
487                         sizeof (u32), res, sizeof (virtchnl_vf_resource_t));
488
489   if (err)
490     return err;
491
492   return err;
493 }
494
495 clib_error_t *
496 avf_op_disable_vlan_stripping (vlib_main_t * vm, avf_device_t * ad)
497 {
498   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_DISABLE_VLAN_STRIPPING, 0, 0, 0,
499                          0);
500 }
501
502 clib_error_t *
503 avf_config_promisc_mode (vlib_main_t * vm, avf_device_t * ad)
504 {
505   virtchnl_promisc_info_t pi = { 0 };
506
507   pi.vsi_id = ad->vsi_id;
508   pi.flags = 1;
509   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_CONFIG_PROMISCUOUS_MODE, &pi,
510                          sizeof (virtchnl_promisc_info_t), 0, 0);
511 }
512
513
514 clib_error_t *
515 avf_op_config_vsi_queues (vlib_main_t * vm, avf_device_t * ad)
516 {
517   int i;
518   int n_qp = clib_max (vec_len (ad->rxqs), vec_len (ad->txqs));
519   int msg_len = sizeof (virtchnl_vsi_queue_config_info_t) + n_qp *
520     sizeof (virtchnl_queue_pair_info_t);
521   u8 msg[msg_len];
522   virtchnl_vsi_queue_config_info_t *ci;
523
524   memset (msg, 0, msg_len);
525   ci = (virtchnl_vsi_queue_config_info_t *) msg;
526   ci->vsi_id = ad->vsi_id;
527   ci->num_queue_pairs = n_qp;
528
529   for (i = 0; i < n_qp; i++)
530     {
531       virtchnl_txq_info_t *txq = &ci->qpair[i].txq;
532       virtchnl_rxq_info_t *rxq = &ci->qpair[i].rxq;
533
534       rxq->vsi_id = ad->vsi_id;
535       rxq->queue_id = i;
536       rxq->max_pkt_size = 1518;
537       if (i < vec_len (ad->rxqs))
538         {
539           avf_rxq_t *q = vec_elt_at_index (ad->rxqs, i);
540           rxq->ring_len = q->size;
541           rxq->databuffer_size = VLIB_BUFFER_DEFAULT_FREE_LIST_BYTES;
542           rxq->dma_ring_addr = avf_dma_addr (vm, ad, q->descs);
543           avf_reg_write (ad, AVF_QRX_TAIL (i), q->size - 1);
544         }
545
546       avf_txq_t *q = vec_elt_at_index (ad->txqs, i);
547       txq->vsi_id = ad->vsi_id;
548       if (i < vec_len (ad->txqs))
549         {
550           txq->queue_id = i;
551           txq->ring_len = q->size;
552           txq->dma_ring_addr = avf_dma_addr (vm, ad, q->descs);
553         }
554     }
555
556   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_CONFIG_VSI_QUEUES, msg, msg_len,
557                          0, 0);
558 }
559
560 clib_error_t *
561 avf_op_config_irq_map (vlib_main_t * vm, avf_device_t * ad)
562 {
563   int count = 1;
564   int msg_len = sizeof (virtchnl_irq_map_info_t) +
565     count * sizeof (virtchnl_vector_map_t);
566   u8 msg[msg_len];
567   virtchnl_irq_map_info_t *imi;
568
569   memset (msg, 0, msg_len);
570   imi = (virtchnl_irq_map_info_t *) msg;
571   imi->num_vectors = count;
572
573   imi->vecmap[0].vector_id = 1;
574   imi->vecmap[0].vsi_id = ad->vsi_id;
575   imi->vecmap[0].rxq_map = 1;
576   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_CONFIG_IRQ_MAP, msg, msg_len, 0,
577                          0);
578 }
579
580 clib_error_t *
581 avf_op_add_eth_addr (vlib_main_t * vm, avf_device_t * ad, u8 count, u8 * macs)
582 {
583   int msg_len =
584     sizeof (virtchnl_ether_addr_list_t) +
585     count * sizeof (virtchnl_ether_addr_t);
586   u8 msg[msg_len];
587   virtchnl_ether_addr_list_t *al;
588   int i;
589
590   memset (msg, 0, msg_len);
591   al = (virtchnl_ether_addr_list_t *) msg;
592   al->vsi_id = ad->vsi_id;
593   al->num_elements = count;
594   for (i = 0; i < count; i++)
595     clib_memcpy (&al->list[i].addr, macs + i * 6, 6);
596   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_ADD_ETH_ADDR, msg, msg_len, 0,
597                          0);
598 }
599
600 clib_error_t *
601 avf_op_enable_queues (vlib_main_t * vm, avf_device_t * ad, u32 rx, u32 tx)
602 {
603   virtchnl_queue_select_t qs = { 0 };
604   qs.vsi_id = ad->vsi_id;
605   qs.rx_queues = rx;
606   qs.tx_queues = tx;
607   avf_rxq_t *rxq = vec_elt_at_index (ad->rxqs, 0);
608   avf_reg_write (ad, AVF_QRX_TAIL (0), rxq->n_bufs);
609   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_ENABLE_QUEUES, &qs,
610                          sizeof (virtchnl_queue_select_t), 0, 0);
611 }
612
613 clib_error_t *
614 avf_op_get_stats (vlib_main_t * vm, avf_device_t * ad,
615                   virtchnl_eth_stats_t * es)
616 {
617   virtchnl_queue_select_t qs = { 0 };
618   qs.vsi_id = ad->vsi_id;
619   return avf_send_to_pf (vm, ad, VIRTCHNL_OP_GET_STATS,
620                          &qs, sizeof (virtchnl_queue_select_t),
621                          es, sizeof (virtchnl_eth_stats_t));
622 }
623
624 clib_error_t *
625 avf_device_reset (vlib_main_t * vm, avf_device_t * ad)
626 {
627   avf_aq_desc_t d = { 0 };
628   clib_error_t *error;
629   u32 rstat;
630   int n_retry = 20;
631
632   d.opcode = 0x801;
633   d.v_opcode = VIRTCHNL_OP_RESET_VF;
634   if ((error = avf_aq_desc_enq (vm, ad, &d, 0, 0)))
635     return error;
636
637 retry:
638   vlib_process_suspend (vm, 10e-3);
639   rstat = avf_get_u32 (ad->bar0, AVFGEN_RSTAT);
640
641   if (rstat == 2 || rstat == 3)
642     return 0;
643
644   if (--n_retry == 0)
645     return clib_error_return (0, "reset failed (timeout)");
646
647   goto retry;
648 }
649
650 clib_error_t *
651 avf_device_init (vlib_main_t * vm, avf_device_t * ad)
652 {
653   virtchnl_version_info_t ver = { 0 };
654   virtchnl_vf_resource_t res = { 0 };
655   clib_error_t *error;
656   vlib_thread_main_t *tm = vlib_get_thread_main ();
657   int i;
658
659   avf_adminq_init (vm, ad);
660
661   if ((error = avf_device_reset (vm, ad)))
662     return error;
663
664   avf_adminq_init (vm, ad);
665
666   /*
667    * OP_VERSION
668    */
669   if ((error = avf_op_version (vm, ad, &ver)))
670     return error;
671
672   if (ver.major != VIRTCHNL_VERSION_MAJOR ||
673       ver.minor != VIRTCHNL_VERSION_MINOR)
674     return clib_error_return (0, "incompatible protocol version "
675                               "(remote %d.%d)", ver.major, ver.minor);
676
677   /*
678    * OP_GET_VF_RESOUCES
679    */
680   if ((error = avf_op_get_vf_resources (vm, ad, &res)))
681     return error;
682
683   if (res.num_vsis != 1 || res.vsi_res[0].vsi_type != VIRTCHNL_VSI_SRIOV)
684     return clib_error_return (0, "unexpected GET_VF_RESOURCE reply received");
685
686   ad->vsi_id = res.vsi_res[0].vsi_id;
687   ad->feature_bitmap = res.vf_offload_flags;
688   ad->num_queue_pairs = res.num_queue_pairs;
689   ad->max_vectors = res.max_vectors;
690   ad->max_mtu = res.max_mtu;
691   ad->rss_key_size = res.rss_key_size;
692   ad->rss_lut_size = res.rss_lut_size;
693
694   clib_memcpy (ad->hwaddr, res.vsi_res[0].default_mac_addr, 6);
695
696   /*
697    * Disable VLAN stripping
698    */
699   if ((error = avf_op_disable_vlan_stripping (vm, ad)))
700     return error;
701
702   if ((error = avf_config_promisc_mode (vm, ad)))
703     return error;
704
705   if ((error = avf_cmd_rx_ctl_reg_write (vm, ad, 0xc400, 0)))
706     return error;
707
708   if ((error = avf_cmd_rx_ctl_reg_write (vm, ad, 0xc404, 0)))
709     return error;
710
711   /*
712    * Init Queues
713    */
714   if ((error = avf_rxq_init (vm, ad, 0)))
715     return error;
716
717   for (i = 0; i < tm->n_vlib_mains; i++)
718     if ((error = avf_txq_init (vm, ad, i)))
719       return error;
720
721   if ((error = avf_op_config_vsi_queues (vm, ad)))
722     return error;
723
724   if ((error = avf_op_config_irq_map (vm, ad)))
725     return error;
726
727   avf_irq_0_enable (ad);
728   avf_irq_n_enable (ad, 0);
729
730   if ((error = avf_op_add_eth_addr (vm, ad, 1, ad->hwaddr)))
731     return error;
732
733   if ((error = avf_op_enable_queues (vm, ad, 1, 0)))
734     return error;
735
736   if ((error = avf_op_enable_queues (vm, ad, 0, 1)))
737     return error;
738
739   ad->flags |= AVF_DEVICE_F_INITIALIZED;
740   return error;
741 }
742
743 void
744 avf_process_one_device (vlib_main_t * vm, avf_device_t * ad, int is_irq)
745 {
746   avf_main_t *am = &avf_main;
747   vnet_main_t *vnm = vnet_get_main ();
748   virtchnl_pf_event_t *e;
749   u32 r;
750
751   if (ad->flags & AVF_DEVICE_F_ERROR)
752     return;
753
754   if ((ad->flags & AVF_DEVICE_F_INITIALIZED) == 0)
755     return;
756
757   ASSERT (ad->error == 0);
758
759   r = avf_get_u32 (ad->bar0, AVF_ARQLEN);
760   if ((r & 0xf0000000) != (1 << 31))
761     {
762       ad->error = clib_error_return (0, "arq not enabled, arqlen = 0x%x", r);
763       goto error;
764     }
765
766   r = avf_get_u32 (ad->bar0, AVF_ATQLEN);
767   if ((r & 0xf0000000) != (1 << 31))
768     {
769       ad->error = clib_error_return (0, "atq not enabled, atqlen = 0x%x", r);
770       goto error;
771     }
772
773   if (is_irq == 0)
774     avf_op_get_stats (vm, ad, &ad->eth_stats);
775
776   /* *INDENT-OFF* */
777   vec_foreach (e, ad->events)
778     {
779       if (e->event == VIRTCHNL_EVENT_LINK_CHANGE)
780         {
781           int link_up = e->event_data.link_event.link_status;
782           virtchnl_link_speed_t speed = e->event_data.link_event.link_speed;
783           u32 flags = 0;
784
785           if (link_up && (ad->flags & AVF_DEVICE_F_LINK_UP) == 0)
786             {
787               ad->flags |= AVF_DEVICE_F_LINK_UP;
788               flags |= (VNET_HW_INTERFACE_FLAG_FULL_DUPLEX |
789                         VNET_HW_INTERFACE_FLAG_LINK_UP);
790               if (speed == VIRTCHNL_LINK_SPEED_40GB)
791                 flags |= VNET_HW_INTERFACE_FLAG_SPEED_40G;
792               else if (speed == VIRTCHNL_LINK_SPEED_25GB)
793                 flags |= VNET_HW_INTERFACE_FLAG_SPEED_25G;
794               else if (speed == VIRTCHNL_LINK_SPEED_10GB)
795                 flags |= VNET_HW_INTERFACE_FLAG_SPEED_10G;
796               else if (speed == VIRTCHNL_LINK_SPEED_1GB)
797                 flags |= VNET_HW_INTERFACE_FLAG_SPEED_1G;
798               else if (speed == VIRTCHNL_LINK_SPEED_100MB)
799                 flags |= VNET_HW_INTERFACE_FLAG_SPEED_100M;
800               vnet_hw_interface_set_flags (vnm, ad->hw_if_index, flags);
801               ad->link_speed = speed;
802             }
803           else if (!link_up && (ad->flags & AVF_DEVICE_F_LINK_UP) != 0)
804             {
805               ad->flags &= ~AVF_DEVICE_F_LINK_UP;
806               ad->link_speed = 0;
807             }
808
809           if (ad->flags & AVF_DEVICE_F_ELOG)
810             {
811               ELOG_TYPE_DECLARE (el) =
812                 {
813                   .format = "avf[%d] link change: link_status %d "
814                     "link_speed %d",
815                   .format_args = "i4i1i1",
816                 };
817               struct
818                 {
819                   u32 dev_instance;
820                   u8 link_status;
821                   u8 link_speed;
822                 } *ed;
823               ed = ELOG_DATA (&vm->elog_main, el);
824               ed->dev_instance = ad->dev_instance;
825               ed->link_status = link_up;
826               ed->link_speed = speed;
827             }
828         }
829       else
830         {
831           if (ad->flags & AVF_DEVICE_F_ELOG)
832             {
833               ELOG_TYPE_DECLARE (el) =
834                 {
835                   .format = "avf[%d] unknown event: event %d severity %d",
836                   .format_args = "i4i4i1i1",
837                 };
838               struct
839                 {
840                   u32 dev_instance;
841                   u32 event;
842                   u32 severity;
843                 } *ed;
844               ed = ELOG_DATA (&vm->elog_main, el);
845               ed->dev_instance = ad->dev_instance;
846               ed->event = e->event;
847               ed->severity = e->severity;
848             }
849         }
850     }
851   /* *INDENT-ON* */
852   vec_reset_length (ad->events);
853
854   return;
855
856 error:
857   ad->flags |= AVF_DEVICE_F_ERROR;
858   ASSERT (ad->error != 0);
859   vlib_log_err (am->log_class, "%U", format_clib_error, ad->error);
860 }
861
862 static u32
863 avf_flag_change (vnet_main_t * vnm, vnet_hw_interface_t * hw, u32 flags)
864 {
865   avf_main_t *am = &avf_main;
866   vlib_log_warn (am->log_class, "TODO");
867   return 0;
868 }
869
870 static uword
871 avf_process (vlib_main_t * vm, vlib_node_runtime_t * rt, vlib_frame_t * f)
872 {
873   avf_main_t *am = &avf_main;
874   avf_device_t *ad;
875   uword *event_data = 0, event_type;
876   int enabled = 0, irq;
877   f64 last_run_duration = 0;
878   f64 last_periodic_time = 0;
879
880   while (1)
881     {
882       if (enabled)
883         vlib_process_wait_for_event_or_clock (vm, 5.0 - last_run_duration);
884       else
885         vlib_process_wait_for_event (vm);
886
887       event_type = vlib_process_get_events (vm, &event_data);
888       vec_reset_length (event_data);
889       irq = 0;
890
891       switch (event_type)
892         {
893         case ~0:
894           last_periodic_time = vlib_time_now (vm);
895           break;
896         case AVF_PROCESS_EVENT_START:
897           enabled = 1;
898           break;
899         case AVF_PROCESS_EVENT_STOP:
900           enabled = 0;
901           continue;
902         case AVF_PROCESS_EVENT_AQ_INT:
903           irq = 1;
904           break;
905         default:
906           ASSERT (0);
907         }
908
909       /* *INDENT-OFF* */
910       pool_foreach (ad, am->devices,
911         {
912           avf_process_one_device (vm, ad, irq);
913         });
914       /* *INDENT-ON* */
915       last_run_duration = vlib_time_now (vm) - last_periodic_time;
916     }
917   return 0;
918 }
919
920 /* *INDENT-OFF* */
921 VLIB_REGISTER_NODE (avf_process_node, static)  = {
922   .function = avf_process,
923   .type = VLIB_NODE_TYPE_PROCESS,
924   .name = "avf-process",
925 };
926 /* *INDENT-ON* */
927
928 static void
929 avf_irq_0_handler (vlib_pci_dev_handle_t h, u16 line)
930 {
931   vlib_main_t *vm = vlib_get_main ();
932   avf_main_t *am = &avf_main;
933   uword pd = vlib_pci_get_private_data (h);
934   avf_device_t *ad = pool_elt_at_index (am->devices, pd);
935   u32 icr0;
936
937   icr0 = avf_reg_read (ad, AVFINT_ICR0);
938
939   if (ad->flags & AVF_DEVICE_F_ELOG)
940     {
941       /* *INDENT-OFF* */
942       ELOG_TYPE_DECLARE (el) =
943         {
944           .format = "avf[%d] irq 0: icr0 0x%x",
945           .format_args = "i4i4",
946         };
947       /* *INDENT-ON* */
948       struct
949       {
950         u32 dev_instance;
951         u32 icr0;
952       } *ed;
953
954       ed = ELOG_DATA (&vm->elog_main, el);
955       ed->dev_instance = ad->dev_instance;
956       ed->icr0 = icr0;
957     }
958
959   avf_irq_0_enable (ad);
960
961   /* bit 30 - Send/Receive Admin queue interrupt indication */
962   if (icr0 & (1 << 30))
963     vlib_process_signal_event (vm, avf_process_node.index,
964                                AVF_PROCESS_EVENT_AQ_INT, 0);
965 }
966
967 static void
968 avf_irq_n_handler (vlib_pci_dev_handle_t h, u16 line)
969 {
970   vlib_main_t *vm = vlib_get_main ();
971   avf_main_t *am = &avf_main;
972   uword pd = vlib_pci_get_private_data (h);
973   avf_device_t *ad = pool_elt_at_index (am->devices, pd);
974
975   if (ad->flags & AVF_DEVICE_F_ELOG)
976     {
977       /* *INDENT-OFF* */
978       ELOG_TYPE_DECLARE (el) =
979         {
980           .format = "avf[%d] irq %d: received",
981           .format_args = "i4i2",
982         };
983       /* *INDENT-ON* */
984       struct
985       {
986         u32 dev_instance;
987         u16 line;
988       } *ed;
989
990       ed = ELOG_DATA (&vm->elog_main, el);
991       ed->dev_instance = ad->dev_instance;
992       ed->line = line;
993     }
994
995   avf_irq_n_enable (ad, 0);
996 }
997
998 void
999 avf_delete_if (vlib_main_t * vm, avf_device_t * ad)
1000 {
1001   vnet_main_t *vnm = vnet_get_main ();
1002   avf_main_t *am = &avf_main;
1003   int i;
1004
1005   if (ad->hw_if_index)
1006     {
1007       vnet_hw_interface_set_flags (vnm, ad->hw_if_index, 0);
1008       vnet_hw_interface_unassign_rx_thread (vnm, ad->hw_if_index, 0);
1009       ethernet_delete_interface (vnm, ad->hw_if_index);
1010     }
1011
1012   vlib_pci_device_close (ad->pci_dev_handle);
1013
1014   vlib_physmem_free (vm, am->physmem_region, ad->atq);
1015   vlib_physmem_free (vm, am->physmem_region, ad->arq);
1016   vlib_physmem_free (vm, am->physmem_region, ad->atq_bufs);
1017   vlib_physmem_free (vm, am->physmem_region, ad->arq_bufs);
1018
1019   /* *INDENT-OFF* */
1020   vec_foreach_index (i, ad->rxqs)
1021     {
1022       avf_rxq_t *rxq = vec_elt_at_index (ad->rxqs, i);
1023       vlib_physmem_free (vm, am->physmem_region, rxq->descs);
1024       if (rxq->n_bufs)
1025         vlib_buffer_free_from_ring (vm, rxq->bufs, rxq->next, rxq->size,
1026                                     rxq->n_bufs);
1027       vec_free (rxq->bufs);
1028     }
1029   /* *INDENT-ON* */
1030   vec_free (ad->rxqs);
1031
1032   /* *INDENT-OFF* */
1033   vec_foreach_index (i, ad->txqs)
1034     {
1035       avf_txq_t *txq = vec_elt_at_index (ad->txqs, i);
1036       vlib_physmem_free (vm, am->physmem_region, txq->descs);
1037       if (txq->n_bufs)
1038         {
1039           u16 first = (txq->next - txq->n_bufs) & (txq->size -1);
1040           vlib_buffer_free_from_ring (vm, txq->bufs, first, txq->size,
1041                                       txq->n_bufs);
1042         }
1043       vec_free (txq->bufs);
1044     }
1045   /* *INDENT-ON* */
1046   vec_free (ad->txqs);
1047
1048   clib_error_free (ad->error);
1049   memset (ad, 0, sizeof (*ad));
1050   pool_put (am->devices, ad);
1051 }
1052
1053 void
1054 avf_create_if (vlib_main_t * vm, avf_create_if_args_t * args)
1055 {
1056   vnet_main_t *vnm = vnet_get_main ();
1057   avf_main_t *am = &avf_main;
1058   avf_device_t *ad;
1059   vlib_pci_dev_handle_t h;
1060   clib_error_t *error = 0;
1061
1062   pool_get (am->devices, ad);
1063   ad->dev_instance = ad - am->devices;
1064   ad->per_interface_next_index = ~0;
1065
1066   if (args->enable_elog)
1067     ad->flags |= AVF_DEVICE_F_ELOG;
1068
1069   if ((error = vlib_pci_device_open (&args->addr, avf_pci_device_ids, &h)))
1070     goto error;
1071   ad->pci_dev_handle = h;
1072
1073   vlib_pci_set_private_data (h, ad->dev_instance);
1074
1075   if ((error = vlib_pci_bus_master_enable (h)))
1076     goto error;
1077
1078   if ((error = vlib_pci_map_region (h, 0, &ad->bar0)))
1079     goto error;
1080
1081   if ((error = vlib_pci_register_msix_handler (h, 0, 1, &avf_irq_0_handler)))
1082     goto error;
1083
1084   if ((error = vlib_pci_register_msix_handler (h, 1, 1, &avf_irq_n_handler)))
1085     goto error;
1086
1087   if ((error = vlib_pci_enable_msix_irq (h, 0, 2)))
1088     goto error;
1089
1090   if (am->physmem_region_alloc == 0)
1091     {
1092       u32 flags = VLIB_PHYSMEM_F_INIT_MHEAP | VLIB_PHYSMEM_F_HUGETLB;
1093       error = vlib_physmem_region_alloc (vm, "avf descriptors", 4 << 20, 0,
1094                                          flags, &am->physmem_region);
1095       if (error)
1096         goto error;
1097       am->physmem_region_alloc = 1;
1098     }
1099   ad->atq = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
1100                                         sizeof (avf_aq_desc_t) * AVF_MBOX_LEN,
1101                                         64);
1102   if (error)
1103     goto error;
1104
1105   ad->arq = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
1106                                         sizeof (avf_aq_desc_t) * AVF_MBOX_LEN,
1107                                         64);
1108   if (error)
1109     goto error;
1110
1111   ad->atq_bufs = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
1112                                              AVF_MBOX_BUF_SZ * AVF_MBOX_LEN,
1113                                              64);
1114   if (error)
1115     goto error;
1116
1117   ad->arq_bufs = vlib_physmem_alloc_aligned (vm, am->physmem_region, &error,
1118                                              AVF_MBOX_BUF_SZ * AVF_MBOX_LEN,
1119                                              64);
1120   if (error)
1121     goto error;
1122
1123   if ((error = vlib_pci_intr_enable (h)))
1124     goto error;
1125
1126   /* FIXME detect */
1127   ad->flags |= AVF_DEVICE_F_IOVA;
1128
1129   if ((error = avf_device_init (vm, ad)))
1130     goto error;
1131
1132   /* create interface */
1133   error = ethernet_register_interface (vnm, avf_device_class.index,
1134                                        ad->dev_instance, ad->hwaddr,
1135                                        &ad->hw_if_index, avf_flag_change);
1136
1137   if (error)
1138     goto error;
1139
1140   vnet_sw_interface_t *sw = vnet_get_hw_sw_interface (vnm, ad->hw_if_index);
1141   ad->sw_if_index = sw->sw_if_index;
1142
1143   vnet_hw_interface_set_input_node (vnm, ad->hw_if_index,
1144                                     avf_input_node.index);
1145
1146   if (pool_elts (am->devices) == 1)
1147     vlib_process_signal_event (vm, avf_process_node.index,
1148                                AVF_PROCESS_EVENT_START, 0);
1149
1150   return;
1151
1152 error:
1153   avf_delete_if (vm, ad);
1154   args->rv = VNET_API_ERROR_INVALID_INTERFACE;
1155   args->error = clib_error_return (error, "pci-addr %U",
1156                                    format_vlib_pci_addr, &args->addr);
1157   vlib_log_err (am->log_class, "%U", format_clib_error, args->error);
1158 }
1159
1160 static clib_error_t *
1161 avf_interface_admin_up_down (vnet_main_t * vnm, u32 hw_if_index, u32 flags)
1162 {
1163   vnet_hw_interface_t *hi = vnet_get_hw_interface (vnm, hw_if_index);
1164   avf_main_t *am = &avf_main;
1165   avf_device_t *ad = vec_elt_at_index (am->devices, hi->dev_instance);
1166   uword is_up = (flags & VNET_SW_INTERFACE_FLAG_ADMIN_UP) != 0;
1167
1168   if (ad->flags & AVF_DEVICE_F_ERROR)
1169     return clib_error_return (0, "device is in error state");
1170
1171   if (is_up)
1172     {
1173       vnet_hw_interface_set_flags (vnm, ad->hw_if_index,
1174                                    VNET_HW_INTERFACE_FLAG_LINK_UP);
1175       ad->flags |= AVF_DEVICE_F_ADMIN_UP;
1176       vnet_hw_interface_assign_rx_thread (vnm, ad->hw_if_index, 0, ~0);
1177     }
1178   else
1179     {
1180       vnet_hw_interface_set_flags (vnm, ad->hw_if_index, 0);
1181       ad->flags &= ~AVF_DEVICE_F_ADMIN_UP;
1182     }
1183   return 0;
1184 }
1185
1186 /* *INDENT-OFF* */
1187 VNET_DEVICE_CLASS (avf_device_class,) =
1188 {
1189   .name = "Adaptive Virtual Function (AVF) interface",
1190   .tx_function = avf_interface_tx,
1191   .format_device = format_avf_device,
1192   .format_device_name = format_avf_device_name,
1193   .admin_up_down_function = avf_interface_admin_up_down,
1194 };
1195 /* *INDENT-ON* */
1196
1197 clib_error_t *
1198 avf_init (vlib_main_t * vm)
1199 {
1200   avf_main_t *am = &avf_main;
1201   clib_error_t *error;
1202   vlib_thread_main_t *tm = vlib_get_thread_main ();
1203   int i;
1204
1205   if ((error = vlib_call_init_function (vm, pci_bus_init)))
1206     return error;
1207
1208   vec_validate_aligned (am->per_thread_data, tm->n_vlib_mains - 1,
1209                         CLIB_CACHE_LINE_BYTES);
1210
1211   /* initialize ptype based loopup table */
1212   vec_validate_aligned (am->ptypes, 255, CLIB_CACHE_LINE_BYTES);
1213
1214   /* *INDENT-OFF* */
1215   vec_foreach_index (i, am->ptypes)
1216     {
1217       avf_ptype_t *p = vec_elt_at_index (am->ptypes, i);
1218       if ((i >= 22) && (i <= 87))
1219         {
1220           p->next_node = VNET_DEVICE_INPUT_NEXT_IP4_NCS_INPUT;
1221           p->flags = VNET_BUFFER_F_IS_IP4;
1222         }
1223       else if ((i >= 88) && (i <= 153))
1224         {
1225           p->next_node = VNET_DEVICE_INPUT_NEXT_IP6_INPUT;
1226           p->flags = VNET_BUFFER_F_IS_IP6;
1227         }
1228       else
1229         p->next_node = VNET_DEVICE_INPUT_NEXT_ETHERNET_INPUT;
1230       p->buffer_advance = device_input_next_node_advance[p->next_node];
1231       p->flags |= VLIB_BUFFER_TOTAL_LENGTH_VALID;
1232     }
1233   /* *INDENT-ON* */
1234
1235   am->log_class = vlib_log_register_class ("avf_plugin", 0);
1236   vlib_log_debug (am->log_class, "initialized");
1237
1238   return 0;
1239 }
1240
1241 VLIB_INIT_FUNCTION (avf_init);
1242
1243 /*
1244  * fd.io coding-style-patch-verification: ON
1245  *
1246  * Local Variables:
1247  * eval: (c-set-style "gnu")
1248  * End:
1249  */