On Wed, 2008-11-26 at 15:07 -0800, Inaky Perez-Gonzalez wrote:

quoted text
> diff --git a/include/linux/wimax.h b/include/linux/wimax.h
> new file mode 100644
> index 0000000..f9d6a17
> --- /dev/null
> +++ b/include/linux/wimax.h
> @@ -0,0 +1,235 @@
> +/*
> + * Linux WiMax
> + * API for user space
> + *
> + *
> + * Copyright (C) 2007 Intel Corporation <linux-wimax@intel.com>
> + * Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
> + *
> + * This program is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU General Public License version
> + * 2 as published by the Free Software Foundation.

Explicitly licensing a header file that's used for userspace tools under
GPL2 might seem to indicate that the tool must be GPL2'ed as well, this
seems unintended. To be on the safe side, it seems that a lot of people
would prefer this to be under something as simple as the ISC license
just so that you can simply copy the file if necessary.

I know this hasn't been done traditionally, but in wireless a lot of
people are complaining and I know of one case where a complete header
file was "reimplemented" from scratch because of such an issue.

quoted text
> +	WIMAX_GNL_ATTR_MAX =3D 5,

This is another side effect of your decision of declaring attributes for
each command. If you didn't, you could simply do

enum wimax_attr {
	__WIMAX_GNL_ATTR_INVALID,
	WIMAX_GNL_ATTR_RFKILL_STATE,
	WIMAX_GNL_ATTR_...

	__WIMAX_GNL_ATTR_AFTER_LAST,
	WIMAX_GNL_ATTR_MAX =3D __WIMAX_GNL_ATTR_AFTER_LAST - 1
};

and have everything fall into place naturally.

Having just a single policy for all top-level attributes is a lot easier
to understand and also a lot more flexible in the long run.

quoted text
> + * Most of these map to an API call; _OP_ stands for operation, _RP_
> + * for reply and _RE_ for report (aka: signal).
> + */
> +enum {
> +	WIMAX_GNL_OP_MSG_FROM_USER,	/* User to kernel message */
> +	WIMAX_GNL_OP_MSG_TO_USER,	/* Kernel to user message */

What are those used for? Smells a lot like "iwpriv"...

quoted text
> +	WIMAX_GNL_OP_OPEN,	/* Open a handle to a wimax device */
> +	WIMAX_GNL_OP_UNUSED,	/* Unused */
> +	WIMAX_GNL_OP_RFKILL,	/* Run wimax_rfkill() */
> +	WIMAX_GNL_RP_IFINFO,	/* Reply to OPEN: Interface info */
> +	WIMAX_GNL_RP_RESULT,	/* Reply: result of operation */
> +	WIMAX_GNL_OP_RESET,	/* Run wimax_rfkill() */
> +	WIMAX_GNL_RE_STATE_CHANGE,	/* Report: status change */
> +	WIMAX_GNL_OP_MAX,

That's not MAX, it's MAX+1, see the idiom above if you really need MAX.

quoted text
> +/* Message from user / to user */
> +enum {
> +	WIMAX_GNL_MSG_DATA =3D 1,
> +};

So this is iwpriv? Why bother with an enum if you're not doing
kernel-doc?

quoted text
> +enum wimax_rf_state {
> +	WIMAX_RF_OFF =3D 0,	/* Radio is off, rfkill on/enabled */
> +	WIMAX_RF_ON =3D 1,	/* Radio is on, rfkill off/disabled */
> +	WIMAX_RF_QUERY =3D 2,
> +};
> +
> +/* Attributes */
> +enum {
> +	WIMAX_GNL_RFKILL_STATE =3D 1,
> +};

What's wrong with making that 2, and using a single enum for all the
attributes? It doesn't make a huge difference.

quoted text
> +enum {
> +	WIMAX_GNL_IFINFO_MC_GROUPS =3D 1,
> +	WIMAX_GNL_IFINFO_MC_GROUP,
> +	WIMAX_GNL_IFINFO_MC_NAME,
> +	WIMAX_GNL_IFINFO_MC_ID,
> +	WIMAX_GNL_IFINFO_MAX,		/* Used by user space */

again, not MAX, also what do you need MC_GROUP stuff for? genl mc groups
are available via the genl controller, isn't that sufficient?

quoted text
> +/*
> + * Attributes for the result-of-operation
> + */
> +enum {
> +	WIMAX_GNL_RESULT_CODE =3D 1,

This is a bit strange, what operations cannot just use the regular genl
ack message? Are these asynchronous?

quoted text
> +enum {
> +	WIMAX_GNL_STCH_STATE_OLD =3D 1,
> +	WIMAX_GNL_STCH_STATE_NEW,
> +};
> +
> +
> +/**
> + * enum wimax_st - The different states of a WiMAX device
> + * @__WIMAX_ST_NULL: The device structure has been allocated and zeroed,
> + *     but still wimax_dev_add() hasn't been called. There is no state.

That's not really available to userspace, is it? I mean, at that point
wimax-genl will just not work?

johannes