svm: track fifo segment virtual memory consumption
[vpp.git] / src / svm / fifo_segment.c
1 /*
2  * Copyright (c) 2016-2019 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15
16 #include <svm/fifo_segment.h>
17
18 static inline fifo_segment_slice_t *
19 fsh_slice_get (fifo_segment_header_t * fsh, u32 slice_index)
20 {
21   return &fsh->slices[slice_index];
22 }
23
24 static char *fifo_segment_mem_status_strings[] = {
25 #define _(sym,str) str,
26   foreach_segment_mem_status
27 #undef _
28 };
29
30 /**
31  * Fifo segment free space
32  *
33  * Queries the underlying memory manager, dlmalloc, for free space. Since this
34  * ends up walking the internal data structures, it should not be called
35  * indiscriminately.
36  *
37  * @param fs            fifo segment
38  * @return              number of free bytes
39  */
40 static uword
41 fsh_free_space (fifo_segment_header_t * fsh)
42 {
43   struct dlmallinfo dlminfo;
44
45   dlminfo = mspace_mallinfo (fsh->ssvm_sh->heap);
46   return dlminfo.fordblks;
47 }
48
49 static inline void
50 fsh_free_bytes_sub (fifo_segment_header_t * fsh, int size)
51 {
52   clib_atomic_fetch_sub_rel (&fsh->n_free_bytes, size);
53 }
54
55 static inline uword
56 fsh_n_free_bytes (fifo_segment_header_t * fsh)
57 {
58   uword n_free = clib_atomic_load_relax_n (&fsh->n_free_bytes);
59   return n_free > fsh->n_reserved_bytes ? n_free - fsh->n_reserved_bytes : 0;
60 }
61
62 static inline void
63 fsh_update_free_bytes (fifo_segment_header_t * fsh)
64 {
65   clib_atomic_store_rel_n (&fsh->n_free_bytes, fsh_free_space (fsh));
66 }
67
68 static inline void
69 fsh_cached_bytes_add (fifo_segment_header_t * fsh, int size)
70 {
71   clib_atomic_fetch_add_rel (&fsh->n_cached_bytes, size);
72 }
73
74 static inline void
75 fsh_cached_bytes_sub (fifo_segment_header_t * fsh, int size)
76 {
77   clib_atomic_fetch_sub_rel (&fsh->n_cached_bytes, size);
78 }
79
80 static inline uword
81 fsh_n_cached_bytes (fifo_segment_header_t * fsh)
82 {
83   uword n_cached = clib_atomic_load_relax_n (&fsh->n_cached_bytes);
84   return n_cached;
85 }
86
87 static inline void
88 fsh_active_fifos_update (fifo_segment_header_t * fsh, int inc)
89 {
90   clib_atomic_fetch_add_rel (&fsh->n_active_fifos, inc);
91 }
92
93 static inline uword
94 fsh_virtual_mem (fifo_segment_header_t * fsh)
95 {
96   fifo_segment_slice_t *fss;
97   uword total_vm = 0;
98   int i;
99
100   for (i = 0; i < fsh->n_slices; i++)
101     {
102       fss = fsh_slice_get (fsh, i);
103       total_vm += clib_atomic_load_relax_n (&fss->virtual_mem);
104     }
105   return total_vm;
106 }
107
108 void
109 fsh_virtual_mem_update (fifo_segment_header_t * fsh, u32 slice_index,
110                         int n_bytes)
111 {
112   fifo_segment_slice_t *fss = fsh_slice_get (fsh, slice_index);
113   fss->virtual_mem += n_bytes;
114 }
115
116 static void
117 fsh_check_mem (fifo_segment_header_t * fsh)
118 {
119   uword thresh;
120
121   if (fsh->flags & FIFO_SEGMENT_F_MEM_LIMIT)
122     return;
123
124   thresh = clib_max (0.01 * fsh->ssvm_sh->ssvm_size,
125                      2 * fsh->n_reserved_bytes);
126   if (fsh->n_free_bytes > thresh)
127     return;
128
129   fsh->flags |= FIFO_SEGMENT_F_MEM_LIMIT;
130   fsh_update_free_bytes (fsh);
131 }
132
133 /**
134  * Initialize fifo segment shared header
135  */
136 int
137 fifo_segment_init (fifo_segment_t * fs)
138 {
139   fifo_segment_header_t *fsh;
140   fifo_segment_slice_t *fss;
141   ssvm_shared_header_t *sh;
142   u32 max_chunk_sz;
143   uword max_fifo;
144   void *oldheap;
145   int i;
146
147   sh = fs->ssvm.sh;
148   oldheap = ssvm_push_heap (sh);
149
150   /*
151    * Manually align the fifo segment header to sizeof(uword) = 8 bytes.
152    * Long story made short: the "process-private" fifo segment
153    * is allocated from the main heap, not mmapped. dlmalloc
154    * only guarantees 4-byte alignment, and on aarch64
155    * the fsh can end up 4-byte but not 8-byte aligned.
156    * That eventually causes the atomic op in fifo_segment_update_free_bytes
157    * to backfire.
158    */
159   fsh = clib_mem_alloc_aligned (sizeof (*fsh), sizeof (uword));
160   clib_memset (fsh, 0, sizeof (*fsh));
161   fs->h = sh->opaque[0] = fsh;
162   fs->n_slices = clib_max (fs->n_slices, 1);
163
164   fsh->ssvm_sh = fs->ssvm.sh;
165   fsh->n_slices = fs->n_slices;
166   max_fifo = clib_min ((fsh_free_space (fsh) - 4096) / 2,
167                        FIFO_SEGMENT_MAX_FIFO_SIZE);
168   fsh->max_log2_chunk_size = max_log2 (max_fifo);
169
170   fsh->slices = clib_mem_alloc (sizeof (*fss) * fs->n_slices);
171   clib_memset (fsh->slices, 0, sizeof (*fss) * fs->n_slices);
172   max_chunk_sz = fsh->max_log2_chunk_size - FIFO_SEGMENT_MIN_LOG2_FIFO_SIZE;
173
174   for (i = 0; i < fs->n_slices; i++)
175     {
176       fss = fsh_slice_get (fsh, i);
177       vec_validate_init_empty (fss->free_chunks, max_chunk_sz, 0);
178       clib_spinlock_init (&fss->chunk_lock);
179     }
180
181   ssvm_pop_heap (oldheap);
182
183   fsh->n_free_bytes = fsh_free_space (fsh);
184   fsh->n_cached_bytes = 0;
185   fsh->n_reserved_bytes = clib_min (0.01 * fsh->n_free_bytes, 256 << 10);
186   sh->ready = 1;
187   return (0);
188 }
189
190 /**
191  * Create a fifo segment and initialize as master
192  */
193 int
194 fifo_segment_create (fifo_segment_main_t * sm, fifo_segment_create_args_t * a)
195 {
196   fifo_segment_t *fs;
197   uword baseva;
198   int rv;
199
200   /* Allocate a fresh segment */
201   pool_get_zero (sm->segments, fs);
202
203   baseva = a->segment_type == SSVM_SEGMENT_PRIVATE ? ~0ULL : sm->next_baseva;
204   fs->ssvm.ssvm_size = a->segment_size;
205   fs->ssvm.i_am_master = 1;
206   fs->ssvm.my_pid = getpid ();
207   fs->ssvm.name = format (0, "%s%c", a->segment_name, 0);
208   fs->ssvm.requested_va = baseva;
209
210   if ((rv = ssvm_master_init (&fs->ssvm, a->segment_type)))
211     {
212       pool_put (sm->segments, fs);
213       return (rv);
214     }
215
216   /* Note: requested_va updated due to seg base addr randomization */
217   sm->next_baseva = fs->ssvm.sh->ssvm_va + fs->ssvm.ssvm_size;
218
219   fifo_segment_init (fs);
220   vec_add1 (a->new_segment_indices, fs - sm->segments);
221   return (0);
222 }
223
224 /**
225  * Attach as slave to a fifo segment
226  */
227 int
228 fifo_segment_attach (fifo_segment_main_t * sm, fifo_segment_create_args_t * a)
229 {
230   fifo_segment_t *fs;
231   int rv;
232
233   pool_get_zero (sm->segments, fs);
234
235   fs->ssvm.ssvm_size = a->segment_size;
236   fs->ssvm.my_pid = getpid ();
237   fs->ssvm.name = format (0, "%s%c", a->segment_name, 0);
238   fs->ssvm.requested_va = sm->next_baseva;
239   if (a->segment_type == SSVM_SEGMENT_MEMFD)
240     fs->ssvm.fd = a->memfd_fd;
241   else
242     fs->ssvm.attach_timeout = sm->timeout_in_seconds;
243
244   if ((rv = ssvm_slave_init (&fs->ssvm, a->segment_type)))
245     {
246       _vec_len (fs) = vec_len (fs) - 1;
247       return (rv);
248     }
249
250   /* Fish the segment header */
251   fs->h = fs->ssvm.sh->opaque[0];
252
253   vec_add1 (a->new_segment_indices, fs - sm->segments);
254   return (0);
255 }
256
257 void
258 fifo_segment_delete (fifo_segment_main_t * sm, fifo_segment_t * s)
259 {
260   ssvm_delete (&s->ssvm);
261   clib_memset (s, 0xfe, sizeof (*s));
262   pool_put (sm->segments, s);
263 }
264
265 u32
266 fifo_segment_index (fifo_segment_main_t * sm, fifo_segment_t * s)
267 {
268   return s - sm->segments;
269 }
270
271 fifo_segment_t *
272 fifo_segment_get_segment (fifo_segment_main_t * sm, u32 segment_index)
273 {
274   return pool_elt_at_index (sm->segments, segment_index);
275 }
276
277 void
278 fifo_segment_info (fifo_segment_t * seg, char **address, size_t * size)
279 {
280   *address = (char *) seg->ssvm.sh->ssvm_va;
281   *size = seg->ssvm.ssvm_size;
282 }
283
284 void
285 fifo_segment_main_init (fifo_segment_main_t * sm, u64 baseva,
286                         u32 timeout_in_seconds)
287 {
288   sm->next_baseva = baseva;
289   sm->timeout_in_seconds = timeout_in_seconds;
290 }
291
292 static inline u32
293 fs_freelist_for_size (u32 size)
294 {
295   if (PREDICT_FALSE (size < FIFO_SEGMENT_MIN_FIFO_SIZE))
296     return 0;
297   return max_log2 (size) - FIFO_SEGMENT_MIN_LOG2_FIFO_SIZE;
298 }
299
300 static inline u32
301 fs_freelist_index_to_size (u32 fl_index)
302 {
303   return 1 << (fl_index + FIFO_SEGMENT_MIN_LOG2_FIFO_SIZE);
304 }
305
306 static inline int
307 fs_chunk_size_is_valid (fifo_segment_header_t * fsh, u32 size)
308 {
309   /*
310    * 4K minimum. It's not likely that anything good will happen
311    * with a smaller FIFO.
312    */
313   return size >= FIFO_SEGMENT_MIN_FIFO_SIZE
314     && size <= (1 << fsh->max_log2_chunk_size);
315 }
316
317 static svm_fifo_t *
318 fs_try_alloc_fifo_freelist (fifo_segment_slice_t * fss, u32 fl_index)
319 {
320   svm_fifo_chunk_t *c;
321   svm_fifo_t *f;
322
323   f = fss->free_fifos;
324   c = fss->free_chunks[fl_index];
325
326   if (!f || !c)
327     return 0;
328
329   fss->free_fifos = f->next;
330   fss->free_chunks[fl_index] = c->next;
331   c->next = 0;
332   c->start_byte = 0;
333   memset (f, 0, sizeof (*f));
334   f->start_chunk = c;
335   f->end_chunk = c;
336
337   fss->n_fl_chunk_bytes -= fs_freelist_index_to_size (fl_index);
338   return f;
339 }
340
341 svm_fifo_chunk_t *
342 fs_try_alloc_multi_chunk (fifo_segment_header_t * fsh,
343                           fifo_segment_slice_t * fss, u32 data_bytes)
344 {
345   u32 fl_index, fl_size, n_alloc = 0, req_bytes = data_bytes;
346   svm_fifo_chunk_t *c, *first = 0, *next;
347
348   fl_index = fs_freelist_for_size (req_bytes);
349   if (fl_index > 0)
350     fl_index -= 1;
351
352   fl_size = fs_freelist_index_to_size (fl_index);
353
354   while (req_bytes)
355     {
356       c = fss->free_chunks[fl_index];
357       if (c)
358         {
359           fss->free_chunks[fl_index] = c->next;
360           c->next = first;
361           first = c;
362           n_alloc += fl_size;
363           req_bytes -= clib_min (fl_size, req_bytes);
364         }
365       else
366         {
367           /* Failed to allocate with smaller chunks */
368           if (fl_index == 0)
369             {
370               /* free all chunks if any allocated */
371               c = first;
372               while (c)
373                 {
374                   fl_index = fs_freelist_for_size (c->length);
375                   fl_size = fs_freelist_index_to_size (fl_index);
376                   next = c->next;
377                   c->next = fss->free_chunks[fl_index];
378                   fss->free_chunks[fl_index] = c;
379                   fss->n_fl_chunk_bytes += fl_size;
380                   c = next;
381                 }
382               n_alloc = 0;
383               first = 0;
384               fl_index = fs_freelist_for_size (data_bytes);
385               if (fss->free_chunks[fl_index + 1])
386                 {
387                   fl_index += 1;
388                   fl_size = fs_freelist_index_to_size (fl_index);
389                   continue;
390                 }
391
392               return 0;
393             }
394           fl_index -= 1;
395           fl_size = fl_size >> 1;
396         }
397     }
398
399   fss->n_fl_chunk_bytes -= n_alloc;
400   fsh_cached_bytes_sub (fsh, n_alloc);
401   return first;
402 }
403
404 static svm_fifo_t *
405 fs_try_alloc_fifo_freelist_multi_chunk (fifo_segment_header_t * fsh,
406                                         fifo_segment_slice_t * fss,
407                                         u32 data_bytes)
408 {
409   svm_fifo_chunk_t *c, *first = 0, *last = 0, *next;
410   u32 fl_index, fl_size, n_alloc = 0;
411   svm_fifo_t *f;
412
413   f = fss->free_fifos;
414   if (!f)
415     {
416       void *oldheap = ssvm_push_heap (fsh->ssvm_sh);
417       f = clib_mem_alloc_aligned (sizeof (*f), CLIB_CACHE_LINE_BYTES);
418       ssvm_pop_heap (oldheap);
419       if (!f)
420         return 0;
421       memset (f, 0, sizeof (*f));
422       fsh_free_bytes_sub (fsh, sizeof (*f));
423     }
424   else
425     {
426       fss->free_fifos = f->next;
427     }
428
429   fl_index = fs_freelist_for_size (data_bytes);
430   if (fl_index > 0)
431     fl_index -= 1;
432
433   fl_size = fs_freelist_index_to_size (fl_index);
434
435   while (data_bytes)
436     {
437       c = fss->free_chunks[fl_index];
438       if (c)
439         {
440           fss->free_chunks[fl_index] = c->next;
441           if (!last)
442             last = c;
443           c->next = first;
444           first = c;
445           n_alloc += fl_size;
446           data_bytes -= clib_min (fl_size, data_bytes);
447         }
448       else
449         {
450           /* Failed to allocate with smaller chunks */
451           if (fl_index == 0)
452             {
453               /* free all chunks if any allocated */
454               c = first;
455               while (c)
456                 {
457                   fl_index = fs_freelist_for_size (c->length);
458                   fl_size = fs_freelist_index_to_size (fl_index);
459                   next = c->next;
460                   c->next = fss->free_chunks[fl_index];
461                   fss->free_chunks[fl_index] = c;
462                   fss->n_fl_chunk_bytes += fl_size;
463                   n_alloc -= fl_size;
464                   data_bytes += fl_size;
465                   c = next;
466                 }
467               first = last = 0;
468               fl_index = fs_freelist_for_size (data_bytes);
469               if (fss->free_chunks[fl_index + 1])
470                 {
471                   fl_index += 1;
472                   fl_size = fs_freelist_index_to_size (fl_index);
473                   continue;
474                 }
475
476               f->next = fss->free_fifos;
477               fss->free_fifos = f;
478               return 0;
479             }
480           fl_index -= 1;
481           fl_size = fl_size >> 1;
482         }
483     }
484
485   f->start_chunk = first;
486   f->end_chunk = last;
487   fss->n_fl_chunk_bytes -= n_alloc;
488   fsh_cached_bytes_sub (fsh, n_alloc);
489   return f;
490 }
491
492 static int
493 fsh_try_alloc_chunk_batch (fifo_segment_header_t * fsh,
494                            fifo_segment_slice_t * fss,
495                            u32 fl_index, u32 batch_size)
496 {
497   u32 rounded_data_size;
498   svm_fifo_chunk_t *c;
499   void *oldheap;
500   uword size;
501   u8 *cmem;
502   int i;
503
504   rounded_data_size = fs_freelist_index_to_size (fl_index);
505   size = (uword) (sizeof (*c) + rounded_data_size) * batch_size;
506
507   oldheap = ssvm_push_heap (fsh->ssvm_sh);
508   cmem = clib_mem_alloc_aligned_at_offset (size, CLIB_CACHE_LINE_BYTES,
509                                            0 /* align_offset */ ,
510                                            0 /* os_out_of_memory */ );
511   ssvm_pop_heap (oldheap);
512
513   /* Out of space.. */
514   if (cmem == 0)
515     return -1;
516
517   /* Carve fifo + chunk space */
518   for (i = 0; i < batch_size; i++)
519     {
520       c = (svm_fifo_chunk_t *) cmem;
521       c->start_byte = 0;
522       c->length = rounded_data_size;
523       c->enq_rb_index = RBTREE_TNIL_INDEX;
524       c->deq_rb_index = RBTREE_TNIL_INDEX;
525       c->next = fss->free_chunks[fl_index];
526       fss->free_chunks[fl_index] = c;
527       cmem += sizeof (*c) + rounded_data_size;
528     }
529
530   fss->n_fl_chunk_bytes += batch_size * rounded_data_size;
531   fsh_cached_bytes_add (fsh, batch_size * rounded_data_size);
532   fsh_free_bytes_sub (fsh, size);
533
534   return 0;
535 }
536
537 static int
538 fs_try_alloc_fifo_batch (fifo_segment_header_t * fsh,
539                          fifo_segment_slice_t * fss,
540                          u32 fl_index, u32 batch_size)
541 {
542   u32 hdrs, rounded_data_size;
543   svm_fifo_chunk_t *c;
544   svm_fifo_t *f;
545   void *oldheap;
546   uword size;
547   u8 *fmem;
548   int i;
549
550   rounded_data_size = fs_freelist_index_to_size (fl_index);
551   hdrs = sizeof (*f) + sizeof (*c);
552   size = (uword) (hdrs + rounded_data_size) * batch_size;
553
554   oldheap = ssvm_push_heap (fsh->ssvm_sh);
555   fmem = clib_mem_alloc_aligned_at_offset (size, CLIB_CACHE_LINE_BYTES,
556                                            0 /* align_offset */ ,
557                                            0 /* os_out_of_memory */ );
558   ssvm_pop_heap (oldheap);
559
560   /* Out of space.. */
561   if (fmem == 0)
562     return -1;
563
564   /* Carve fifo + chunk space */
565   for (i = 0; i < batch_size; i++)
566     {
567       f = (svm_fifo_t *) fmem;
568       memset (f, 0, sizeof (*f));
569       f->next = fss->free_fifos;
570       fss->free_fifos = f;
571       c = (svm_fifo_chunk_t *) (fmem + sizeof (*f));
572       c->start_byte = 0;
573       c->length = rounded_data_size;
574       c->enq_rb_index = RBTREE_TNIL_INDEX;
575       c->deq_rb_index = RBTREE_TNIL_INDEX;
576       c->next = fss->free_chunks[fl_index];
577       fss->free_chunks[fl_index] = c;
578       fmem += hdrs + rounded_data_size;
579     }
580
581   fss->n_fl_chunk_bytes += batch_size * rounded_data_size;
582   fsh_cached_bytes_add (fsh, batch_size * rounded_data_size);
583   fsh_free_bytes_sub (fsh, size);
584
585   return 0;
586 }
587
588 /**
589  * Try to allocate new fifo
590  *
591  * Tries the following steps in order:
592  * - grab fifo and chunk from freelists
593  * - batch fifo and chunk allocation
594  * - single fifo allocation
595  * - grab multiple fifo chunks from freelists
596  */
597 static svm_fifo_t *
598 fs_try_alloc_fifo (fifo_segment_header_t * fsh, fifo_segment_slice_t * fss,
599                    u32 data_bytes)
600 {
601   u32 fifo_sz, fl_index;
602   svm_fifo_t *f = 0;
603   uword n_free_bytes;
604   u32 min_size;
605
606   min_size = clib_max ((fsh->pct_first_alloc * data_bytes) / 100, 4096);
607   fl_index = fs_freelist_for_size (min_size);
608   fifo_sz = sizeof (svm_fifo_t) + sizeof (svm_fifo_chunk_t);
609   fifo_sz += 1 << max_log2 (min_size);
610
611   clib_spinlock_lock (&fss->chunk_lock);
612
613   if (fss->free_fifos && fss->free_chunks[fl_index])
614     {
615       f = fs_try_alloc_fifo_freelist (fss, fl_index);
616       if (f)
617         {
618           fsh_cached_bytes_sub (fsh, fs_freelist_index_to_size (fl_index));
619           goto done;
620         }
621     }
622
623   fsh_check_mem (fsh);
624   n_free_bytes = fsh_n_free_bytes (fsh);
625   if (fifo_sz * FIFO_SEGMENT_ALLOC_BATCH_SIZE < n_free_bytes)
626     {
627       if (fs_try_alloc_fifo_batch (fsh, fss, fl_index,
628                                    FIFO_SEGMENT_ALLOC_BATCH_SIZE))
629         goto done;
630
631       f = fs_try_alloc_fifo_freelist (fss, fl_index);
632       if (f)
633         fsh_cached_bytes_sub (fsh, fs_freelist_index_to_size (fl_index));
634       goto done;
635     }
636   if (fifo_sz <= n_free_bytes)
637     {
638       void *oldheap = ssvm_push_heap (fsh->ssvm_sh);
639       f = svm_fifo_alloc (min_size);
640       ssvm_pop_heap (oldheap);
641       if (f)
642         {
643           fsh_free_bytes_sub (fsh, fifo_sz);
644           goto done;
645         }
646     }
647   /* All failed, try to allocate min of data bytes and fifo sz */
648   fifo_sz = clib_min (fifo_sz, data_bytes);
649   if (fifo_sz <= fss->n_fl_chunk_bytes)
650     f = fs_try_alloc_fifo_freelist_multi_chunk (fsh, fss, fifo_sz);
651
652 done:
653   clib_spinlock_unlock (&fss->chunk_lock);
654
655   if (f)
656     {
657       f->size = data_bytes;
658       f->fs_hdr = fsh;
659     }
660   return f;
661 }
662
663 svm_fifo_chunk_t *
664 fsh_alloc_chunk (fifo_segment_header_t * fsh, u32 slice_index, u32 chunk_size)
665 {
666   fifo_segment_slice_t *fss;
667   svm_fifo_chunk_t *c;
668   void *oldheap;
669   int fl_index;
670   uword n_free;
671
672   fl_index = fs_freelist_for_size (chunk_size);
673   fss = fsh_slice_get (fsh, slice_index);
674
675   clib_spinlock_lock (&fss->chunk_lock);
676
677   c = fss->free_chunks[fl_index];
678
679   if (c)
680     {
681       fss->free_chunks[fl_index] = c->next;
682       c->next = 0;
683       fss->n_fl_chunk_bytes -= fs_freelist_index_to_size (fl_index);
684       fsh_cached_bytes_sub (fsh, fs_freelist_index_to_size (fl_index));
685     }
686   else if (chunk_size <= (n_free = fsh_n_free_bytes (fsh)))
687     {
688       fsh_check_mem (fsh);
689
690       chunk_size = fs_freelist_index_to_size (fl_index);
691       if (n_free < chunk_size)
692         goto done;
693
694       oldheap = ssvm_push_heap (fsh->ssvm_sh);
695       c = svm_fifo_chunk_alloc (chunk_size);
696       ssvm_pop_heap (oldheap);
697
698       if (!c)
699         goto done;
700
701       fsh_free_bytes_sub (fsh, chunk_size + sizeof (*c));
702     }
703   else if (chunk_size <= fss->n_fl_chunk_bytes)
704     {
705       c = fs_try_alloc_multi_chunk (fsh, fss, chunk_size);
706     }
707   else if (chunk_size <= fss->n_fl_chunk_bytes + n_free)
708     {
709       u32 min_size = FIFO_SEGMENT_MIN_FIFO_SIZE;
710       u32 batch;
711
712       fsh_check_mem (fsh);
713       batch = (chunk_size - fss->n_fl_chunk_bytes) / min_size;
714       batch = clib_min (batch + 1, n_free / min_size);
715       if (!fsh_try_alloc_chunk_batch (fsh, fss, 0, batch))
716         c = fs_try_alloc_multi_chunk (fsh, fss, chunk_size);
717     }
718
719 done:
720
721   clib_spinlock_unlock (&fss->chunk_lock);
722
723   return c;
724 }
725
726 static void
727 fsh_slice_collect_chunks (fifo_segment_header_t * fsh,
728                           fifo_segment_slice_t * fss, svm_fifo_chunk_t * c)
729 {
730   svm_fifo_chunk_t *next;
731   int fl_index;
732   u32 n_collect = 0;
733
734   clib_spinlock_lock (&fss->chunk_lock);
735
736   while (c)
737     {
738       next = c->next;
739       fl_index = fs_freelist_for_size (c->length);
740       c->next = fss->free_chunks[fl_index];
741       c->enq_rb_index = RBTREE_TNIL_INDEX;
742       c->deq_rb_index = RBTREE_TNIL_INDEX;
743       fss->free_chunks[fl_index] = c;
744       n_collect += fs_freelist_index_to_size (fl_index);
745       c = next;
746     }
747
748   fss->n_fl_chunk_bytes += n_collect;
749   fsh_cached_bytes_add (fsh, n_collect);
750
751   clib_spinlock_unlock (&fss->chunk_lock);
752 }
753
754 void
755 fsh_collect_chunks (fifo_segment_header_t * fsh, u32 slice_index,
756                     svm_fifo_chunk_t * c)
757 {
758   fifo_segment_slice_t *fss;
759   fss = fsh_slice_get (fsh, slice_index);
760   fsh_slice_collect_chunks (fsh, fss, c);
761 }
762
763 /**
764  * Allocate fifo in fifo segment
765  */
766 svm_fifo_t *
767 fifo_segment_alloc_fifo_w_slice (fifo_segment_t * fs, u32 slice_index,
768                                  u32 data_bytes, fifo_segment_ftype_t ftype)
769 {
770   fifo_segment_header_t *fsh = fs->h;
771   fifo_segment_slice_t *fss;
772   svm_fifo_t *f = 0;
773
774   ASSERT (slice_index < fs->n_slices);
775
776   fss = fsh_slice_get (fsh, slice_index);
777   f = fs_try_alloc_fifo (fsh, fss, data_bytes);
778   if (!f)
779     goto done;
780
781   f->slice_index = slice_index;
782
783   svm_fifo_init (f, data_bytes);
784
785   /* If rx fifo type add to active fifos list. When cleaning up segment,
786    * we need a list of active sessions that should be disconnected. Since
787    * both rx and tx fifos keep pointers to the session, it's enough to track
788    * only one. */
789   if (ftype == FIFO_SEGMENT_RX_FIFO)
790     {
791       if (fss->fifos)
792         {
793           fss->fifos->prev = f;
794           f->next = fss->fifos;
795         }
796       fss->fifos = f;
797       f->flags |= SVM_FIFO_F_LL_TRACKED;
798
799       svm_fifo_init_ooo_lookup (f, 0 /* ooo enq */ );
800     }
801   else
802     {
803       svm_fifo_init_ooo_lookup (f, 1 /* ooo deq */ );
804     }
805
806   fsh_active_fifos_update (fsh, 1);
807   fss->virtual_mem += svm_fifo_size (f);
808
809 done:
810   return (f);
811 }
812
813 /**
814  * Free fifo allocated in fifo segment
815  */
816 void
817 fifo_segment_free_fifo (fifo_segment_t * fs, svm_fifo_t * f)
818 {
819   fifo_segment_header_t *fsh = fs->h;
820   fifo_segment_slice_t *fss;
821
822   ASSERT (f->refcnt > 0);
823
824   if (--f->refcnt > 0)
825     return;
826
827   fss = fsh_slice_get (fsh, f->slice_index);
828
829   /* Remove from active list. Only rx fifos are tracked */
830   if (f->flags & SVM_FIFO_F_LL_TRACKED)
831     {
832       if (f->prev)
833         f->prev->next = f->next;
834       else
835         fss->fifos = f->next;
836       if (f->next)
837         f->next->prev = f->prev;
838       f->flags &= ~SVM_FIFO_F_LL_TRACKED;
839     }
840
841   /* Free fifo chunks */
842   fsh_slice_collect_chunks (fsh, fss, f->start_chunk);
843
844   f->start_chunk = f->end_chunk = 0;
845   f->head_chunk = f->tail_chunk = f->ooo_enq = f->ooo_deq = 0;
846
847   /* not allocated on segment heap */
848   svm_fifo_free_chunk_lookup (f);
849   svm_fifo_free_ooo_data (f);
850
851   if (CLIB_DEBUG)
852     {
853       f->master_session_index = ~0;
854       f->master_thread_index = ~0;
855     }
856
857   fss->virtual_mem -= svm_fifo_size (f);
858
859   /* Add to free list */
860   f->next = fss->free_fifos;
861   f->prev = 0;
862   fss->free_fifos = f;
863
864   fsh_active_fifos_update (fsh, -1);
865 }
866
867 int
868 fifo_segment_prealloc_fifo_hdrs (fifo_segment_t * fs, u32 slice_index,
869                                  u32 batch_size)
870 {
871   fifo_segment_header_t *fsh = fs->h;
872   fifo_segment_slice_t *fss;
873   svm_fifo_t *f;
874   void *oldheap;
875   uword size;
876   u8 *fmem;
877   int i;
878
879   fss = fsh_slice_get (fsh, slice_index);
880   size = (uword) (sizeof (*f)) * batch_size;
881
882   oldheap = ssvm_push_heap (fsh->ssvm_sh);
883   fmem = clib_mem_alloc_aligned_at_offset (size, CLIB_CACHE_LINE_BYTES,
884                                            0 /* align_offset */ ,
885                                            0 /* os_out_of_memory */ );
886   ssvm_pop_heap (oldheap);
887
888   /* Out of space.. */
889   if (fmem == 0)
890     return -1;
891
892   /* Carve fifo + chunk space */
893   for (i = 0; i < batch_size; i++)
894     {
895       f = (svm_fifo_t *) fmem;
896       memset (f, 0, sizeof (*f));
897       f->next = fss->free_fifos;
898       fss->free_fifos = f;
899       fmem += sizeof (*f);
900     }
901
902   fsh_free_bytes_sub (fsh, size);
903
904   return 0;
905 }
906
907 int
908 fifo_segment_prealloc_fifo_chunks (fifo_segment_t * fs, u32 slice_index,
909                                    u32 chunk_size, u32 batch_size)
910 {
911   fifo_segment_header_t *fsh = fs->h;
912   u32 rounded_data_size, fl_index;
913   fifo_segment_slice_t *fss;
914   svm_fifo_chunk_t *c;
915   void *oldheap;
916   uword size;
917   u8 *cmem;
918   int i;
919
920   if (!fs_chunk_size_is_valid (fsh, chunk_size))
921     {
922       clib_warning ("chunk size out of range %d", chunk_size);
923       return -1;
924     }
925
926   fl_index = fs_freelist_for_size (chunk_size);
927   rounded_data_size = fs_freelist_index_to_size (fl_index);
928   size = (uword) (sizeof (*c) + rounded_data_size) * batch_size;
929
930   oldheap = ssvm_push_heap (fsh->ssvm_sh);
931   cmem = clib_mem_alloc_aligned_at_offset (size, CLIB_CACHE_LINE_BYTES,
932                                            0 /* align_offset */ ,
933                                            0 /* os_out_of_memory */ );
934   ssvm_pop_heap (oldheap);
935
936   /* Out of space.. */
937   if (cmem == 0)
938     return -1;
939
940   fss = fsh_slice_get (fsh, slice_index);
941
942   /* Carve fifo + chunk space */
943   for (i = 0; i < batch_size; i++)
944     {
945       c = (svm_fifo_chunk_t *) cmem;
946       c->start_byte = 0;
947       c->length = rounded_data_size;
948       c->next = fss->free_chunks[fl_index];
949       fss->free_chunks[fl_index] = c;
950       cmem += sizeof (*c) + rounded_data_size;
951       fsh_cached_bytes_add (fsh, rounded_data_size);
952     }
953
954   fss->n_fl_chunk_bytes += batch_size * rounded_data_size;
955   fsh_free_bytes_sub (fsh, size);
956
957   return 0;
958 }
959
960 /**
961  * Pre-allocates fifo pairs in fifo segment
962  */
963 void
964 fifo_segment_preallocate_fifo_pairs (fifo_segment_t * fs,
965                                      u32 rx_fifo_size, u32 tx_fifo_size,
966                                      u32 * n_fifo_pairs)
967 {
968   u32 rx_rounded_data_size, tx_rounded_data_size, pair_size, pairs_to_alloc;
969   u32 hdrs, pairs_per_slice, alloc_now;
970   fifo_segment_header_t *fsh = fs->h;
971   int rx_fl_index, tx_fl_index, i;
972   fifo_segment_slice_t *fss;
973   uword space_available;
974
975   /* Parameter check */
976   if (rx_fifo_size == 0 || tx_fifo_size == 0 || *n_fifo_pairs == 0)
977     return;
978
979   if (!fs_chunk_size_is_valid (fsh, rx_fifo_size))
980     {
981       clib_warning ("rx fifo_size out of range %d", rx_fifo_size);
982       return;
983     }
984
985   if (!fs_chunk_size_is_valid (fsh, tx_fifo_size))
986     {
987       clib_warning ("tx fifo_size out of range %d", tx_fifo_size);
988       return;
989     }
990
991   rx_rounded_data_size = (1 << (max_log2 (rx_fifo_size)));
992   rx_fl_index = fs_freelist_for_size (rx_fifo_size);
993   tx_rounded_data_size = (1 << (max_log2 (tx_fifo_size)));
994   tx_fl_index = fs_freelist_for_size (tx_fifo_size);
995
996   hdrs = sizeof (svm_fifo_t) + sizeof (svm_fifo_chunk_t);
997
998   /* Calculate space requirements */
999   pair_size = 2 * hdrs + rx_rounded_data_size + tx_rounded_data_size;
1000   space_available = fsh_free_space (fsh);
1001   pairs_to_alloc = space_available / pair_size;
1002   pairs_to_alloc = clib_min (pairs_to_alloc, *n_fifo_pairs);
1003   pairs_per_slice = pairs_to_alloc / fs->n_slices;
1004   pairs_per_slice += pairs_to_alloc % fs->n_slices ? 1 : 0;
1005
1006   if (!pairs_per_slice)
1007     return;
1008
1009   for (i = 0; i < fs->n_slices; i++)
1010     {
1011       fss = fsh_slice_get (fsh, i);
1012       alloc_now = clib_min (pairs_per_slice, *n_fifo_pairs);
1013       if (fs_try_alloc_fifo_batch (fsh, fss, rx_fl_index, alloc_now))
1014         clib_warning ("rx prealloc failed: pairs %u", alloc_now);
1015       if (fs_try_alloc_fifo_batch (fsh, fss, tx_fl_index, alloc_now))
1016         clib_warning ("tx prealloc failed: pairs %u", alloc_now);
1017
1018       /* Account for the pairs allocated */
1019       *n_fifo_pairs -= alloc_now;
1020     }
1021 }
1022
1023 /**
1024  * Get number of active fifos
1025  */
1026 u32
1027 fifo_segment_num_fifos (fifo_segment_t * fs)
1028 {
1029   return clib_atomic_load_relax_n (&fs->h->n_active_fifos);
1030 }
1031
1032 static u32
1033 fs_slice_num_free_fifos (fifo_segment_slice_t * fss)
1034 {
1035   svm_fifo_t *f;
1036   u32 count = 0;
1037
1038   f = fss->free_fifos;
1039   if (f == 0)
1040     return 0;
1041
1042   while (f)
1043     {
1044       f = f->next;
1045       count++;
1046     }
1047   return count;
1048 }
1049
1050 u32
1051 fifo_segment_num_free_fifos (fifo_segment_t * fs)
1052 {
1053   fifo_segment_header_t *fsh = fs->h;
1054   fifo_segment_slice_t *fss;
1055   int slice_index;
1056   u32 count = 0;
1057
1058   for (slice_index = 0; slice_index < fs->n_slices; slice_index++)
1059     {
1060       fss = fsh_slice_get (fsh, slice_index);
1061       count += fs_slice_num_free_fifos (fss);
1062     }
1063   return count;
1064 }
1065
1066 static u32
1067 fs_slice_num_free_chunks (fifo_segment_slice_t * fss, u32 size)
1068 {
1069   u32 count = 0, rounded_size, fl_index;
1070   svm_fifo_chunk_t *c;
1071   int i;
1072
1073   /* Count all free chunks? */
1074   if (size == ~0)
1075     {
1076       for (i = 0; i < vec_len (fss->free_chunks); i++)
1077         {
1078           c = fss->free_chunks[i];
1079           if (c == 0)
1080             continue;
1081
1082           while (c)
1083             {
1084               c = c->next;
1085               count++;
1086             }
1087         }
1088       return count;
1089     }
1090
1091   rounded_size = (1 << (max_log2 (size)));
1092   fl_index = fs_freelist_for_size (rounded_size);
1093
1094   if (fl_index >= vec_len (fss->free_chunks))
1095     return 0;
1096
1097   c = fss->free_chunks[fl_index];
1098   if (c == 0)
1099     return 0;
1100
1101   while (c)
1102     {
1103       c = c->next;
1104       count++;
1105     }
1106   return count;
1107 }
1108
1109 u32
1110 fifo_segment_num_free_chunks (fifo_segment_t * fs, u32 size)
1111 {
1112   fifo_segment_header_t *fsh = fs->h;
1113   fifo_segment_slice_t *fss;
1114   int slice_index;
1115   u32 count = 0;
1116
1117   for (slice_index = 0; slice_index < fs->n_slices; slice_index++)
1118     {
1119       fss = fsh_slice_get (fsh, slice_index);
1120       count += fs_slice_num_free_chunks (fss, size);
1121     }
1122   return count;
1123 }
1124
1125 void
1126 fifo_segment_update_free_bytes (fifo_segment_t * fs)
1127 {
1128   fsh_update_free_bytes (fs->h);
1129 }
1130
1131 uword
1132 fifo_segment_size (fifo_segment_t * fs)
1133 {
1134   return fs->ssvm.ssvm_size;
1135 }
1136
1137 u8
1138 fsh_has_reached_mem_limit (fifo_segment_header_t * fsh)
1139 {
1140   return (fsh->flags & FIFO_SEGMENT_F_MEM_LIMIT) ? 1 : 0;
1141 }
1142
1143 void
1144 fsh_reset_mem_limit (fifo_segment_header_t * fsh)
1145 {
1146   fsh->flags &= ~FIFO_SEGMENT_F_MEM_LIMIT;
1147 }
1148
1149 uword
1150 fifo_segment_free_bytes (fifo_segment_t * fs)
1151 {
1152   return fsh_n_free_bytes (fs->h);
1153 }
1154
1155 uword
1156 fifo_segment_cached_bytes (fifo_segment_t * fs)
1157 {
1158   return fsh_n_cached_bytes (fs->h);
1159 }
1160
1161 uword
1162 fifo_segment_available_bytes (fifo_segment_t * fs)
1163 {
1164   return fsh_n_free_bytes (fs->h) + fsh_n_cached_bytes (fs->h);
1165 }
1166
1167 uword
1168 fifo_segment_fl_chunk_bytes (fifo_segment_t * fs)
1169 {
1170   fifo_segment_header_t *fsh = fs->h;
1171   fifo_segment_slice_t *fss;
1172   uword n_bytes = 0;
1173   int slice_index;
1174
1175   for (slice_index = 0; slice_index < fs->n_slices; slice_index++)
1176     {
1177       fss = fsh_slice_get (fsh, slice_index);
1178       n_bytes += fss->n_fl_chunk_bytes;
1179     }
1180
1181   return n_bytes;
1182 }
1183
1184 u8
1185 fifo_segment_has_fifos (fifo_segment_t * fs)
1186 {
1187   fifo_segment_header_t *fsh = fs->h;
1188   fifo_segment_slice_t *fss;
1189   int slice_index;
1190
1191   for (slice_index = 0; slice_index < fs->n_slices; slice_index++)
1192     {
1193       fss = fsh_slice_get (fsh, slice_index);
1194       if (fss->fifos)
1195         return 1;
1196     }
1197   return 0;
1198 }
1199
1200 svm_fifo_t *
1201 fifo_segment_get_slice_fifo_list (fifo_segment_t * fs, u32 slice_index)
1202 {
1203   fifo_segment_header_t *fsh = fs->h;
1204   fifo_segment_slice_t *fss;
1205
1206   fss = fsh_slice_get (fsh, slice_index);
1207   return fss->fifos;
1208 }
1209
1210 u8
1211 fifo_segment_get_mem_usage (fifo_segment_t * fs)
1212 {
1213   uword size, in_use;
1214
1215   size = fifo_segment_size (fs);
1216   in_use =
1217     size - fifo_segment_free_bytes (fs) - fifo_segment_cached_bytes (fs);
1218   return (in_use * 100) / size;
1219 }
1220
1221 fifo_segment_mem_status_t
1222 fifo_segment_determine_status (fifo_segment_header_t * fsh, u8 usage)
1223 {
1224   if (!fsh->high_watermark || !fsh->low_watermark)
1225     return MEMORY_PRESSURE_NO_PRESSURE;
1226
1227   /* once the no-memory is detected, the status continues
1228    * until memory usage gets below the high watermark
1229    */
1230   if (fsh_has_reached_mem_limit (fsh))
1231     {
1232       if (usage >= fsh->high_watermark)
1233         return MEMORY_PRESSURE_NO_MEMORY;
1234       else
1235         fsh_reset_mem_limit (fsh);
1236     }
1237
1238   if (usage >= fsh->high_watermark)
1239     return MEMORY_PRESSURE_HIGH_PRESSURE;
1240
1241   else if (usage >= fsh->low_watermark)
1242     return MEMORY_PRESSURE_LOW_PRESSURE;
1243
1244   return MEMORY_PRESSURE_NO_PRESSURE;
1245 }
1246
1247 fifo_segment_mem_status_t
1248 fifo_segment_get_mem_status (fifo_segment_t * fs)
1249 {
1250   fifo_segment_header_t *fsh = fs->h;
1251   u8 usage = fifo_segment_get_mem_usage (fs);
1252
1253   return fifo_segment_determine_status (fsh, usage);
1254 }
1255
1256 u8 *
1257 format_fifo_segment_type (u8 * s, va_list * args)
1258 {
1259   fifo_segment_t *sp;
1260   sp = va_arg (*args, fifo_segment_t *);
1261   ssvm_segment_type_t st = ssvm_type (&sp->ssvm);
1262
1263   if (st == SSVM_SEGMENT_PRIVATE)
1264     s = format (s, "%s", "private-heap");
1265   else if (st == SSVM_SEGMENT_MEMFD)
1266     s = format (s, "%s", "memfd");
1267   else if (st == SSVM_SEGMENT_SHM)
1268     s = format (s, "%s", "shm");
1269   else
1270     s = format (s, "%s", "unknown");
1271   return s;
1272 }
1273
1274 /**
1275  * Segment format function
1276  */
1277 u8 *
1278 format_fifo_segment (u8 * s, va_list * args)
1279 {
1280   u32 count, indent, active_fifos, free_fifos, fifo_hdr = 0;
1281   fifo_segment_t *fs = va_arg (*args, fifo_segment_t *);
1282   int verbose __attribute__ ((unused)) = va_arg (*args, int);
1283   uword est_chunk_bytes, est_free_seg_bytes, free_chunks;
1284   uword chunk_bytes = 0, free_seg_bytes, chunk_size;
1285   uword tracked_cached_bytes;
1286   fifo_segment_header_t *fsh;
1287   fifo_segment_slice_t *fss;
1288   svm_fifo_chunk_t *c;
1289   u32 slice_index;
1290   char *address;
1291   size_t size;
1292   int i;
1293   uword allocated, in_use, virt;
1294   f64 usage;
1295   fifo_segment_mem_status_t mem_st;
1296
1297   indent = format_get_indent (s) + 2;
1298
1299   if (fs == 0)
1300     {
1301       s = format (s, "%-15s%15s%15s%15s%15s%15s", "Name", "Type",
1302                   "HeapSize (M)", "ActiveFifos", "FreeFifos", "Address");
1303       return s;
1304     }
1305
1306   fifo_segment_info (fs, &address, &size);
1307   active_fifos = fifo_segment_num_fifos (fs);
1308   free_fifos = fifo_segment_num_free_fifos (fs);
1309
1310   s = format (s, "%-15v%15U%15llu%15u%15u%15llx", ssvm_name (&fs->ssvm),
1311               format_fifo_segment_type, fs, size >> 20ULL, active_fifos,
1312               free_fifos, address);
1313
1314   if (!verbose)
1315     return s;
1316
1317   fsh = fs->h;
1318
1319   free_chunks = fifo_segment_num_free_chunks (fs, ~0);
1320   if (free_chunks)
1321     s = format (s, "\n\n%UFree chunks by size:\n", format_white_space,
1322                 indent + 2);
1323   else
1324     s = format (s, "\n");
1325
1326   for (slice_index = 0; slice_index < fs->n_slices; slice_index++)
1327     {
1328       fss = fsh_slice_get (fsh, slice_index);
1329       for (i = 0; i < vec_len (fss->free_chunks); i++)
1330         {
1331           c = fss->free_chunks[i];
1332           if (c == 0)
1333             continue;
1334           count = 0;
1335           while (c)
1336             {
1337               c = c->next;
1338               count++;
1339             }
1340
1341           chunk_size = fs_freelist_index_to_size (i);
1342           s = format (s, "%U%-5u kB: %u\n", format_white_space, indent + 2,
1343                       chunk_size >> 10, count);
1344
1345           chunk_bytes += count * chunk_size;
1346         }
1347     }
1348
1349   fifo_hdr = free_fifos * sizeof (svm_fifo_t);
1350   est_chunk_bytes = fifo_segment_fl_chunk_bytes (fs);
1351   est_free_seg_bytes = fifo_segment_free_bytes (fs);
1352   fifo_segment_update_free_bytes (fs);
1353   free_seg_bytes = fifo_segment_free_bytes (fs);
1354   tracked_cached_bytes = fifo_segment_cached_bytes (fs);
1355   allocated = fifo_segment_size (fs);
1356   in_use = fifo_segment_size (fs) - est_free_seg_bytes - tracked_cached_bytes;
1357   usage = (100.0 * in_use) / allocated;
1358   mem_st = fifo_segment_get_mem_status (fs);
1359   virt = fsh_virtual_mem (fsh);
1360
1361   s = format (s, "\n%Useg free bytes: %U (%lu) estimated: %U (%lu) reserved:"
1362               " %U (%lu)\n", format_white_space, indent + 2,
1363               format_memory_size, free_seg_bytes, free_seg_bytes,
1364               format_memory_size, est_free_seg_bytes, est_free_seg_bytes,
1365               format_memory_size, fsh->n_reserved_bytes,
1366               fsh->n_reserved_bytes);
1367   s = format (s, "%Uchunk free bytes: %U (%lu) estimated: %U (%lu) tracked:"
1368               " %U (%lu)\n", format_white_space, indent + 2,
1369               format_memory_size, chunk_bytes, chunk_bytes,
1370               format_memory_size, est_chunk_bytes, est_chunk_bytes,
1371               format_memory_size, tracked_cached_bytes, tracked_cached_bytes);
1372   s = format (s, "%Ufifo active: %u hdr free bytes: %U (%u) \n",
1373               format_white_space, indent + 2, fsh->n_active_fifos,
1374               format_memory_size, fifo_hdr, fifo_hdr);
1375   s = format (s, "%Usegment usage: %.2f%% (%U / %U) virt: %U status: %s\n",
1376               format_white_space, indent + 2, usage, format_memory_size,
1377               in_use, format_memory_size, allocated, format_memory_size, virt,
1378               fifo_segment_mem_status_strings[mem_st]);
1379   s = format (s, "\n");
1380
1381   return s;
1382 }
1383
1384 /*
1385  * fd.io coding-style-patch-verification: ON
1386  *
1387  * Local Variables:
1388  * eval: (c-set-style "gnu")
1389  * End:
1390  */