qemu/hw/ppc/spapr_vio.c
<<
>>
Prefs
   1/*
   2 * QEMU sPAPR VIO code
   3 *
   4 * Copyright (c) 2010 David Gibson, IBM Corporation <dwg@au1.ibm.com>
   5 * Based on the s390 virtio bus code:
   6 * Copyright (c) 2009 Alexander Graf <agraf@suse.de>
   7 *
   8 * This library is free software; you can redistribute it and/or
   9 * modify it under the terms of the GNU Lesser General Public
  10 * License as published by the Free Software Foundation; either
  11 * version 2 of the License, or (at your option) any later version.
  12 *
  13 * This library is distributed in the hope that it will be useful,
  14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 * Lesser General Public License for more details.
  17 *
  18 * You should have received a copy of the GNU Lesser General Public
  19 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  20 */
  21
  22#include "hw/hw.h"
  23#include "sysemu/sysemu.h"
  24#include "hw/boards.h"
  25#include "monitor/monitor.h"
  26#include "hw/loader.h"
  27#include "elf.h"
  28#include "hw/sysbus.h"
  29#include "sysemu/kvm.h"
  30#include "sysemu/device_tree.h"
  31#include "kvm_ppc.h"
  32
  33#include "hw/ppc/spapr.h"
  34#include "hw/ppc/spapr_vio.h"
  35#include "hw/ppc/xics.h"
  36
  37#include <libfdt.h>
  38
  39/* #define DEBUG_SPAPR */
  40
  41#ifdef DEBUG_SPAPR
  42#define DPRINTF(fmt, ...) \
  43    do { fprintf(stderr, fmt, ## __VA_ARGS__); } while (0)
  44#else
  45#define DPRINTF(fmt, ...) \
  46    do { } while (0)
  47#endif
  48
  49static Property spapr_vio_props[] = {
  50    DEFINE_PROP_UINT32("irq", VIOsPAPRDevice, irq, 0), \
  51    DEFINE_PROP_END_OF_LIST(),
  52};
  53
  54static char *spapr_vio_get_dev_name(DeviceState *qdev)
  55{
  56    VIOsPAPRDevice *dev = VIO_SPAPR_DEVICE(qdev);
  57    VIOsPAPRDeviceClass *pc = VIO_SPAPR_DEVICE_GET_CLASS(dev);
  58    char *name;
  59
  60    /* Device tree style name device@reg */
  61    name = g_strdup_printf("%s@%x", pc->dt_name, dev->reg);
  62
  63    return name;
  64}
  65
  66static void spapr_vio_bus_class_init(ObjectClass *klass, void *data)
  67{
  68    BusClass *k = BUS_CLASS(klass);
  69
  70    k->get_dev_path = spapr_vio_get_dev_name;
  71}
  72
  73static const TypeInfo spapr_vio_bus_info = {
  74    .name = TYPE_SPAPR_VIO_BUS,
  75    .parent = TYPE_BUS,
  76    .class_init = spapr_vio_bus_class_init,
  77    .instance_size = sizeof(VIOsPAPRBus),
  78};
  79
  80VIOsPAPRDevice *spapr_vio_find_by_reg(VIOsPAPRBus *bus, uint32_t reg)
  81{
  82    BusChild *kid;
  83    VIOsPAPRDevice *dev = NULL;
  84
  85    QTAILQ_FOREACH(kid, &bus->bus.children, sibling) {
  86        dev = (VIOsPAPRDevice *)kid->child;
  87        if (dev->reg == reg) {
  88            return dev;
  89        }
  90    }
  91
  92    return NULL;
  93}
  94
  95static int vio_make_devnode(VIOsPAPRDevice *dev,
  96                            void *fdt)
  97{
  98    VIOsPAPRDeviceClass *pc = VIO_SPAPR_DEVICE_GET_CLASS(dev);
  99    int vdevice_off, node_off, ret;
 100    char *dt_name;
 101
 102    vdevice_off = fdt_path_offset(fdt, "/vdevice");
 103    if (vdevice_off < 0) {
 104        return vdevice_off;
 105    }
 106
 107    dt_name = spapr_vio_get_dev_name(DEVICE(dev));
 108    node_off = fdt_add_subnode(fdt, vdevice_off, dt_name);
 109    g_free(dt_name);
 110    if (node_off < 0) {
 111        return node_off;
 112    }
 113
 114    ret = fdt_setprop_cell(fdt, node_off, "reg", dev->reg);
 115    if (ret < 0) {
 116        return ret;
 117    }
 118
 119    if (pc->dt_type) {
 120        ret = fdt_setprop_string(fdt, node_off, "device_type",
 121                                 pc->dt_type);
 122        if (ret < 0) {
 123            return ret;
 124        }
 125    }
 126
 127    if (pc->dt_compatible) {
 128        ret = fdt_setprop_string(fdt, node_off, "compatible",
 129                                 pc->dt_compatible);
 130        if (ret < 0) {
 131            return ret;
 132        }
 133    }
 134
 135    if (dev->irq) {
 136        uint32_t ints_prop[] = {cpu_to_be32(dev->irq), 0};
 137
 138        ret = fdt_setprop(fdt, node_off, "interrupts", ints_prop,
 139                          sizeof(ints_prop));
 140        if (ret < 0) {
 141            return ret;
 142        }
 143    }
 144
 145    ret = spapr_tcet_dma_dt(fdt, node_off, "ibm,my-dma-window", dev->tcet);
 146    if (ret < 0) {
 147        return ret;
 148    }
 149
 150    if (pc->devnode) {
 151        ret = (pc->devnode)(dev, fdt, node_off);
 152        if (ret < 0) {
 153            return ret;
 154        }
 155    }
 156
 157    return node_off;
 158}
 159
 160/*
 161 * CRQ handling
 162 */
 163static target_ulong h_reg_crq(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 164                              target_ulong opcode, target_ulong *args)
 165{
 166    target_ulong reg = args[0];
 167    target_ulong queue_addr = args[1];
 168    target_ulong queue_len = args[2];
 169    VIOsPAPRDevice *dev = spapr_vio_find_by_reg(spapr->vio_bus, reg);
 170
 171    if (!dev) {
 172        hcall_dprintf("Unit 0x" TARGET_FMT_lx " does not exist\n", reg);
 173        return H_PARAMETER;
 174    }
 175
 176    /* We can't grok a queue size bigger than 256M for now */
 177    if (queue_len < 0x1000 || queue_len > 0x10000000) {
 178        hcall_dprintf("Queue size too small or too big (0x" TARGET_FMT_lx
 179                      ")\n", queue_len);
 180        return H_PARAMETER;
 181    }
 182
 183    /* Check queue alignment */
 184    if (queue_addr & 0xfff) {
 185        hcall_dprintf("Queue not aligned (0x" TARGET_FMT_lx ")\n", queue_addr);
 186        return H_PARAMETER;
 187    }
 188
 189    /* Check if device supports CRQs */
 190    if (!dev->crq.SendFunc) {
 191        hcall_dprintf("Device does not support CRQ\n");
 192        return H_NOT_FOUND;
 193    }
 194
 195    /* Already a queue ? */
 196    if (dev->crq.qsize) {
 197        hcall_dprintf("CRQ already registered\n");
 198        return H_RESOURCE;
 199    }
 200    dev->crq.qladdr = queue_addr;
 201    dev->crq.qsize = queue_len;
 202    dev->crq.qnext = 0;
 203
 204    DPRINTF("CRQ for dev 0x" TARGET_FMT_lx " registered at 0x"
 205            TARGET_FMT_lx "/0x" TARGET_FMT_lx "\n",
 206            reg, queue_addr, queue_len);
 207    return H_SUCCESS;
 208}
 209
 210static target_ulong free_crq(VIOsPAPRDevice *dev)
 211{
 212    dev->crq.qladdr = 0;
 213    dev->crq.qsize = 0;
 214    dev->crq.qnext = 0;
 215
 216    DPRINTF("CRQ for dev 0x%" PRIx32 " freed\n", dev->reg);
 217
 218    return H_SUCCESS;
 219}
 220
 221static target_ulong h_free_crq(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 222                               target_ulong opcode, target_ulong *args)
 223{
 224    target_ulong reg = args[0];
 225    VIOsPAPRDevice *dev = spapr_vio_find_by_reg(spapr->vio_bus, reg);
 226
 227    if (!dev) {
 228        hcall_dprintf("Unit 0x" TARGET_FMT_lx " does not exist\n", reg);
 229        return H_PARAMETER;
 230    }
 231
 232    return free_crq(dev);
 233}
 234
 235static target_ulong h_send_crq(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 236                               target_ulong opcode, target_ulong *args)
 237{
 238    target_ulong reg = args[0];
 239    target_ulong msg_hi = args[1];
 240    target_ulong msg_lo = args[2];
 241    VIOsPAPRDevice *dev = spapr_vio_find_by_reg(spapr->vio_bus, reg);
 242    uint64_t crq_mangle[2];
 243
 244    if (!dev) {
 245        hcall_dprintf("Unit 0x" TARGET_FMT_lx " does not exist\n", reg);
 246        return H_PARAMETER;
 247    }
 248    crq_mangle[0] = cpu_to_be64(msg_hi);
 249    crq_mangle[1] = cpu_to_be64(msg_lo);
 250
 251    if (dev->crq.SendFunc) {
 252        return dev->crq.SendFunc(dev, (uint8_t *)crq_mangle);
 253    }
 254
 255    return H_HARDWARE;
 256}
 257
 258static target_ulong h_enable_crq(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 259                                 target_ulong opcode, target_ulong *args)
 260{
 261    target_ulong reg = args[0];
 262    VIOsPAPRDevice *dev = spapr_vio_find_by_reg(spapr->vio_bus, reg);
 263
 264    if (!dev) {
 265        hcall_dprintf("Unit 0x" TARGET_FMT_lx " does not exist\n", reg);
 266        return H_PARAMETER;
 267    }
 268
 269    return 0;
 270}
 271
 272/* Returns negative error, 0 success, or positive: queue full */
 273int spapr_vio_send_crq(VIOsPAPRDevice *dev, uint8_t *crq)
 274{
 275    int rc;
 276    uint8_t byte;
 277
 278    if (!dev->crq.qsize) {
 279        fprintf(stderr, "spapr_vio_send_creq on uninitialized queue\n");
 280        return -1;
 281    }
 282
 283    /* Maybe do a fast path for KVM just writing to the pages */
 284    rc = spapr_vio_dma_read(dev, dev->crq.qladdr + dev->crq.qnext, &byte, 1);
 285    if (rc) {
 286        return rc;
 287    }
 288    if (byte != 0) {
 289        return 1;
 290    }
 291
 292    rc = spapr_vio_dma_write(dev, dev->crq.qladdr + dev->crq.qnext + 8,
 293                             &crq[8], 8);
 294    if (rc) {
 295        return rc;
 296    }
 297
 298    kvmppc_eieio();
 299
 300    rc = spapr_vio_dma_write(dev, dev->crq.qladdr + dev->crq.qnext, crq, 8);
 301    if (rc) {
 302        return rc;
 303    }
 304
 305    dev->crq.qnext = (dev->crq.qnext + 16) % dev->crq.qsize;
 306
 307    if (dev->signal_state & 1) {
 308        qemu_irq_pulse(spapr_vio_qirq(dev));
 309    }
 310
 311    return 0;
 312}
 313
 314/* "quiesce" handling */
 315
 316static void spapr_vio_quiesce_one(VIOsPAPRDevice *dev)
 317{
 318    if (dev->tcet) {
 319        device_reset(DEVICE(dev->tcet));
 320    }
 321    free_crq(dev);
 322}
 323
 324static void rtas_set_tce_bypass(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 325                                uint32_t token,
 326                                uint32_t nargs, target_ulong args,
 327                                uint32_t nret, target_ulong rets)
 328{
 329    VIOsPAPRBus *bus = spapr->vio_bus;
 330    VIOsPAPRDevice *dev;
 331    uint32_t unit, enable;
 332
 333    if (nargs != 2) {
 334        rtas_st(rets, 0, -3);
 335        return;
 336    }
 337    unit = rtas_ld(args, 0);
 338    enable = rtas_ld(args, 1);
 339    dev = spapr_vio_find_by_reg(bus, unit);
 340    if (!dev) {
 341        rtas_st(rets, 0, -3);
 342        return;
 343    }
 344
 345    if (!dev->tcet) {
 346        rtas_st(rets, 0, -3);
 347        return;
 348    }
 349
 350    spapr_tce_set_bypass(dev->tcet, !!enable);
 351
 352    rtas_st(rets, 0, 0);
 353}
 354
 355static void rtas_quiesce(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 356                         uint32_t token,
 357                         uint32_t nargs, target_ulong args,
 358                         uint32_t nret, target_ulong rets)
 359{
 360    VIOsPAPRBus *bus = spapr->vio_bus;
 361    BusChild *kid;
 362    VIOsPAPRDevice *dev = NULL;
 363
 364    if (nargs != 0) {
 365        rtas_st(rets, 0, -3);
 366        return;
 367    }
 368
 369    QTAILQ_FOREACH(kid, &bus->bus.children, sibling) {
 370        dev = (VIOsPAPRDevice *)kid->child;
 371        spapr_vio_quiesce_one(dev);
 372    }
 373
 374    rtas_st(rets, 0, 0);
 375}
 376
 377static VIOsPAPRDevice *reg_conflict(VIOsPAPRDevice *dev)
 378{
 379    VIOsPAPRBus *bus = DO_UPCAST(VIOsPAPRBus, bus, dev->qdev.parent_bus);
 380    BusChild *kid;
 381    VIOsPAPRDevice *other;
 382
 383    /*
 384     * Check for a device other than the given one which is already
 385     * using the requested address. We have to open code this because
 386     * the given dev might already be in the list.
 387     */
 388    QTAILQ_FOREACH(kid, &bus->bus.children, sibling) {
 389        other = VIO_SPAPR_DEVICE(kid->child);
 390
 391        if (other != dev && other->reg == dev->reg) {
 392            return other;
 393        }
 394    }
 395
 396    return 0;
 397}
 398
 399static void spapr_vio_busdev_reset(DeviceState *qdev)
 400{
 401    VIOsPAPRDevice *dev = VIO_SPAPR_DEVICE(qdev);
 402    VIOsPAPRDeviceClass *pc = VIO_SPAPR_DEVICE_GET_CLASS(dev);
 403
 404    /* Shut down the request queue and TCEs if necessary */
 405    spapr_vio_quiesce_one(dev);
 406
 407    dev->signal_state = 0;
 408
 409    if (pc->reset) {
 410        pc->reset(dev);
 411    }
 412}
 413
 414static int spapr_vio_busdev_init(DeviceState *qdev)
 415{
 416    VIOsPAPRDevice *dev = (VIOsPAPRDevice *)qdev;
 417    VIOsPAPRDeviceClass *pc = VIO_SPAPR_DEVICE_GET_CLASS(dev);
 418    char *id;
 419
 420    if (dev->reg != -1) {
 421        /*
 422         * Explicitly assigned address, just verify that no-one else
 423         * is using it.  other mechanism). We have to open code this
 424         * rather than using spapr_vio_find_by_reg() because sdev
 425         * itself is already in the list.
 426         */
 427        VIOsPAPRDevice *other = reg_conflict(dev);
 428
 429        if (other) {
 430            fprintf(stderr, "vio: %s and %s devices conflict at address %#x\n",
 431                    object_get_typename(OBJECT(qdev)),
 432                    object_get_typename(OBJECT(&other->qdev)),
 433                    dev->reg);
 434            return -1;
 435        }
 436    } else {
 437        /* Need to assign an address */
 438        VIOsPAPRBus *bus = DO_UPCAST(VIOsPAPRBus, bus, dev->qdev.parent_bus);
 439
 440        do {
 441            dev->reg = bus->next_reg++;
 442        } while (reg_conflict(dev));
 443    }
 444
 445    /* Don't overwrite ids assigned on the command line */
 446    if (!dev->qdev.id) {
 447        id = spapr_vio_get_dev_name(DEVICE(dev));
 448        dev->qdev.id = id;
 449    }
 450
 451    dev->irq = spapr_allocate_msi(dev->irq);
 452    if (!dev->irq) {
 453        return -1;
 454    }
 455
 456    if (pc->rtce_window_size) {
 457        uint32_t liobn = SPAPR_VIO_BASE_LIOBN | dev->reg;
 458        dev->tcet = spapr_tce_new_table(qdev, liobn, pc->rtce_window_size);
 459        address_space_init(&dev->as, spapr_tce_get_iommu(dev->tcet), qdev->id);
 460    }
 461
 462    return pc->init(dev);
 463}
 464
 465static target_ulong h_vio_signal(PowerPCCPU *cpu, sPAPREnvironment *spapr,
 466                                 target_ulong opcode,
 467                                 target_ulong *args)
 468{
 469    target_ulong reg = args[0];
 470    target_ulong mode = args[1];
 471    VIOsPAPRDevice *dev = spapr_vio_find_by_reg(spapr->vio_bus, reg);
 472    VIOsPAPRDeviceClass *pc;
 473
 474    if (!dev) {
 475        return H_PARAMETER;
 476    }
 477
 478    pc = VIO_SPAPR_DEVICE_GET_CLASS(dev);
 479
 480    if (mode & ~pc->signal_mask) {
 481        return H_PARAMETER;
 482    }
 483
 484    dev->signal_state = mode;
 485
 486    return H_SUCCESS;
 487}
 488
 489VIOsPAPRBus *spapr_vio_bus_init(void)
 490{
 491    VIOsPAPRBus *bus;
 492    BusState *qbus;
 493    DeviceState *dev;
 494
 495    /* Create bridge device */
 496    dev = qdev_create(NULL, "spapr-vio-bridge");
 497    qdev_init_nofail(dev);
 498
 499    /* Create bus on bridge device */
 500
 501    qbus = qbus_create(TYPE_SPAPR_VIO_BUS, dev, "spapr-vio");
 502    bus = DO_UPCAST(VIOsPAPRBus, bus, qbus);
 503    bus->next_reg = 0x71000000;
 504
 505    /* hcall-vio */
 506    spapr_register_hypercall(H_VIO_SIGNAL, h_vio_signal);
 507
 508    /* hcall-crq */
 509    spapr_register_hypercall(H_REG_CRQ, h_reg_crq);
 510    spapr_register_hypercall(H_FREE_CRQ, h_free_crq);
 511    spapr_register_hypercall(H_SEND_CRQ, h_send_crq);
 512    spapr_register_hypercall(H_ENABLE_CRQ, h_enable_crq);
 513
 514    /* RTAS calls */
 515    spapr_rtas_register("ibm,set-tce-bypass", rtas_set_tce_bypass);
 516    spapr_rtas_register("quiesce", rtas_quiesce);
 517
 518    return bus;
 519}
 520
 521/* Represents sPAPR hcall VIO devices */
 522
 523static int spapr_vio_bridge_init(SysBusDevice *dev)
 524{
 525    /* nothing */
 526    return 0;
 527}
 528
 529static void spapr_vio_bridge_class_init(ObjectClass *klass, void *data)
 530{
 531    DeviceClass *dc = DEVICE_CLASS(klass);
 532    SysBusDeviceClass *k = SYS_BUS_DEVICE_CLASS(klass);
 533
 534    k->init = spapr_vio_bridge_init;
 535    dc->no_user = 1;
 536}
 537
 538static const TypeInfo spapr_vio_bridge_info = {
 539    .name          = "spapr-vio-bridge",
 540    .parent        = TYPE_SYS_BUS_DEVICE,
 541    .instance_size = sizeof(SysBusDevice),
 542    .class_init    = spapr_vio_bridge_class_init,
 543};
 544
 545const VMStateDescription vmstate_spapr_vio = {
 546    .name = "spapr_vio",
 547    .version_id = 1,
 548    .minimum_version_id = 1,
 549    .minimum_version_id_old = 1,
 550    .fields      = (VMStateField []) {
 551        /* Sanity check */
 552        VMSTATE_UINT32_EQUAL(reg, VIOsPAPRDevice),
 553        VMSTATE_UINT32_EQUAL(irq, VIOsPAPRDevice),
 554
 555        /* General VIO device state */
 556        VMSTATE_UINTTL(signal_state, VIOsPAPRDevice),
 557        VMSTATE_UINT64(crq.qladdr, VIOsPAPRDevice),
 558        VMSTATE_UINT32(crq.qsize, VIOsPAPRDevice),
 559        VMSTATE_UINT32(crq.qnext, VIOsPAPRDevice),
 560
 561        VMSTATE_END_OF_LIST()
 562    },
 563};
 564
 565static void vio_spapr_device_class_init(ObjectClass *klass, void *data)
 566{
 567    DeviceClass *k = DEVICE_CLASS(klass);
 568    k->init = spapr_vio_busdev_init;
 569    k->reset = spapr_vio_busdev_reset;
 570    k->bus_type = TYPE_SPAPR_VIO_BUS;
 571    k->props = spapr_vio_props;
 572}
 573
 574static const TypeInfo spapr_vio_type_info = {
 575    .name = TYPE_VIO_SPAPR_DEVICE,
 576    .parent = TYPE_DEVICE,
 577    .instance_size = sizeof(VIOsPAPRDevice),
 578    .abstract = true,
 579    .class_size = sizeof(VIOsPAPRDeviceClass),
 580    .class_init = vio_spapr_device_class_init,
 581};
 582
 583static void spapr_vio_register_types(void)
 584{
 585    type_register_static(&spapr_vio_bus_info);
 586    type_register_static(&spapr_vio_bridge_info);
 587    type_register_static(&spapr_vio_type_info);
 588}
 589
 590type_init(spapr_vio_register_types)
 591
 592static int compare_reg(const void *p1, const void *p2)
 593{
 594    VIOsPAPRDevice const *dev1, *dev2;
 595
 596    dev1 = (VIOsPAPRDevice *)*(DeviceState **)p1;
 597    dev2 = (VIOsPAPRDevice *)*(DeviceState **)p2;
 598
 599    if (dev1->reg < dev2->reg) {
 600        return -1;
 601    }
 602    if (dev1->reg == dev2->reg) {
 603        return 0;
 604    }
 605
 606    /* dev1->reg > dev2->reg */
 607    return 1;
 608}
 609
 610int spapr_populate_vdevice(VIOsPAPRBus *bus, void *fdt)
 611{
 612    DeviceState *qdev, **qdevs;
 613    BusChild *kid;
 614    int i, num, ret = 0;
 615
 616    /* Count qdevs on the bus list */
 617    num = 0;
 618    QTAILQ_FOREACH(kid, &bus->bus.children, sibling) {
 619        num++;
 620    }
 621
 622    /* Copy out into an array of pointers */
 623    qdevs = g_malloc(sizeof(qdev) * num);
 624    num = 0;
 625    QTAILQ_FOREACH(kid, &bus->bus.children, sibling) {
 626        qdevs[num++] = kid->child;
 627    }
 628
 629    /* Sort the array */
 630    qsort(qdevs, num, sizeof(qdev), compare_reg);
 631
 632    /* Hack alert. Give the devices to libfdt in reverse order, we happen
 633     * to know that will mean they are in forward order in the tree. */
 634    for (i = num - 1; i >= 0; i--) {
 635        VIOsPAPRDevice *dev = (VIOsPAPRDevice *)(qdevs[i]);
 636
 637        ret = vio_make_devnode(dev, fdt);
 638
 639        if (ret < 0) {
 640            goto out;
 641        }
 642    }
 643
 644    ret = 0;
 645out:
 646    free(qdevs);
 647
 648    return ret;
 649}
 650
 651int spapr_populate_chosen_stdout(void *fdt, VIOsPAPRBus *bus)
 652{
 653    VIOsPAPRDevice *dev;
 654    char *name, *path;
 655    int ret, offset;
 656
 657    dev = spapr_vty_get_default(bus);
 658    if (!dev)
 659        return 0;
 660
 661    offset = fdt_path_offset(fdt, "/chosen");
 662    if (offset < 0) {
 663        return offset;
 664    }
 665
 666    name = spapr_vio_get_dev_name(DEVICE(dev));
 667    path = g_strdup_printf("/vdevice/%s", name);
 668
 669    ret = fdt_setprop_string(fdt, offset, "linux,stdout-path", path);
 670
 671    g_free(name);
 672    g_free(path);
 673
 674    return ret;
 675}
 676