libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

[Euan Harris]

Hi,

If I call libxl_device_nic_add and pass in a mostly-default
libxl_device_nic structure, the function fills in the unspecified default
config fields with data for the NIC which it has just created:

	libxl_device_nic nic;
   	libxl_device_nic_init(&nic);
	/* 
	   nic.devid == -1 
	   nic.mac == 00:00:00:00:00:00 
           nic.model == null
	   etc.
	 */

	libxl_device_nic_add(ctx, domid, &nic, NULL);
	/* 
	   nic.devid == 3 
	   nic.mac == 00:16:3e:1b:7b:12
           nic.model == rtl8139
	   etc.
	 */

Is this behaviour an intentional part of the API which I can rely on,
or just an artefact of the current implementation?  In other words, is
nic meant to be an (in)_out parameter?  If it's not, what is the correct
way to find out the device ID which was allocated for the new device,
for example?

Thanks,
Euan

Re: libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

[Ian Campbell]

On Tue, 2014-11-18 at 15:28 +0000, Euan Harris wrote:
> Hi,
> 
> If I call libxl_device_nic_add and pass in a mostly-default
> libxl_device_nic structure, the function fills in the unspecified default
> config fields with data for the NIC which it has just created:
> 
> 	libxl_device_nic nic;
>    	libxl_device_nic_init(&nic);
> 	/* 
> 	   nic.devid == -1 
> 	   nic.mac == 00:00:00:00:00:00 
>            nic.model == null
> 	   etc.
> 	 */
> 
> 	libxl_device_nic_add(ctx, domid, &nic, NULL);
> 	/* 
> 	   nic.devid == 3 
> 	   nic.mac == 00:16:3e:1b:7b:12
>            nic.model == rtl8139
> 	   etc.
> 	 */
> 
> Is this behaviour an intentional part of the API which I can rely on,
> or just an artefact of the current implementation?  In other words, is
> nic meant to be an (in)_out parameter?

I believe so, yes. The comment under "Devices" in libxl.h probably ought
to be adjusted to say so explicitly.

Ian (J) -- do you agree?

>   If it's not, what is the correct
> way to find out the device ID which was allocated for the new device,
> for example?

You would have to libxl_device_<type>_list and look for it, which is
clearly suboptimal.

Ian.

Re: libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

[Ian Jackson]

Ian Campbell writes ("Re: [Xen-devel] libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?"):
> On Tue, 2014-11-18 at 15:28 +0000, Euan Harris wrote:
> > If I call libxl_device_nic_add and pass in a mostly-default
> > libxl_device_nic structure, the function fills in the unspecified default
> > config fields with data for the NIC which it has just created:
...
> > Is this behaviour an intentional part of the API which I can rely on,
> > or just an artefact of the current implementation?  In other words, is
> > nic meant to be an (in)_out parameter?

Yes.

> I believe so, yes. The comment under "Devices" in libxl.h probably ought
> to be adjusted to say so explicitly.
> 
> Ian (J) -- do you agree?

I do.  I think this applies to other kinds of device too, which might
have unspecified parameters which get filled in.

Euan, would you like to send us a doc patch for libxl.h ?

Ian.

Re: libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

[Ian Campbell]

On Tue, 2014-11-18 at 15:41 +0000, Ian Jackson wrote:
> Ian Campbell writes ("Re: [Xen-devel] libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?"):
> > On Tue, 2014-11-18 at 15:28 +0000, Euan Harris wrote:
> > > If I call libxl_device_nic_add and pass in a mostly-default
> > > libxl_device_nic structure, the function fills in the unspecified default
> > > config fields with data for the NIC which it has just created:
> ...
> > > Is this behaviour an intentional part of the API which I can rely on,
> > > or just an artefact of the current implementation?  In other words, is
> > > nic meant to be an (in)_out parameter?
> 
> Yes.
> 
> > I believe so, yes. The comment under "Devices" in libxl.h probably ought
> > to be adjusted to say so explicitly.
> > 
> > Ian (J) -- do you agree?
> 
> I do.  I think this applies to other kinds of device too, which might
> have unspecified parameters which get filled in.

Agreed. The docs section I was referring to is generic to all devices,
not just nics (i.e. it talks about libxl_device_<type>_add etc), so a
comment change would (and should) apply to everything.

> 
> Euan, would you like to send us a doc patch for libxl.h ?
> 
> Ian.

Re: libxl: Is the nic param to libxl_network_device_add an (in)_out parameter?

[Euan Harris]

> > I believe so, yes. The comment under "Devices" in libxl.h probably ought
> > to be adjusted to say so explicitly.
> > 
> > Ian (J) -- do you agree?
> 
> I do.  I think this applies to other kinds of device too, which might
> have unspecified parameters which get filled in.
> 
> Euan, would you like to send us a doc patch for libxl.h ?

I have sent a patch for the Devices comment.   If I come across more
functions which behave similarly I'll send more patches.

Thanks,
Euan