Skip to content
  • Markus Armbruster's avatar
    129c7d1c
    block: Document -drive problematic code and bugs · 129c7d1c
    Markus Armbruster authored
    
    
    -blockdev and blockdev_add convert their arguments via QObject to
    BlockdevOptions for qmp_blockdev_add(), which converts them back to
    QObject, then to a flattened QDict.  The QDict's members are typed
    according to the QAPI schema.
    
    -drive converts its argument via QemuOpts to a (flat) QDict.  This
    QDict's members are all QString.
    
    Thus, the QType of a flat QDict member depends on whether it comes
    from -drive or -blockdev/blockdev_add, except when the QAPI type maps
    to QString, which is the case for 'str' and enumeration types.
    
    The block layer core extracts generic configuration from the flat
    QDict, and the block driver extracts driver-specific configuration.
    
    Both commonly do so by converting (parts of) the flat QDict to
    QemuOpts, which turns all values into strings.  Not exactly elegant,
    but correct.
    
    However, A few places access the flat QDict directly:
    
    * Most of them access members that are always QString.  Correct.
    
    * bdrv_open_inherit() accesses a boolean, carefully.  Correct.
    
    * nfs_config() uses a QObject input visitor.  Correct only because the
      visited type contains nothing but QStrings.
    
    * nbd_config() and ssh_config() use a QObject input visitor, and the
      visited types contain non-QStrings: InetSocketAddress members
      @numeric, @to, @ipv4, @ipv6.  -drive works as long as you don't try
      to use them (they're all optional).  @to is ignored anyway.
    
      Reproducer:
      -drive driver=ssh,server.host=h,server.port=22,server.ipv4,path=p
      -drive driver=nbd,server.type=inet,server.data.host=h,server.data.port=22,server.data.ipv4
      both fail with "Invalid parameter type for 'data.ipv4', expected: boolean"
    
    Add suitable comments to all these places.  Mark the buggy ones FIXME.
    
    "Fortunately", -drive's driver-specific options are entirely
    undocumented.
    
    Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
    Message-id: 1490895797-29094-5-git-send-email-armbru@redhat.com
    [mreitz: Fixed two typos]
    Reviewed-by: default avatarEric Blake <eblake@redhat.com>
    Signed-off-by: default avatarMax Reitz <mreitz@redhat.com>
    129c7d1c
    block: Document -drive problematic code and bugs
    Markus Armbruster authored
    
    
    -blockdev and blockdev_add convert their arguments via QObject to
    BlockdevOptions for qmp_blockdev_add(), which converts them back to
    QObject, then to a flattened QDict.  The QDict's members are typed
    according to the QAPI schema.
    
    -drive converts its argument via QemuOpts to a (flat) QDict.  This
    QDict's members are all QString.
    
    Thus, the QType of a flat QDict member depends on whether it comes
    from -drive or -blockdev/blockdev_add, except when the QAPI type maps
    to QString, which is the case for 'str' and enumeration types.
    
    The block layer core extracts generic configuration from the flat
    QDict, and the block driver extracts driver-specific configuration.
    
    Both commonly do so by converting (parts of) the flat QDict to
    QemuOpts, which turns all values into strings.  Not exactly elegant,
    but correct.
    
    However, A few places access the flat QDict directly:
    
    * Most of them access members that are always QString.  Correct.
    
    * bdrv_open_inherit() accesses a boolean, carefully.  Correct.
    
    * nfs_config() uses a QObject input visitor.  Correct only because the
      visited type contains nothing but QStrings.
    
    * nbd_config() and ssh_config() use a QObject input visitor, and the
      visited types contain non-QStrings: InetSocketAddress members
      @numeric, @to, @ipv4, @ipv6.  -drive works as long as you don't try
      to use them (they're all optional).  @to is ignored anyway.
    
      Reproducer:
      -drive driver=ssh,server.host=h,server.port=22,server.ipv4,path=p
      -drive driver=nbd,server.type=inet,server.data.host=h,server.data.port=22,server.data.ipv4
      both fail with "Invalid parameter type for 'data.ipv4', expected: boolean"
    
    Add suitable comments to all these places.  Mark the buggy ones FIXME.
    
    "Fortunately", -drive's driver-specific options are entirely
    undocumented.
    
    Signed-off-by: default avatarMarkus Armbruster <armbru@redhat.com>
    Message-id: 1490895797-29094-5-git-send-email-armbru@redhat.com
    [mreitz: Fixed two typos]
    Reviewed-by: default avatarEric Blake <eblake@redhat.com>
    Signed-off-by: default avatarMax Reitz <mreitz@redhat.com>
Loading