Add '-device help' output for device params and help text
cover Add '-device help' output for device params and help text
Hello,
This patch series adds support to specify some descriptive help text to qdev device parameters. This series adds some help text to the virtserialport and net family of devices as an example, and the new output is shown in the respective commits.
This series also adds a new '-device help' option that lists all the available qdev devices (which is avl. via -device ? now), and adds each device's parameters to the output listing. This output also shows the descriptive text.
The idea is to auto-generate documentation from code and to populate some wiki / qemu-doc.texi using this new target.
Changes from previous send:
- Removed the 'RFC' tag
- Not using macros in net.h (Markus)
It'll be helpful to have people submit some short descriptive text for the subsystems they care about.
Amit Shah (5):
qdev: Add a description field for qdev properties for documentation
virtio-serial: Add description fields for qdev properties net.h: Add description fields for qdev properites
qdev: Re-arrange code to have device properties shown from own
function
qdev: Add new '-device help' option, shows all devices and properties
block_int.h | 10 +++--- hw/a9mpcore.c | 2 +- hw/acpi_piix4.c | 2 +- hw/arm11mpcore.c | 4 +- hw/arm_sysctl.c | 4 +- hw/armv7m.c | 2 +- hw/cs4231a.c | 6 ++-- hw/debugcon.c | 6 ++-- hw/eccmemctl.c | 2 +- hw/escc.c | 16 +++++----- hw/etraxfs_pic.c | 3 +- hw/fdc.c | 10 +++--- hw/gus.c | 8 ++-- hw/i2c.c | 2 +- hw/ide/cmd646.c | 2 +- hw/ide/isa.c | 6 ++-- hw/ide/qdev.c | 4 +- hw/integratorcp.c | 2 +- hw/lance.c | 2 +- hw/m48t59.c | 12 ++++---- hw/mc146818rtc.c | 2 +- hw/ne2000-isa.c | 4 +- hw/parallel.c | 8 ++-- hw/pci.c | 10 +++--- hw/qdev-addr.h | 4 +- hw/qdev.c | 51 +++++++++++++++++++++------------ hw/qdev.h | 75 ++++++++++++++++++++++++++----------------------- hw/s390-virtio-bus.c | 2 +- hw/sb16.c | 10 +++--- hw/scsi-bus.c | 2 +- hw/scsi-disk.c | 2 +- hw/serial.c | 8 ++-- hw/slavio_timer.c | 2 +- hw/smbus_eeprom.c | 2 +- hw/sparc32_dma.c | 2 +- hw/sun4m.c | 2 +- hw/sun4m_iommu.c | 2 +- hw/sun4u.c | 2 +- hw/syborg_fb.c | 4 +- hw/syborg_interrupt.c | 2 +- hw/syborg_keyboard.c | 2 +- hw/syborg_pointer.c | 4 +- hw/syborg_serial.c | 2 +- hw/syborg_timer.c | 2 +- hw/tcx.c | 10 +++--- hw/usb-ohci.c | 4 +- hw/usb-serial.c | 12 ++++---- hw/vga-pci.c | 4 +- hw/virtio-blk.h | 4 +- hw/virtio-console.c | 19 ++++++++---- hw/virtio-net.h | 51 +++++++++++++++++++++------------ hw/virtio-pci.c | 16 +++++----- hw/virtio-serial.h | 13 ++++++++ hw/virtio.h | 2 +- hw/xilinx_ethlite.c | 6 ++- hw/xilinx_intc.c | 3 +- hw/xilinx_timer.c | 4 +- net.h | 9 ++++-- usb-linux.c | 8 ++-- 59 files changed, 268 insertions(+), 208 deletions(-)
PATCH 1/5 qdev: Add a description field for qdev properties for documentation
Add a 'description' along with each qdev property to document the input each qdev property takes.
--- block_int.h | 10 +++--- hw/a9mpcore.c | 2 +- hw/acpi_piix4.c | 2 +- hw/arm11mpcore.c | 4 +- hw/arm_sysctl.c | 4 +- hw/armv7m.c | 2 +- hw/cs4231a.c | 6 ++-- hw/debugcon.c | 6 ++-- hw/eccmemctl.c | 2 +- hw/escc.c | 16 +++++----- hw/etraxfs_pic.c | 3 +- hw/fdc.c | 10 +++--- hw/gus.c | 8 ++-- hw/i2c.c | 2 +- hw/ide/cmd646.c | 2 +- hw/ide/isa.c | 6 ++-- hw/ide/qdev.c | 4 +- hw/integratorcp.c | 2 +- hw/lance.c | 2 +- hw/m48t59.c | 12 ++++---- hw/mc146818rtc.c | 2 +- hw/ne2000-isa.c | 4 +- hw/parallel.c | 8 ++-- hw/pci.c | 10 +++--- hw/qdev-addr.h | 4 +- hw/qdev.c | 3 +- hw/qdev.h | 75 ++++++++++++++++++++++++++----------------------- hw/s390-virtio-bus.c | 2 +- hw/sb16.c | 10 +++--- hw/scsi-bus.c | 2 +- hw/scsi-disk.c | 2 +- hw/serial.c | 8 ++-- hw/slavio_timer.c | 2 +- hw/smbus_eeprom.c | 2 +- hw/sparc32_dma.c | 2 +- hw/sun4m.c | 2 +- hw/sun4m_iommu.c | 2 +- hw/sun4u.c | 2 +- hw/syborg_fb.c | 4 +- hw/syborg_interrupt.c | 2 +- hw/syborg_keyboard.c | 2 +- hw/syborg_pointer.c | 4 +- hw/syborg_serial.c | 2 +- hw/syborg_timer.c | 2 +- hw/tcx.c | 10 +++--- hw/usb-ohci.c | 4 +- hw/usb-serial.c | 12 ++++---- hw/vga-pci.c | 4 +- hw/virtio-blk.h | 4 +- hw/virtio-console.c | 16 ++++++---- hw/virtio-net.h | 51 +++++++++++++++++++++------------ hw/virtio-pci.c | 16 +++++----- hw/virtio.h | 2 +- hw/xilinx_ethlite.c | 6 ++- hw/xilinx_intc.c | 3 +- hw/xilinx_timer.c | 4 +- net.h | 6 ++-- usb-linux.c | 8 ++-- 58 files changed, 218 insertions(+), 191 deletions(-)
block_int.h +5 -5
@@ -231,12 +231,12 @@ static inline unsigned int get_physical_block_exp(BlockConf *conf) }#define DEFINE_BLOCK_PROPERTIES (_state, _conf) \ - DEFINE_PROP_DRIVE("drive", _state, _conf.dinfo), \ + DEFINE_PROP_DRIVE("drive", _state, _conf.dinfo, ""), \ DEFINE_PROP_UINT16("logical_block_size", _state, \ - _conf.logical_block_size, 512), \ + _conf.logical_block_size, 512, ""), \ DEFINE_PROP_UINT16("physical_block_size", _state, \ - _conf.physical_block_size, 512), \ - DEFINE_PROP_UINT16("min_io_size", _state, _conf.min_io_size, 512), \ - DEFINE_PROP_UINT32("opt_io_size", _state, _conf.opt_io_size, 512) + _conf.physical_block_size, 512, ""), \ + DEFINE_PROP_UINT16("min_io_size", _state, _conf.min_io_size, 512, ""), \ + DEFINE_PROP_UINT32("opt_io_size", _state, _conf.opt_io_size, 512, "")#endif /* BLOCK_INT_H */
hw/a9mpcore.c +1 -1
@@ -16,7 +16,7 @@ static SysBusDeviceInfo mpcore_priv_info = { .qdev.name = "a9mpcore_priv", .qdev.size = sizeof(mpcore_priv_state), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num-cpu" , mpcore_priv_state, num_cpu,1 ), +DEFINE_PROP_UINT32 ("num-cpu" , mpcore_priv_state, num_cpu,1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/acpi_piix4.c +1 -1
@@ -410,7 +410,7 @@ static PCIDeviceInfo piix4_pm_info = { .init = piix4_pm_initfn, .config_write = pm_write_config, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("smb_io_base" , PIIX4PMState, smb_io_base,0 ), +DEFINE_PROP_UINT32 ("smb_io_base" , PIIX4PMState, smb_io_base,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/arm11mpcore.c +2 -2
@@ -88,7 +88,7 @@ static SysBusDeviceInfo mpcore_rirq_info = { .qdev.name = "realview_mpcore", .qdev.size = sizeof(mpcore_rirq_state), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num-cpu" , mpcore_rirq_state, num_cpu,1 ), +DEFINE_PROP_UINT32 ("num-cpu" , mpcore_rirq_state, num_cpu,1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
@@ -98,7 +98,7 @@ static SysBusDeviceInfo mpcore_priv_info = { .qdev.name = "arm11mpcore_priv", .qdev.size = sizeof(mpcore_priv_state), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num-cpu" , mpcore_priv_state, num_cpu,1 ), +DEFINE_PROP_UINT32 ("num-cpu" , mpcore_priv_state, num_cpu,1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/arm_sysctl.c +2 -2
@@ -232,8 +232,8 @@ static SysBusDeviceInfo arm_sysctl_info = { .qdev.size = sizeof(arm_sysctl_state), .qdev.reset = arm_sysctl_reset, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("sys_id" , arm_sysctl_state, sys_id,0 ), -DEFINE_PROP_UINT32 ("proc_id" , arm_sysctl_state, proc_id,0 ), +DEFINE_PROP_UINT32 ("sys_id" , arm_sysctl_state, sys_id,0 ,"" ), +DEFINE_PROP_UINT32 ("proc_id" , arm_sysctl_state, proc_id,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/armv7m.c +1 -1
@@ -247,7 +247,7 @@ static SysBusDeviceInfo bitband_info = { .qdev.name = "ARM,bitband-memory", .qdev.size = sizeof(BitBandState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("base" , BitBandState, base,0 ), +DEFINE_PROP_UINT32 ("base" , BitBandState, base,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/cs4231a.c +3 -3
@@ -671,9 +671,9 @@ static ISADeviceInfo cs4231a_info = { .qdev.vmsd = &vmstate_cs4231a, .init = cs4231a_initfn, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("iobase" , CSState, port,0x534 ), -DEFINE_PROP_UINT32 ("irq" , CSState, irq,9 ), -DEFINE_PROP_UINT32 ("dma" , CSState, dma,3 ), +DEFINE_PROP_HEX32 ("iobase" , CSState, port,0x534 ,"" ), +DEFINE_PROP_UINT32 ("irq" , CSState, irq,9 ,"" ), +DEFINE_PROP_UINT32 ("dma" , CSState, dma,3 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/debugcon.c +3 -3
@@ -92,9 +92,9 @@ static ISADeviceInfo debugcon_isa_info = { .qdev.size = sizeof(ISADebugconState), .init = debugcon_isa_initfn, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("iobase" , ISADebugconState, iobase,0xe9 ), -DEFINE_PROP_CHR ("chardev" , ISADebugconState, state.chr), -DEFINE_PROP_HEX32 ("readback" , ISADebugconState, state.readback,0xe9 ), +DEFINE_PROP_HEX32 ("iobase" , ISADebugconState, iobase,0xe9 ,"" ), +DEFINE_PROP_CHR ("chardev" , ISADebugconState, state.chr,"" ), +DEFINE_PROP_HEX32 ("readback" , ISADebugconState, state.readback,0xe9 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/eccmemctl.c +1 -1
@@ -324,7 +324,7 @@ static SysBusDeviceInfo ecc_info = { .qdev.vmsd = &vmstate_ecc, .qdev.reset = ecc_reset, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("version" , ECCState, version,-1 ), +DEFINE_PROP_HEX32 ("version" , ECCState, version,-1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/escc.c +8 -8
@@ -932,14 +932,14 @@ static SysBusDeviceInfo escc_info = { .qdev.vmsd = &vmstate_escc, .qdev.reset = escc_reset, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("frequency" , SerialState, frequency,0 ), -DEFINE_PROP_UINT32 ("it_shift" , SerialState, it_shift,0 ), -DEFINE_PROP_UINT32 ("disabled" , SerialState, disabled,0 ), -DEFINE_PROP_UINT32 ("disabled" , SerialState, disabled,0 ), -DEFINE_PROP_UINT32 ("chnBtype" , SerialState, chn[0 ].type,0 ), -DEFINE_PROP_UINT32 ("chnAtype" , SerialState, chn[1 ].type,0 ), -DEFINE_PROP_CHR ("chrB" , SerialState, chn[0 ].chr), -DEFINE_PROP_CHR ("chrA" , SerialState, chn[1 ].chr), +DEFINE_PROP_UINT32 ("frequency" , SerialState, frequency,0 ,"" ), +DEFINE_PROP_UINT32 ("it_shift" , SerialState, it_shift,0 ,"" ), +DEFINE_PROP_UINT32 ("disabled" , SerialState, disabled,0 ,"" ), +DEFINE_PROP_UINT32 ("disabled" , SerialState, disabled,0 ,"" ), +DEFINE_PROP_UINT32 ("chnBtype" , SerialState, chn[0 ].type,0 ,"" ), +DEFINE_PROP_UINT32 ("chnAtype" , SerialState, chn[1 ].type,0 ,"" ), +DEFINE_PROP_CHR ("chrB" , SerialState, chn[0 ].chr,"" ), +DEFINE_PROP_CHR ("chrA" , SerialState, chn[1 ].chr,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/etraxfs_pic.c +2 -1
@@ -155,7 +155,8 @@ static SysBusDeviceInfo etraxfs_pic_info = { .qdev.name = "etraxfs,pic", .qdev.size = sizeof(struct etrax_pic), .qdev.props = (Property []) { - DEFINE_PROP_PTR("interrupt_vector", struct etrax_pic, interrupt_vector), + DEFINE_PROP_PTR("interrupt_vector", struct etrax_pic, interrupt_vector, +"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/fdc.c +5 -5
@@ -2031,8 +2031,8 @@ static ISADeviceInfo isa_fdc_info = { .qdev.vmsd = &vmstate_isa_fdc, .qdev.reset = fdctrl_external_reset_isa, .qdev.props = (Property []) { -DEFINE_PROP_DRIVE ("driveA" , FDCtrlISABus, state.drives[0 ].dinfo), -DEFINE_PROP_DRIVE ("driveB" , FDCtrlISABus, state.drives[1 ].dinfo), +DEFINE_PROP_DRIVE ("driveA" , FDCtrlISABus, state.drives[0 ].dinfo,"" ), +DEFINE_PROP_DRIVE ("driveB" , FDCtrlISABus, state.drives[1 ].dinfo,"" ),DEFINE_PROP_END_OF_LIST (), }, };
@@ -2054,8 +2054,8 @@ static SysBusDeviceInfo sysbus_fdc_info = { .qdev.vmsd = &vmstate_sysbus_fdc, .qdev.reset = fdctrl_external_reset_sysbus, .qdev.props = (Property []) { -DEFINE_PROP_DRIVE ("driveA" , FDCtrlSysBus, state.drives[0 ].dinfo), -DEFINE_PROP_DRIVE ("driveB" , FDCtrlSysBus, state.drives[1 ].dinfo), +DEFINE_PROP_DRIVE ("driveA" , FDCtrlSysBus, state.drives[0 ].dinfo,"" ), +DEFINE_PROP_DRIVE ("driveB" , FDCtrlSysBus, state.drives[1 ].dinfo,"" ),DEFINE_PROP_END_OF_LIST (), }, };
@@ -2067,7 +2067,7 @@ static SysBusDeviceInfo sun4m_fdc_info = { .qdev.vmsd = &vmstate_sysbus_fdc, .qdev.reset = fdctrl_external_reset_sysbus, .qdev.props = (Property []) { -DEFINE_PROP_DRIVE ("drive" , FDCtrlSysBus, state.drives[0 ].dinfo), +DEFINE_PROP_DRIVE ("drive" , FDCtrlSysBus, state.drives[0 ].dinfo,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/gus.c +4 -4
@@ -303,10 +303,10 @@ static ISADeviceInfo gus_info = { .qdev.vmsd = &vmstate_gus, .init = gus_initfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("freq" , GUSState, freq,44100 ), -DEFINE_PROP_HEX32 ("iobase" , GUSState, port,0x240 ), -DEFINE_PROP_UINT32 ("irq" , GUSState, emu.gusirq,7 ), -DEFINE_PROP_UINT32 ("dma" , GUSState, emu.gusdma,3 ), +DEFINE_PROP_UINT32 ("freq" , GUSState, freq,44100 ,"" ), +DEFINE_PROP_HEX32 ("iobase" , GUSState, port,0x240 ,"" ), +DEFINE_PROP_UINT32 ("irq" , GUSState, emu.gusirq,7 ,"" ), +DEFINE_PROP_UINT32 ("dma" , GUSState, emu.gusdma,3 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/i2c.c +1 -1
@@ -21,7 +21,7 @@ static struct BusInfo i2c_bus_info = { .name = "I2C", .size = sizeof(i2c_bus), .props = (Property []) { - DEFINE_PROP_UINT8("address", struct i2c_slave, address, 0), + DEFINE_PROP_UINT8("address", struct i2c_slave, address, 0, ""),DEFINE_PROP_END_OF_LIST (), } };
hw/ide/cmd646.c +1 -1
@@ -286,7 +286,7 @@ static PCIDeviceInfo cmd646_ide_info[] = { .qdev.size = sizeof(PCIIDEState), .init = pci_cmd646_ide_initfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("secondary" , PCIIDEState, secondary,0 ), +DEFINE_PROP_UINT32 ("secondary" , PCIIDEState, secondary,0 ,"" ),DEFINE_PROP_END_OF_LIST (), }, },{
hw/ide/isa.c +3 -3
@@ -102,9 +102,9 @@ static ISADeviceInfo isa_ide_info = { .init = isa_ide_initfn, .qdev.reset = isa_ide_reset, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("iobase" , ISAIDEState, iobase,0x1f0 ), -DEFINE_PROP_HEX32 ("iobase2" , ISAIDEState, iobase2,0x3f6 ), -DEFINE_PROP_UINT32 ("irq" , ISAIDEState, isairq,14 ), +DEFINE_PROP_HEX32 ("iobase" , ISAIDEState, iobase,0x1f0 ,"" ), +DEFINE_PROP_HEX32 ("iobase2" , ISAIDEState, iobase2,0x3f6 ,"" ), +DEFINE_PROP_UINT32 ("irq" , ISAIDEState, isairq,14 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/ide/qdev.c +2 -2
@@ -109,9 +109,9 @@ static IDEDeviceInfo ide_drive_info = { .qdev.size = sizeof(IDEDrive), .init = ide_drive_initfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("unit" , IDEDrive, dev.unit,-1 ), +DEFINE_PROP_UINT32 ("unit" , IDEDrive, dev.unit,-1 ,"" ),DEFINE_BLOCK_PROPERTIES (IDEDrive, dev.conf), -DEFINE_PROP_STRING ("ver" , IDEDrive, dev.version), +DEFINE_PROP_STRING ("ver" , IDEDrive, dev.version,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/integratorcp.c +1 -1
@@ -528,7 +528,7 @@ static SysBusDeviceInfo core_info = { .qdev.name = "integrator_core", .qdev.size = sizeof(integratorcm_state), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("memsz" , integratorcm_state, memsz,0 ), +DEFINE_PROP_UINT32 ("memsz" , integratorcm_state, memsz,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/lance.c +1 -1
@@ -151,7 +151,7 @@ static SysBusDeviceInfo lance_info = { .qdev.reset = lance_reset, .qdev.vmsd = &vmstate_lance, .qdev.props = (Property[]) { -DEFINE_PROP_PTR ("dma" , SysBusPCNetState, state.dma_opaque), +DEFINE_PROP_PTR ("dma" , SysBusPCNetState, state.dma_opaque,"" ),DEFINE_NIC_PROPERTIES (SysBusPCNetState, state.conf),DEFINE_PROP_END_OF_LIST (), }
hw/m48t59.c +6 -6
@@ -730,9 +730,9 @@ static ISADeviceInfo m48t59_isa_info = { .qdev.reset = m48t59_reset_isa, .qdev.no_user = 1, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("size" , M48t59ISAState, state.size,-1 ), -DEFINE_PROP_UINT32 ("type" , M48t59ISAState, state.type,-1 ), -DEFINE_PROP_HEX32 ("io_base" , M48t59ISAState, state.io_base,0 ), +DEFINE_PROP_UINT32 ("size" , M48t59ISAState, state.size,-1 ,"" ), +DEFINE_PROP_UINT32 ("type" , M48t59ISAState, state.type,-1 ,"" ), +DEFINE_PROP_HEX32 ("io_base" , M48t59ISAState, state.io_base,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
@@ -743,9 +743,9 @@ static SysBusDeviceInfo m48t59_info = { .qdev.size = sizeof(M48t59SysBusState), .qdev.reset = m48t59_reset_sysbus, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("size" , M48t59SysBusState, state.size,-1 ), -DEFINE_PROP_UINT32 ("type" , M48t59SysBusState, state.type,-1 ), -DEFINE_PROP_HEX32 ("io_base" , M48t59SysBusState, state.io_base,0 ), +DEFINE_PROP_UINT32 ("size" , M48t59SysBusState, state.size,-1 ,"" ), +DEFINE_PROP_UINT32 ("type" , M48t59SysBusState, state.type,-1 ,"" ), +DEFINE_PROP_HEX32 ("io_base" , M48t59SysBusState, state.io_base,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/mc146818rtc.c +1 -1
@@ -655,7 +655,7 @@ static ISADeviceInfo mc146818rtc_info = { .qdev.vmsd = &vmstate_rtc, .init = rtc_initfn, .qdev.props = (Property []) { -DEFINE_PROP_INT32 ("base_year" , RTCState, base_year,1980 ), +DEFINE_PROP_INT32 ("base_year" , RTCState, base_year,1980 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/ne2000-isa.c +2 -2
@@ -107,8 +107,8 @@ static ISADeviceInfo ne2000_isa_info = { .qdev.size = sizeof(ISANE2000State), .init = isa_ne2000_initfn, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("iobase" , ISANE2000State, iobase,0x300 ), -DEFINE_PROP_UINT32 ("irq" , ISANE2000State, isairq,9 ), +DEFINE_PROP_HEX32 ("iobase" , ISANE2000State, iobase,0x300 ,"" ), +DEFINE_PROP_UINT32 ("irq" , ISANE2000State, isairq,9 ,"" ),DEFINE_NIC_PROPERTIES (ISANE2000State, ne2000.c),DEFINE_PROP_END_OF_LIST (), },
hw/parallel.c +4 -4
@@ -586,10 +586,10 @@ static ISADeviceInfo parallel_isa_info = { .qdev.size = sizeof(ISAParallelState), .init = parallel_isa_initfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("index" , ISAParallelState, index,-1 ), -DEFINE_PROP_HEX32 ("iobase" , ISAParallelState, iobase,-1 ), -DEFINE_PROP_UINT32 ("irq" , ISAParallelState, isairq,7 ), -DEFINE_PROP_CHR ("chardev" , ISAParallelState, state.chr), +DEFINE_PROP_UINT32 ("index" , ISAParallelState, index,-1 ,"" ), +DEFINE_PROP_HEX32 ("iobase" , ISAParallelState, iobase,-1 ,"" ), +DEFINE_PROP_UINT32 ("irq" , ISAParallelState, isairq,7 ,"" ), +DEFINE_PROP_CHR ("chardev" , ISAParallelState, state.chr,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/pci.c +5 -5
@@ -64,9 +64,9 @@ static struct BusInfo pci_bus_info = { .size = sizeof(PCIBus), .print_dev = pcibus_dev_print, .props = (Property []) { -DEFINE_PROP_PCI_DEVFN ("addr" , PCIDevice, devfn,-1 ), -DEFINE_PROP_STRING ("romfile" , PCIDevice, romfile), -DEFINE_PROP_UINT32 ("rombar" , PCIDevice, rom_bar,1 ), +DEFINE_PROP_PCI_DEVFN ("addr" , PCIDevice, devfn,-1 ,"" ), +DEFINE_PROP_STRING ("romfile" , PCIDevice, romfile,"" ), +DEFINE_PROP_UINT32 ("rombar" , PCIDevice, rom_bar,1 ,"" ),DEFINE_PROP_END_OF_LIST () } };
@@ -1906,8 +1906,8 @@ static PCIDeviceInfo bridge_info = { .config_write = pci_bridge_write_config, .header_type = PCI_HEADER_TYPE_BRIDGE, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("vendorid" , PCIBridge, vid,0 ), -DEFINE_PROP_HEX32 ("deviceid" , PCIBridge, did,0 ), +DEFINE_PROP_HEX32 ("vendorid" , PCIBridge, vid,0 ,"" ), +DEFINE_PROP_HEX32 ("deviceid" , PCIBridge, did,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/qdev-addr.h +2 -2
@@ -1,5 +1,5 @@ -#define DEFINE_PROP_TADDR (_n, _s, _f, _d) \ - DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_taddr, target_phys_addr_t) +#define DEFINE_PROP_TADDR (_n, _s, _f, _d, _c) \ + DEFINE_PROP_DEFAULT(_n, _s, _f, _d, qdev_prop_taddr, target_phys_addr_t, _c)extern PropertyInfo qdev_prop_taddr;void qdev_prop_set_taddr (DeviceState *dev,const char *name,target_phys_addr_t value);
hw/qdev.c +2 -1
@@ -187,7 +187,8 @@ int qdev_device_help(QemuOpts *opts)if (!prop->info->parse) {continue ;/* no way to set it, don't show */ } -error_printf ("%s.%s=%s\n" , info->name, prop->name, prop->info->name); +error_printf ("%s.%s=%s, %s\n" , info->name, prop->name, + prop->info->name, prop->desc ?:"" ); }return 1 ; }
hw/qdev.h +40 -35
105 lines not on this page · raw message
hw/s390-virtio-bus.c +1 -1
@@ -348,7 +348,7 @@ static VirtIOS390DeviceInfo s390_virtio_serial = { .qdev.size = sizeof(VirtIOS390Device), .qdev.props = (Property []) {DEFINE_PROP_UINT32 ("max_ports" , VirtIOS390Device, max_virtserial_ports, -31 ), +31 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/sb16.c +5 -5
@@ -1400,11 +1400,11 @@ static ISADeviceInfo sb16_info = { .qdev.vmsd = &vmstate_sb16, .init = sb16_initfn, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("version" , SB16State, ver,0x0405 ),/* 4.5 */ -DEFINE_PROP_HEX32 ("iobase" , SB16State, port,0x220 ), -DEFINE_PROP_UINT32 ("irq" , SB16State, irq,5 ), -DEFINE_PROP_UINT32 ("dma" , SB16State, dma,1 ), -DEFINE_PROP_UINT32 ("dma16" , SB16State, hdma,5 ), +DEFINE_PROP_HEX32 ("version" , SB16State, ver,0x0405 ,"" ),/* 4.5 */ +DEFINE_PROP_HEX32 ("iobase" , SB16State, port,0x220 ,"" ), +DEFINE_PROP_UINT32 ("irq" , SB16State, irq,5 ,"" ), +DEFINE_PROP_UINT32 ("dma" , SB16State, dma,1 ,"" ), +DEFINE_PROP_UINT32 ("dma16" , SB16State, hdma,5 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/scsi-bus.c +1 -1
@@ -9,7 +9,7 @@ static struct BusInfo scsi_bus_info = { .name = "SCSI", .size = sizeof(SCSIBus), .props = (Property []) { -DEFINE_PROP_UINT32 ("scsi-id" , SCSIDevice, id,-1 ), +DEFINE_PROP_UINT32 ("scsi-id" , SCSIDevice, id,-1 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/scsi-disk.c +1 -1
@@ -1089,7 +1089,7 @@ static SCSIDeviceInfo scsi_disk_info = { .get_buf = scsi_get_buf, .qdev.props = (Property []) {DEFINE_BLOCK_PROPERTIES (SCSIDiskState, qdev.conf), -DEFINE_PROP_STRING ("ver" , SCSIDiskState, version), +DEFINE_PROP_STRING ("ver" , SCSIDiskState, version,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/serial.c +4 -4
@@ -969,10 +969,10 @@ static ISADeviceInfo serial_isa_info = { .qdev.vmsd = &vmstate_isa_serial, .init = serial_isa_initfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("index" , ISASerialState, index,-1 ), -DEFINE_PROP_HEX32 ("iobase" , ISASerialState, iobase,-1 ), -DEFINE_PROP_UINT32 ("irq" , ISASerialState, isairq,-1 ), -DEFINE_PROP_CHR ("chardev" , ISASerialState, state.chr), +DEFINE_PROP_UINT32 ("index" , ISASerialState, index,-1 ,"" ), +DEFINE_PROP_HEX32 ("iobase" , ISASerialState, iobase,-1 ,"" ), +DEFINE_PROP_UINT32 ("irq" , ISASerialState, isairq,-1 ,"" ), +DEFINE_PROP_CHR ("chardev" , ISASerialState, state.chr,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/slavio_timer.c +1 -1
@@ -425,7 +425,7 @@ static SysBusDeviceInfo slavio_timer_info = { .qdev.vmsd = &vmstate_slavio_timer, .qdev.reset = slavio_timer_reset, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num_cpus" , SLAVIO_TIMERState, num_cpus,0 ), +DEFINE_PROP_UINT32 ("num_cpus" , SLAVIO_TIMERState, num_cpus,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/smbus_eeprom.c +1 -1
@@ -108,7 +108,7 @@ static SMBusDeviceInfo smbus_eeprom_info = { .i2c.qdev.name = "smbus-eeprom", .i2c.qdev.size = sizeof(SMBusEEPROMDevice), .i2c.qdev.props = (Property []) { -DEFINE_PROP_PTR ("data" , SMBusEEPROMDevice, data), +DEFINE_PROP_PTR ("data" , SMBusEEPROMDevice, data,"" ),DEFINE_PROP_END_OF_LIST (), }, .init = smbus_eeprom_init,
hw/sparc32_dma.c +1 -1
@@ -274,7 +274,7 @@ static SysBusDeviceInfo sparc32_dma_info = { .qdev.vmsd = &vmstate_dma, .qdev.reset = dma_reset, .qdev.props = (Property []) { -DEFINE_PROP_PTR ("iommu_opaque" , DMAState, iommu), +DEFINE_PROP_PTR ("iommu_opaque" , DMAState, iommu,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/sun4m.c +1 -1
@@ -760,7 +760,7 @@ static SysBusDeviceInfo ram_info = { .qdev.name = "memory", .qdev.size = sizeof(RamDevice), .qdev.props = (Property []) { -DEFINE_PROP_UINT64 ("size" , RamDevice, size,0 ), +DEFINE_PROP_UINT64 ("size" , RamDevice, size,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/sun4m_iommu.c +1 -1
@@ -379,7 +379,7 @@ static SysBusDeviceInfo iommu_info = { .qdev.vmsd = &vmstate_iommu, .qdev.reset = iommu_reset, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("version" , IOMMUState, version,0 ), +DEFINE_PROP_HEX32 ("version" , IOMMUState, version,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/sun4u.c +1 -1
@@ -692,7 +692,7 @@ static SysBusDeviceInfo ram_info = { .qdev.name = "memory", .qdev.size = sizeof(RamDevice), .qdev.props = (Property []) { -DEFINE_PROP_UINT64 ("size" , RamDevice, size,0 ), +DEFINE_PROP_UINT64 ("size" , RamDevice, size,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_fb.c +2 -2
@@ -536,8 +536,8 @@ static SysBusDeviceInfo syborg_fb_info = { .qdev.name = "syborg,framebuffer", .qdev.size = sizeof(SyborgFBState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("width" , SyborgFBState, cols,0 ), -DEFINE_PROP_UINT32 ("height" , SyborgFBState, rows,0 ), +DEFINE_PROP_UINT32 ("width" , SyborgFBState, cols,0 ,"" ), +DEFINE_PROP_UINT32 ("height" , SyborgFBState, rows,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_interrupt.c +1 -1
@@ -223,7 +223,7 @@ static SysBusDeviceInfo syborg_int_info = { .qdev.name = "syborg,interrupt", .qdev.size = sizeof(SyborgIntState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num-interrupts" , SyborgIntState, num_irqs,64 ), +DEFINE_PROP_UINT32 ("num-interrupts" , SyborgIntState, num_irqs,64 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_keyboard.c +1 -1
@@ -230,7 +230,7 @@ static SysBusDeviceInfo syborg_keyboard_info = { .qdev.name = "syborg,keyboard", .qdev.size = sizeof(SyborgKeyboardState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("fifo-size" , SyborgKeyboardState, fifo_size,16 ), +DEFINE_PROP_UINT32 ("fifo-size" , SyborgKeyboardState, fifo_size,16 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_pointer.c +2 -2
@@ -228,8 +228,8 @@ static SysBusDeviceInfo syborg_pointer_info = { .qdev.name = "syborg,pointer", .qdev.size = sizeof(SyborgPointerState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("fifo-size" , SyborgPointerState, fifo_size,16 ), -DEFINE_PROP_UINT32 ("absolute" , SyborgPointerState, absolute,1 ), +DEFINE_PROP_UINT32 ("fifo-size" , SyborgPointerState, fifo_size,16 ,"" ), +DEFINE_PROP_UINT32 ("absolute" , SyborgPointerState, absolute,1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_serial.c +1 -1
@@ -345,7 +345,7 @@ static SysBusDeviceInfo syborg_serial_info = { .qdev.name = "syborg,serial", .qdev.size = sizeof(SyborgSerialState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("fifo-size" , SyborgSerialState, fifo_size,16 ), +DEFINE_PROP_UINT32 ("fifo-size" , SyborgSerialState, fifo_size,16 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/syborg_timer.c +1 -1
@@ -231,7 +231,7 @@ static SysBusDeviceInfo syborg_timer_info = { .qdev.name = "syborg,timer", .qdev.size = sizeof(SyborgTimerState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("frequency" ,SyborgTimerState, freq,0 ), +DEFINE_PROP_UINT32 ("frequency" ,SyborgTimerState, freq,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/tcx.c +5 -5
@@ -633,11 +633,11 @@ static SysBusDeviceInfo tcx_info = { .qdev.reset = tcx_reset, .qdev.vmsd = &vmstate_tcx, .qdev.props = (Property []) { -DEFINE_PROP_TADDR ("addr" , TCXState, addr,-1 ), -DEFINE_PROP_HEX32 ("vram_size" , TCXState, vram_size,-1 ), -DEFINE_PROP_UINT16 ("width" , TCXState, width,-1 ), -DEFINE_PROP_UINT16 ("height" , TCXState, height,-1 ), -DEFINE_PROP_UINT16 ("depth" , TCXState, depth,-1 ), +DEFINE_PROP_TADDR ("addr" , TCXState, addr,-1 ,"" ), +DEFINE_PROP_HEX32 ("vram_size" , TCXState, vram_size,-1 ,"" ), +DEFINE_PROP_UINT16 ("width" , TCXState, width,-1 ,"" ), +DEFINE_PROP_UINT16 ("height" , TCXState, height,-1 ,"" ), +DEFINE_PROP_UINT16 ("depth" , TCXState, depth,-1 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/usb-ohci.c +2 -2
@@ -1778,8 +1778,8 @@ static SysBusDeviceInfo ohci_sysbus_info = { .qdev.desc = "OHCI USB Controller", .qdev.size = sizeof(OHCISysBusState), .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("num-ports" , OHCISysBusState, num_ports,3 ), -DEFINE_PROP_TADDR ("dma-offset" , OHCISysBusState, dma_offset,3 ), +DEFINE_PROP_UINT32 ("num-ports" , OHCISysBusState, num_ports,3 ,"" ), +DEFINE_PROP_TADDR ("dma-offset" , OHCISysBusState, dma_offset,3 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/usb-serial.c +6 -6
@@ -637,9 +637,9 @@ static struct USBDeviceInfo serial_info = { .usbdevice_name = "serial", .usbdevice_init = usb_serial_init, .qdev.props = (Property []) { -DEFINE_PROP_CHR ("chardev" , USBSerialState, cs), -DEFINE_PROP_HEX32 ("vendorid" , USBSerialState, vendorid,0x0403 ), -DEFINE_PROP_HEX32 ("productid" , USBSerialState, productid,0x6001 ), +DEFINE_PROP_CHR ("chardev" , USBSerialState, cs,"" ), +DEFINE_PROP_HEX32 ("vendorid" , USBSerialState, vendorid,0x0403 ,"" ), +DEFINE_PROP_HEX32 ("productid" , USBSerialState, productid,0x6001 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
@@ -657,9 +657,9 @@ static struct USBDeviceInfo braille_info = { .usbdevice_name = "braille", .usbdevice_init = usb_braille_init, .qdev.props = (Property []) { -DEFINE_PROP_CHR ("chardev" , USBSerialState, cs), -DEFINE_PROP_HEX32 ("vendorid" , USBSerialState, vendorid,0x0403 ), -DEFINE_PROP_HEX32 ("productid" , USBSerialState, productid,0xfe72 ), +DEFINE_PROP_CHR ("chardev" , USBSerialState, cs,"" ), +DEFINE_PROP_HEX32 ("vendorid" , USBSerialState, vendorid,0x0403 ,"" ), +DEFINE_PROP_HEX32 ("productid" , USBSerialState, productid,0xfe72 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/vga-pci.c +2 -2
@@ -132,8 +132,8 @@ static PCIDeviceInfo vga_info = { .init = pci_vga_initfn, .config_write = pci_vga_write_config, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("bios-offset" , PCIVGAState, vga.bios_offset,0 ), -DEFINE_PROP_HEX32 ("bios-size" , PCIVGAState, vga.bios_size,0 ), +DEFINE_PROP_HEX32 ("bios-offset" , PCIVGAState, vga.bios_offset,0 ,"" ), +DEFINE_PROP_HEX32 ("bios-size" , PCIVGAState, vga.bios_size,0 ,"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/virtio-blk.h +2 -2
@@ -94,8 +94,8 @@ struct virtio_scsi_inhdr#ifdef __linux__#define DEFINE_VIRTIO_BLK_FEATURES (_state, _field) \ - DEFINE_VIRTIO_COMMON_FEATURES(_state, _field), \ - DEFINE_PROP_BIT("scsi", _state, _field, VIRTIO_BLK_F_SCSI, true) + DEFINE_VIRTIO_COMMON_FEATURES(_state, _field), \ + DEFINE_PROP_BIT("scsi", _state, _field, VIRTIO_BLK_F_SCSI, true, "")#else #define DEFINE_VIRTIO_BLK_FEATURES (_state, _field) \ DEFINE_VIRTIO_COMMON_FEATURES(_state, _field)
hw/virtio-console.c +9 -7
@@ -95,10 +95,11 @@ static VirtIOSerialPortInfo virtconsole_info = { .init = virtconsole_initfn, .exit = virtconsole_exitfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT8 ("is_console" , VirtConsole, port.is_console,1 ), -DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID ), -DEFINE_PROP_CHR ("chardev" , VirtConsole, chr), -DEFINE_PROP_STRING ("name" , VirtConsole, port.name), +DEFINE_PROP_UINT8 ("is_console" , VirtConsole, port.is_console,1 ,"" ), +DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID , +"" ), +DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,"" ), +DEFINE_PROP_STRING ("name" , VirtConsole, port.name,"" ),DEFINE_PROP_END_OF_LIST (), }, };
@@ -131,9 +132,10 @@ static VirtIOSerialPortInfo virtserialport_info = { .init = virtserialport_initfn, .exit = virtconsole_exitfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID ), -DEFINE_PROP_CHR ("chardev" , VirtConsole, chr), -DEFINE_PROP_STRING ("name" , VirtConsole, port.name), +DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID , +"" ), +DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,"" ), +DEFINE_PROP_STRING ("name" , VirtConsole, port.name,"" ),DEFINE_PROP_END_OF_LIST (), }, };
hw/virtio-net.h +33 -18
55 lines not on this page · raw message
hw/virtio-pci.c +8 -8
@@ -666,9 +666,9 @@ static PCIDeviceInfo virtio_info[] = { .init = virtio_blk_init_pci, .exit = virtio_blk_exit_pci, .qdev.props = (Property []) { -DEFINE_PROP_HEX32 ("class" , VirtIOPCIProxy, class_code,0 ), +DEFINE_PROP_HEX32 ("class" , VirtIOPCIProxy, class_code,0 ,"" ),DEFINE_BLOCK_PROPERTIES (VirtIOPCIProxy, block), -DEFINE_PROP_UINT32 ("vectors" , VirtIOPCIProxy, nvectors,2 ), +DEFINE_PROP_UINT32 ("vectors" , VirtIOPCIProxy, nvectors,2 ,"" ),DEFINE_VIRTIO_BLK_FEATURES (VirtIOPCIProxy, host_features),DEFINE_PROP_END_OF_LIST (), },
@@ -680,7 +680,7 @@ static PCIDeviceInfo virtio_info[] = { .exit = virtio_net_exit_pci, .romfile = "pxe-virtio.bin", .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("vectors" , VirtIOPCIProxy, nvectors,3 ), +DEFINE_PROP_UINT32 ("vectors" , VirtIOPCIProxy, nvectors,3 ,"" ),DEFINE_VIRTIO_NET_FEATURES (VirtIOPCIProxy, host_features),DEFINE_NIC_PROPERTIES (VirtIOPCIProxy, nic),DEFINE_PROP_END_OF_LIST (),
@@ -694,11 +694,11 @@ static PCIDeviceInfo virtio_info[] = { .exit = virtio_exit_pci, .qdev.props = (Property []) {DEFINE_PROP_UINT32 ("vectors" , VirtIOPCIProxy, nvectors, -DEV_NVECTORS_UNSPECIFIED ), -DEFINE_PROP_HEX32 ("class" , VirtIOPCIProxy, class_code,0 ), +DEV_NVECTORS_UNSPECIFIED ,"" ), +DEFINE_PROP_HEX32 ("class" , VirtIOPCIProxy, class_code,0 ,"" ),DEFINE_VIRTIO_COMMON_FEATURES (VirtIOPCIProxy, host_features),DEFINE_PROP_UINT32 ("max_ports" , VirtIOPCIProxy, max_virtserial_ports, -31 ), +31 ,"" ),DEFINE_PROP_END_OF_LIST (), }, .qdev.reset = virtio_pci_reset,
@@ -719,8 +719,8 @@ static PCIDeviceInfo virtio_info[] = { .init = virtio_9p_init_pci, .qdev.props = (Property []) {DEFINE_VIRTIO_COMMON_FEATURES (VirtIOPCIProxy, host_features), -DEFINE_PROP_STRING ("mount_tag" , VirtIOPCIProxy, fsconf.tag), -DEFINE_PROP_STRING ("fsdev" , VirtIOPCIProxy, fsconf.fsdev_id), +DEFINE_PROP_STRING ("mount_tag" , VirtIOPCIProxy, fsconf.tag,"" ), +DEFINE_PROP_STRING ("fsdev" , VirtIOPCIProxy, fsconf.fsdev_id,"" ),DEFINE_PROP_END_OF_LIST (), }, }, {
hw/virtio.h +1 -1
@@ -197,7 +197,7 @@ void virtio_net_exit(VirtIODevice *vdev);#define DEFINE_VIRTIO_COMMON_FEATURES (_state, _field) \ DEFINE_PROP_BIT("indirect_desc", _state, _field, \ - VIRTIO_RING_F_INDIRECT_DESC, true) + VIRTIO_RING_F_INDIRECT_DESC, true, "")target_phys_addr_t virtio_queue_get_desc_addr (VirtIODevice *vdev,int n);target_phys_addr_t virtio_queue_get_avail_addr (VirtIODevice *vdev,int n);
hw/xilinx_ethlite.c +4 -2
@@ -239,8 +239,10 @@ static SysBusDeviceInfo xilinx_ethlite_info = { .qdev.name = "xilinx,ethlite", .qdev.size =sizeof (struct xlx_ethlite ), .qdev.props = (Property[]) { - DEFINE_PROP_UINT32("txpingpong", struct xlx_ethlite, c_tx_pingpong, 1), - DEFINE_PROP_UINT32("rxpingpong", struct xlx_ethlite, c_rx_pingpong, 1), + DEFINE_PROP_UINT32("txpingpong", struct xlx_ethlite, c_tx_pingpong, 1, +"" ), + DEFINE_PROP_UINT32("rxpingpong", struct xlx_ethlite, c_rx_pingpong, 1, +"" ), DEFINE_NIC_PROPERTIES(struct xlx_ethlite, conf),DEFINE_PROP_END_OF_LIST (), }
hw/xilinx_intc.c +2 -1
@@ -163,7 +163,8 @@ static SysBusDeviceInfo xilinx_intc_info = { .qdev.name = "xilinx,intc", .qdev.size = sizeof(struct xlx_pic), .qdev.props = (Property []) { - DEFINE_PROP_UINT32("kind-of-intr", struct xlx_pic, c_kind_of_intr, 0), + DEFINE_PROP_UINT32("kind-of-intr", struct xlx_pic, c_kind_of_intr, 0, +"" ),DEFINE_PROP_END_OF_LIST (), } };
hw/xilinx_timer.c +2 -2
@@ -220,8 +220,8 @@ static SysBusDeviceInfo xilinx_timer_info = { .qdev.name = "xilinx,timer", .qdev.size = sizeof(struct timerblock), .qdev.props = (Property []) { - DEFINE_PROP_UINT32("frequency", struct timerblock, freq_hz, 0), - DEFINE_PROP_UINT32("nr-timers", struct timerblock, nr_timers, 0), + DEFINE_PROP_UINT32("frequency", struct timerblock, freq_hz, 0, ""), + DEFINE_PROP_UINT32("nr-timers", struct timerblock, nr_timers, 0, ""),DEFINE_PROP_END_OF_LIST (), } };
net.h +3 -3
@@ -21,9 +21,9 @@ typedef struct NICConf { } NICConf;#define DEFINE_NIC_PROPERTIES (_state, _conf) \ - DEFINE_PROP_MACADDR("mac", _state, _conf.macaddr), \ - DEFINE_PROP_VLAN("vlan", _state, _conf.vlan), \ - DEFINE_PROP_NETDEV("netdev", _state, _conf.peer) + DEFINE_PROP_MACADDR("mac", _state, _conf.macaddr, ""), \ + DEFINE_PROP_VLAN("vlan", _state, _conf.vlan, ""), \ + DEFINE_PROP_NETDEV("netdev", _state, _conf.peer, "")/* VLANs support */
usb-linux.c +4 -4
@@ -1018,10 +1018,10 @@ static struct USBDeviceInfo usb_host_dev_info = { .usbdevice_name = "host", .usbdevice_init = usb_host_device_open, .qdev.props = (Property []) { -DEFINE_PROP_UINT32 ("hostbus" , USBHostDevice, match.bus_num,0 ), -DEFINE_PROP_UINT32 ("hostaddr" , USBHostDevice, match.addr,0 ), -DEFINE_PROP_HEX32 ("vendorid" , USBHostDevice, match.vendor_id,0 ), -DEFINE_PROP_HEX32 ("productid" , USBHostDevice, match.product_id,0 ), +DEFINE_PROP_UINT32 ("hostbus" , USBHostDevice, match.bus_num,0 ,"" ), +DEFINE_PROP_UINT32 ("hostaddr" , USBHostDevice, match.addr,0 ,"" ), +DEFINE_PROP_HEX32 ("vendorid" , USBHostDevice, match.vendor_id,0 ,"" ), +DEFINE_PROP_HEX32 ("productid" , USBHostDevice, match.product_id,0 ,"" ),DEFINE_PROP_END_OF_LIST (), }, };
Signature · 1 line
1.7.0.1
PATCH 2/5 virtio-serial: Add description fields for qdev properties
In reply to Amit ShahDocument the parameters for the virtserialport and virtioconsole devices.
Example:
$ ./x86_64-softmmu/qemu-system-x86_64 -device virtserialport,? virtserialport.nr=uint32, The 'number' for the port for \ predictable port numbers. Use this to spawn ports if you \ plan to migrate the guest.
virtserialport.chardev=chr, The chardev to associate this port with.
virtserialport.name=string, Name for the port that's exposed to \
the guest for port discovery.
--- hw/virtio-console.c | 17 ++++++++++------- hw/virtio-serial.h | 13 +++++++++++++ 2 files changed, 23 insertions(+), 7 deletions(-)
hw/virtio-console.c +10 -7
@@ -95,11 +95,13 @@ static VirtIOSerialPortInfo virtconsole_info = { .init = virtconsole_initfn, .exit = virtconsole_exitfn, .qdev.props = (Property []) { -DEFINE_PROP_UINT8 ("is_console" , VirtConsole, port.is_console,1 ,"" ), +DEFINE_PROP_UINT8 ("is_console" , VirtConsole, port.is_console,1 , +PROP_VIRTSERIAL_IS_CONSOLE_DESC ),DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID , -"" ), -DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,"" ), -DEFINE_PROP_STRING ("name" , VirtConsole, port.name,"" ), +PROP_VIRTSERIAL_NR_DESC ), +DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,PROP_VIRTSERIAL_CHR_DESC ), +DEFINE_PROP_STRING ("name" , VirtConsole, port.name, +PROP_VIRTSERIAL_NAME_DESC ),DEFINE_PROP_END_OF_LIST (), }, };
@@ -133,9 +135,10 @@ static VirtIOSerialPortInfo virtserialport_info = { .exit = virtconsole_exitfn, .qdev.props = (Property []) {DEFINE_PROP_UINT32 ("nr" , VirtConsole, port.id,VIRTIO_CONSOLE_BAD_ID , -"" ), -DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,"" ), -DEFINE_PROP_STRING ("name" , VirtConsole, port.name,"" ), +PROP_VIRTSERIAL_NR_DESC ), +DEFINE_PROP_CHR ("chardev" , VirtConsole, chr,PROP_VIRTSERIAL_CHR_DESC ), +DEFINE_PROP_STRING ("name" , VirtConsole, port.name, +PROP_VIRTSERIAL_NAME_DESC ),DEFINE_PROP_END_OF_LIST (), }, };
hw/virtio-serial.h +13 -0
@@ -58,6 +58,19 @@ struct virtio_console_control {/* == In-qemu interface == */ +#define PROP_VIRTSERIAL_IS_CONSOLE_DESC \ + "An hvc console will be spawned in the guest if this is set." + +#define PROP_VIRTSERIAL_NR_DESC \ + "The 'number' for the port for predictable port numbers. Use this to " \ + "spawn ports if you plan to migrate the guest." + +#define PROP_VIRTSERIAL_CHR_DESC \ + "The chardev to associate this port with." + +#define PROP_VIRTSERIAL_NAME_DESC \ + "Name for the port that's exposed to the guest for port discovery." +typedef struct VirtIOSerial VirtIOSerial ;typedef struct VirtIOSerialBus VirtIOSerialBus ;typedef struct VirtIOSerialPort VirtIOSerialPort ;
Signature · 1 line
1.7.0.1
PATCH 3/5 net.h: Add description fields for qdev properites
In reply to Amit ShahThis results in an output like:
$ ./x86_64-softmmu/qemu-system-x86_64 -device virtio-net-pci,?
...
virtio-net-pci.mac=macaddr, The MAC address for the NIC. virtio-net-pci.vlan=vlan, The VLAN to associate the NIC with. virtio-net-pci.netdev=netdev, The peer net device to associate with this virtual NIC.
--- net.h | 9 ++++++--- 1 files changed, 6 insertions(+), 3 deletions(-)
net.h +6 -3
@@ -21,9 +21,12 @@ typedef struct NICConf { } NICConf;#define DEFINE_NIC_PROPERTIES (_state, _conf) \ - DEFINE_PROP_MACADDR("mac", _state, _conf.macaddr, ""), \ - DEFINE_PROP_VLAN("vlan", _state, _conf.vlan, ""), \ - DEFINE_PROP_NETDEV("netdev", _state, _conf.peer, "") + DEFINE_PROP_MACADDR("mac", _state, _conf.macaddr, \ + "The MAC address for the NIC."), \ + DEFINE_PROP_VLAN("vlan", _state, _conf.vlan, \ + "The VLAN to associate the NIC with."), \ + DEFINE_PROP_NETDEV("netdev", _state, _conf.peer, \ + "The peer net device to associate with this virtual NIC.")/* VLANs support */
Signature · 1 line
1.7.0.1
PATCH 4/5 qdev: Re-arrange code to have device properties shown from own function
In reply to Amit ShahInstead of printing out the device properties help messages from qdev_device_help(), split it off into a new function. This way, we have two separate function calls for device help and device properties help.
This will be later used to show all the devices and all the properties associated with the device as part of a complete coverage for all devices and options associated with each of them.
--- hw/qdev.c | 41 ++++++++++++++++++++++++----------------- 1 files changed, 24 insertions(+), 17 deletions(-)
hw/qdev.c +24 -17
@@ -151,27 +151,11 @@ static int set_property(const char *name, const char *value, void *opaque)return 0 ; } -int qdev_device_help (QemuOpts *opts) +static int show_device_props (const char *driver) { -const char *driver;DeviceInfo *info;Property *prop; - driver =qemu_opt_get (opts,"driver" ); -if (driver && !strcmp (driver,"?" )) { -for (info = device_info_list; info !=NULL ; info = info->next) { -if (info->no_user) { -continue ;/* not available, don't show */ - } -qdev_print_devinfo (info); - } -return 1 ; - } - -if (!qemu_opt_get (opts,"?" )) { -return 0 ; - } - info =qdev_find_info (NULL , driver);if (!info) {return 0 ;
@@ -193,6 +177,29 @@ int qdev_device_help(QemuOpts *opts)return 1 ; } +int qdev_device_help (QemuOpts *opts) +{ +const char *driver; +DeviceInfo *info; + + driver =qemu_opt_get (opts,"driver" ); +if (driver && !strcmp (driver,"?" )) { +for (info = device_info_list; info !=NULL ; info = info->next) { +if (info->no_user) { +continue ;/* not available, don't show */ + } +qdev_print_devinfo (info); + } +return 1 ; + } + +if (!qemu_opt_get (opts,"?" )) { +return 0 ; + } + +return show_device_props (driver); +} +DeviceState *qdev_device_add (QemuOpts *opts) {const char *driver, *path, *id;
Signature · 1 line
1.7.0.1
PATCH 5/5 qdev: Add new '-device help' option, shows all devices and properties
In reply to Amit ShahThe new '-device help' option shows all the devices that are registered with qdev and prints out all the properties each device has, along with the description for each property.
This is useful in creating automatic documentation for all the options that we have and support.
--- hw/qdev.c | 15 +++++++++++---- 1 files changed, 11 insertions(+), 4 deletions(-)
hw/qdev.c +11 -4
@@ -151,7 +151,7 @@ static int set_property(const char *name, const char *value, void *opaque)return 0 ; } -static int show_device_props (const char *driver) +static int show_device_props (const char *driver,const char *prefix) {DeviceInfo *info;Property *prop;
@@ -161,6 +161,10 @@ static int show_device_props(const char *driver)return 0 ; } +if (!prefix) { + prefix ="" ; + } +for (prop = info->props; prop && prop->name; prop++) {/* * TODO Properties without a parser are just for dirty hacks.
@@ -171,7 +175,7 @@ static int show_device_props(const char *driver)if (!prop->info->parse) {continue ;/* no way to set it, don't show */ } -error_printf ("%s.%s=%s, %s\n" , info->name, prop->name, +error_printf ("%s%s.%s=%s, %s\n" , prefix, info->name, prop->name, prop->info->name, prop->desc ?:"" ); }return 1 ;
@@ -183,12 +187,15 @@ int qdev_device_help(QemuOpts *opts)DeviceInfo *info; driver =qemu_opt_get (opts,"driver" ); -if (driver && !strcmp (driver,"?" )) { +if (driver && (!strcmp (driver,"?" ) || !strcmp (driver,"help" ))) {for (info = device_info_list; info !=NULL ; info = info->next) {if (info->no_user) {continue ;/* not available, don't show */ }qdev_print_devinfo (info); +if (!strcmp (driver,"help" )) { +show_device_props (info->name,"\t" ); + } }return 1 ; }
@@ -197,7 +204,7 @@ int qdev_device_help(QemuOpts *opts)return 0 ; } -return show_device_props (driver); +return show_device_props (driver,NULL ); }DeviceState *qdev_device_add (QemuOpts *opts)
Signature · 1 line
1.7.0.1
Re: [Qemu-devel] [PATCH 5/5] qdev: Add new '-device help' option, shows all devices and properties
I like PATCH 1-3/5, but this one needs discussion.
Quoted 11 lines · Amit Shah
The new '-device help' option shows all the devices that are registered with qdev and prints out all the properties each device has, along with the description for each property.
This is useful in creating automatic documentation for all the options that we have and support.
Signed-off-by Amit Shah <[email protected]>--- hw/qdev.c | 15 +++++++++++---- 1 files changed, 11 insertions(+), 4 deletions(-)
Documentation update missing: qemu-options.hx
Quoted 14 lines
hw/qdev.c +1
-1@@ -151,7 +151,7 @@ static int set_property(const char *name, const char *value, void *opaque)return 0 ; } -static int show_device_props (const char *driver) +static int show_device_props (const char *driver,const char *prefix) {DeviceInfo *info;Property *prop;
hw/qdev.c static int show_device_props(const char *driver) · line 167
Quoted 7 lines
hw/qdev.c +4
-0@@ -161,6 +161,10 @@ static int show_device_props(const char *driver)return 0 ; } +if (!prefix) { + prefix ="" ; + } +
Just make the caller pass "" instead of NULL.
Quoted 19 lines
hw/qdev.c +2
-2for (prop = info->props; prop && prop->name; prop++) {/* * TODO Properties without a parser are just for dirty hacks. @@ -171,7 +175,7 @@ static int show_device_props(const char *driver)if (!prop->info->parse) {continue ;/* no way to set it, don't show */ } -error_printf ("%s.%s=%s, %s\n" , info->name, prop->name, +error_printf ("%s%s.%s=%s, %s\n" , prefix, info->name, prop->name, prop->info->name, prop->desc ?:"" ); }return 1 ;@@ -183,12 +187,15 @@ int qdev_device_help(QemuOpts *opts)DeviceInfo *info; driver =qemu_opt_get (opts,"driver" ); -if (driver && !strcmp (driver,"?" )) { +if (driver && (!strcmp (driver,"?" ) || !strcmp (driver,"help" ))) {for (info = device_info_list; info !=NULL ; info = info->next) {
hw/qdev.c int qdev_device_help(QemuOpts *opts) · line 201
Quoted 10 lines
hw/qdev.c +3
-0if (info->no_user) {continue ;/* not available, don't show */ }qdev_print_devinfo (info); +if (!strcmp (driver,"help" )) { +show_device_props (info->name,"\t" ); + } }return 1 ; }
There is "-device \?" and "-device help", but the user interface provides no clue about the difference between them.
"-device help" loses when we ever pick up a device model with name "help". Not that "?" was a particularly smart choice...
Do we really need two kinds of help output? Where the second is basically the same as "-device FOO,\?" for all FOO? Is that convenience worth the extra UI complexity?
Doing it in the shell isn't exactly hard:
$ for i in `qemu -device \? 2>&1 | awk -F \" '{ print $2 }'`; do qemu -device $i,\?; doneQuoted 9 lines
hw/qdev.c +1
-1@@ -197,7 +204,7 @@ int qdev_device_help(QemuOpts *opts)return 0 ; } -return show_device_props (driver); +return show_device_props (driver,NULL ); }DeviceState *qdev_device_add (QemuOpts *opts)
Re: [Qemu-devel] [PATCH 5/5] qdev: Add new '-device help' option, shows all devices and properties
Quoted 10 lines · Markus Armbruster
There is "-device \?" and "-device help", but the user interface provides no clue about the difference between them.
"-device help" loses when we ever pick up a device model with name "help". Not that "?" was a particularly smart choice...
Do we really need two kinds of help output? Where the second is basically the same as "-device FOO,\?" for all FOO? Is that convenience worth the extra UI complexity?
OK, so my big plan is to have something like this:
---
./qemu -device help
...
name "virtserialport", bus virtio-serial-bus
nr=uint32, The 'number' for the port for predictable port numbers. chardev=chr, The chardev to associate this port with. name=string, Name for the port that's exposed to the guest for port discovery.
...
---
./qemu -device virtserialport,?
virtserialport.nr=uint32, The 'number' for the port for predictable port numbers.
Use this to spawn ports if you plan to migrate the guest and perform hot-plug and unplug operations.
virtserialport.chardev=chr, The chardev to associate this port with.
External programs can communicate with the guest side of the channel using chardev
virtserialport.name=string, Name for the port that's exposed to the guest for port discovery.
The name is exposed in Linux guests via sysfs and udev rules can be written to create symlinks to the ports. Apps in the guest can then easily find these ports and start communication.
---
So basically -device help gives a short, one-liner help message and the -device ? option gives a slightly detailed message, if one is available.
How to do that: I'm thinking of two ways:
1)
DEFINE_PROP_UINT32("nr", VirtConsole, port.id, VIRTIO_CONSOLE_BAD_ID,
"The 'number' for the port for predictable port numbers.", "Use this to spawn ports if you plan to migrate the guest and perform \n" "hot-plug and unplug operations." ),
ie, two different strings for the short and long descriptions
2)
DEFINE_PROP_UINT32("nr", VirtConsole, port.id, VIRTIO_CONSOLE_BAD_ID,
"The 'number' for the port for predictable port numbers.\n" "Use this to spawn ports if you plan to migrate the guest and perform \n" "hot-plug and unplug operations." ),
ie, the same string, but the short and long descriptions are separated by a '\n'.
Doing it the adds parsing to the printing routine for no extra benefit, so I'm inclined to go with 1. Thoughts?
Amit
Quoted 7 lines · Amit Shah
Hello,
This patch series adds support to specify some descriptive help text to qdev device parameters. This series adds some help text to the virtserialport and net family of devices as an example, and the new output is shown in the respective commits.
Quoted 8 lines
This series also adds a new '-device help' option that lists all the available qdev devices (which is avl. via -device ? now), and adds each device's parameters to the output listing. This output also shows the descriptive text.
The idea is to auto-generate documentation from code and to populate some wiki / qemu-doc.texi using this new target.
I really dislike having options print their own help.
Maybe we can introduce a proper -help option that takes an argument that can display subsystem specific help?
For instance:
qemu -help device
Would display the help output in this series.
My other concern is that we now have a big mess of properties that don't have help text. What are the chances that anyone is going to go through and do this?
I'd rather we bite the bullet and add help everywhere before merging any of this because experience has shown that existing code usually never gets converted if not converted all at once.
Regards,
Anthony Liguori
Quoted 78 lines
Changes from previous send:
- Removed the 'RFC' tag
- Not using macros innet.h(Markus)It'll be helpful to have people submit some short descriptive text for the subsystems they care about.
Amit Shah (5):
qdev: Add a description field for qdev properties for documentation
virtio-serial: Add description fields for qdev propertiesnet.h: Add description fields for qdev properites
qdev: Re-arrange code to have device properties shown from own
function
qdev: Add new '-device help' option, shows all devices and propertiesblock_int.h | 10 +++--- hw/a9mpcore.c | 2 +- hw/acpi_piix4.c | 2 +- hw/arm11mpcore.c | 4 +- hw/arm_sysctl.c | 4 +- hw/armv7m.c | 2 +- hw/cs4231a.c | 6 ++-- hw/debugcon.c | 6 ++-- hw/eccmemctl.c | 2 +- hw/escc.c | 16 +++++----- hw/etraxfs_pic.c | 3 +- hw/fdc.c | 10 +++--- hw/gus.c | 8 ++-- hw/i2c.c | 2 +- hw/ide/cmd646.c | 2 +- hw/ide/isa.c | 6 ++-- hw/ide/qdev.c | 4 +- hw/integratorcp.c | 2 +- hw/lance.c | 2 +- hw/m48t59.c | 12 ++++---- hw/mc146818rtc.c | 2 +- hw/ne2000-isa.c | 4 +- hw/parallel.c | 8 ++-- hw/pci.c | 10 +++--- hw/qdev-addr.h | 4 +- hw/qdev.c | 51 +++++++++++++++++++++------------ hw/qdev.h | 75 ++++++++++++++++++++++++++----------------------- hw/s390-virtio-bus.c | 2 +- hw/sb16.c | 10 +++--- hw/scsi-bus.c | 2 +- hw/scsi-disk.c | 2 +- hw/serial.c | 8 ++-- hw/slavio_timer.c | 2 +- hw/smbus_eeprom.c | 2 +- hw/sparc32_dma.c | 2 +- hw/sun4m.c | 2 +- hw/sun4m_iommu.c | 2 +- hw/sun4u.c | 2 +- hw/syborg_fb.c | 4 +- hw/syborg_interrupt.c | 2 +- hw/syborg_keyboard.c | 2 +- hw/syborg_pointer.c | 4 +- hw/syborg_serial.c | 2 +- hw/syborg_timer.c | 2 +- hw/tcx.c | 10 +++--- hw/usb-ohci.c | 4 +- hw/usb-serial.c | 12 ++++---- hw/vga-pci.c | 4 +- hw/virtio-blk.h | 4 +- hw/virtio-console.c | 19 ++++++++---- hw/virtio-net.h | 51 +++++++++++++++++++++------------ hw/virtio-pci.c | 16 +++++----- hw/virtio-serial.h | 13 ++++++++ hw/virtio.h | 2 +- hw/xilinx_ethlite.c | 6 ++- hw/xilinx_intc.c | 3 +- hw/xilinx_timer.c | 4 +- net.h | 9 ++++-- usb-linux.c | 8 ++-- 59 files changed, 268 insertions(+), 208 deletions(-)
Quoted 13 lines · Anthony Liguori
Quoted 12 lines · Amit Shah
Hello,
This patch series adds support to specify some descriptive help text to qdev device parameters. This series adds some help text to the virtserialport and net family of devices as an example, and the new output is shown in the respective commits.
This series also adds a new '-device help' option that lists all the available qdev devices (which is avl. via -device ? now), and adds each device's parameters to the output listing. This output also shows the descriptive text.
Quoted 4 lines
Quoted 2 lines
The idea is to auto-generate documentation from code and to populate some wiki / qemu-doc.texi using this new target.
I really dislike having options print their own help.
Why? I really like it, coders can embed help exactly in the same place they're adding / changing options and there's much less chance of someone missing updating help strings when updating / adding options.
Quoted 8 lines
Maybe we can introduce a proper -help option that takes an argument that can display subsystem specific help?
For instance:
qemu -help device
Would display the help output in this series.
What I'm adding here is similar; instead of -help device, I'm adding -device help, and I think it's nicer because it fits directly in the qdev code.
Quoted 7 lines
My other concern is that we now have a big mess of properties that don't have help text. What are the chances that anyone is going to go through and do this?
I'd rather we bite the bullet and add help everywhere before merging any of this because experience has shown that existing code usually never gets converted if not converted all at once.
Let me put my community contributor hat on: we're not really giving away vibes that qemu has to be 100% enterprise-ready at each commit, are we? qemu is a *development* project, and development happens one small commit at a time, commit early and often. If I'm going to have to maintiain hundreds of small help-related patches, it's soon going to grow stale as people change related code and in the end I'll grow frustrated and drop then entire exercise. Not the first time that would've happened.
On the other hand, we commit this right away, and interested developers in their own domains start contributing the small one-liners which brings their subsystem up to the mark for documentation.
I think this is the best way to contribute such patches.
If you think some devices are going to go documentation-less, instead of empty strings, I can do "description needed" strings, which can even invite first-time contributors grep through this and contribute the one-liners.
If the enterprise people want this fixed before any enterprise release, they better commit resources to ensure they don't release anything that has a 'documentation needed!' line. :-)
Amit
Quoted 16 lines · Amit Shah
Quoted 14 lines · Anthony Liguori
Quoted 12 lines · Amit Shah
Hello,
This patch series adds support to specify some descriptive help text to qdev device parameters. This series adds some help text to the virtserialport and net family of devices as an example, and the new output is shown in the respective commits.
This series also adds a new '-device help' option that lists all the available qdev devices (which is avl. via -device ? now), and adds each device's parameters to the output listing. This output also shows the descriptive text.
Quoted 9 lines
Quoted 5 lines
Quoted 3 lines
The idea is to auto-generate documentation from code and to populate some wiki / qemu-doc.texi using this new target.
I really dislike having options print their own help.
Why? I really like it, coders can embed help exactly in the same place they're adding / changing options and there's much less chance of someone missing updating help strings when updating / adding options.
Because it's inconsistent from a UI perspective. -device help, -M ?, etc.
How's a user supposed to know which options can display help and what the magic invocation is that is used to display it?
-help device/-help machine
Provides a consistent, self discoverable interface for users to get detailed inline help.
Quoted 5 lines
Quoted 5 lines
Maybe we can introduce a proper -help option that takes an argument that can display subsystem specific help?
For instance:
Quoted 8 lines
Quoted 4 lines
qemu -help device
Would display the help output in this series.
What I'm adding here is similar; instead of -help device, I'm adding -device help, and I think it's nicer because it fits directly in the qdev code.
The UI should not be a consequence of the implementation.
Quoted 8 lines
Quoted 8 lines
My other concern is that we now have a big mess of properties that don't have help text. What are the chances that anyone is going to go through and do this?
I'd rather we bite the bullet and add help everywhere before merging any of this because experience has shown that existing code usually never gets converted if not converted all at once.
Quoted 9 lines
Let me put my community contributor hat on: we're not really giving away vibes that qemu has to be 100% enterprise-ready at each commit, are we? qemu is a *development* project, and development happens one small commit at a time, commit early and often. If I'm going to have to maintiain hundreds of small help-related patches, it's soon going to grow stale as people change related code and in the end I'll grow frustrated and drop then entire exercise. Not the first time that would've happened.
The problem with this argument is that people introduce things like this with this exact argument and then nothing every ends up getting help options.
Quoted 4 lines
On the other hand, we commit this right away, and interested developers in their own domains start contributing the small one-liners which brings their subsystem up to the mark for documentation.
It simply doesn't happen or else it already would have. The best way to make this is a one time painful conversion followed by strong enforcement that all new options take help strings.
Regards,
Anthony Liguori
Quoted 15 lines
I think this is the best way to contribute such patches.
If you think some devices are going to go documentation-less, instead of empty strings, I can do "description needed" strings, which can even invite first-time contributors grep through this and contribute the one-liners.
If the enterprise people want this fixed before any enterprise release, they better commit resources to ensure they don't release anything that has a 'documentation needed!' line. :-)
Amit
Quoted 29 lines · Anthony Liguori
Quoted 16 lines · Amit Shah
Quoted 14 lines · Anthony Liguori
Quoted 12 lines · Amit Shah
Hello,
This patch series adds support to specify some descriptive help text to qdev device parameters. This series adds some help text to the virtserialport and net family of devices as an example, and the new output is shown in the respective commits.
This series also adds a new '-device help' option that lists all the available qdev devices (which is avl. via -device ? now), and adds each device's parameters to the output listing. This output also shows the descriptive text.
Quoted 9 lines
Quoted 5 lines
Quoted 3 lines
The idea is to auto-generate documentation from code and to populate some wiki / qemu-doc.texi using this new target.
I really dislike having options print their own help.
Why? I really like it, coders can embed help exactly in the same place they're adding / changing options and there's much less chance of someone missing updating help strings when updating / adding options.
Because it's inconsistent from a UI perspective. -device help, -M ?, etc.
Quoted 7 lines
How's a user supposed to know which options can display help and what the magic invocation is that is used to display it?
-help device/-help machine
Provides a consistent, self discoverable interface for users to get detailed inline help.
Additional advantages:
* No special case for '?' in option processing. No risk '?' for help collides with a legitimate non-help option argument starting with '?'.
* No more "-device x: Parameter 'driver' expects a driver name" just because you happen to have a file named "x" around, and you forgot to quote.
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Maybe we can introduce a proper -help option that takes an argument that can display subsystem specific help?
For instance:
qemu -help device
Quoted 8 lines
Quoted 6 lines
Quoted 2 lines
Would display the help output in this series.
What I'm adding here is similar; instead of -help device, I'm adding -device help, and I think it's nicer because it fits directly in the qdev code.
The UI should not be a consequence of the implementation.
Yes. And "-help FOO" can certainly be engineered so that FOO's documentation is still next to FOO's implementation.
[...]