[4/5] ieee802154: add documentation about our stack

Add MAINTAINERS entry and a small text describing our stack interfaces,
how to hook the drivers, etc.

Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
Signed-off-by: Sergey Lapin <slapin@ossfans.org>
---
 Documentation/networking/ieee802154.txt |   76 +++++++++++++++++++++++++++++++
 MAINTAINERS                             |   12 +++++
 2 files changed, 88 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/networking/ieee802154.txt

Hi Dmitry,

> Add MAINTAINERS entry and a small text describing our stack interfaces,
> how to hook the drivers, etc.
> 
> Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
> Signed-off-by: Sergey Lapin <slapin@ossfans.org>
> ---
>  Documentation/networking/ieee802154.txt |   76 +++++++++++++++++++++++++++++++
>  MAINTAINERS                             |   12 +++++
>  2 files changed, 88 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/networking/ieee802154.txt
> 
> diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt
> new file mode 100644
> index 0000000..a0280ad
> --- /dev/null
> +++ b/Documentation/networking/ieee802154.txt
> @@ -0,0 +1,76 @@
> +
> +		Linux IEEE 802.15.4 implementation
> +
> +
> +Introduction
> +============
> +
> +The Linux-ZigBee project goal is to provide complete implementation
> +of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack
> +of protocols for organizing Low-Rate Wireless Personal Area Networks.
> +
> +Currently only IEEE 802.15.4 layer is implemented. We have choosen
> +to use plain Berkeley socket API, the generic Linux networking stack
> +to transfer IEEE 802.15.4 messages and a special protocol over genetlink
> +for configuration/management
> +
> +
> +Socket API
> +==========
> +
> +int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
> +.....
> +
> +The address family, socket addresses etc. are defined in the
> +include/net/ieee802154/af_ieee802154.h header or in the special header
> +in our userspace package (see either linux-zigbee sourceforge download page
> +or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee).
> +
> +One can use SOCK_RAW for passing raw data towards device xmit function. YMMV.
> +
> +
> +MLME - MAC Level Management
> +============================
> +
> +Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands.
> +See the include/net/ieee802154/nl802154.h header. Our userspace tools package
> +(see above) provides CLI configuration utility for radio interfaces and simple
> +coordinator for IEEE 802.15.4 networks as an example users of MLME protocol.
> +
> +
> +Kernel side
> +=============
> +
> +Like with WiFi, there are several types of devices implementing IEEE 802.15.4.
> +1) 'HardMAC'. The MAC layer is implemented in the device itself, the device
> +   exports MLME and data API.
> +2) 'SoftMAC' or just radio. These types of devices are just radio transceivers
> +   possibly with some kinds of acceleration like automatic CRC computation and
> +   comparation, automagic ACK handling, address matching, etc.
> +
> +Those types of devices require different approach to be hooked into Linux kernel.
> +
> +
> +HardMAC
> +=======
> +
> +See the header include/net/ieee802154/netdevice.h. You have to implement Linux
> +net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family
> +code via plain sk_buffs. The control block of sk_buffs will contain additional
> +info as described in the struct ieee802154_mac_cb.

are you sending IP packets over this ARPHRD_IEEE802154 network devices
or are you just abusing it as a control interface. If it is the later
then can we please stop doing this. I really dislike these irda0,
wmaster0 and alike stuff. If you can't configure it as real IP device,
you should not use struct net_device at all from my point of view. For
all your control details you have netlink so no need for an extra device
here unless it can actually talk IP (or similar like IPX etc.).

The irda0 code is legacy and mostly unmaintained so might not go away,
but for the wmaster0 we will remove that soon (looks at Johannes).

Regards

Marcel


--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

2009/6/5 Marcel Holtmann <marcel@holtmann.org>:
> Hi Dmitry,
>
>> Add MAINTAINERS entry and a small text describing our stack interfaces,
>> how to hook the drivers, etc.
>>
>> Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
>> Signed-off-by: Sergey Lapin <slapin@ossfans.org>
>> ---
>>  Documentation/networking/ieee802154.txt |   76 +++++++++++++++++++++++++++++++
>>  MAINTAINERS                             |   12 +++++
>>  2 files changed, 88 insertions(+), 0 deletions(-)
>>  create mode 100644 Documentation/networking/ieee802154.txt
>>
>> diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt
>> new file mode 100644
>> index 0000000..a0280ad
>> --- /dev/null
>> +++ b/Documentation/networking/ieee802154.txt
>> @@ -0,0 +1,76 @@
>> +
>> +             Linux IEEE 802.15.4 implementation
>> +
>> +
>> +Introduction
>> +============
>> +
>> +The Linux-ZigBee project goal is to provide complete implementation
>> +of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack
>> +of protocols for organizing Low-Rate Wireless Personal Area Networks.
>> +
>> +Currently only IEEE 802.15.4 layer is implemented. We have choosen
>> +to use plain Berkeley socket API, the generic Linux networking stack
>> +to transfer IEEE 802.15.4 messages and a special protocol over genetlink
>> +for configuration/management
>> +
>> +
>> +Socket API
>> +==========
>> +
>> +int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
>> +.....
>> +
>> +The address family, socket addresses etc. are defined in the
>> +include/net/ieee802154/af_ieee802154.h header or in the special header
>> +in our userspace package (see either linux-zigbee sourceforge download page
>> +or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee).
>> +
>> +One can use SOCK_RAW for passing raw data towards device xmit function. YMMV.
>> +
>> +
>> +MLME - MAC Level Management
>> +============================
>> +
>> +Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands.
>> +See the include/net/ieee802154/nl802154.h header. Our userspace tools package
>> +(see above) provides CLI configuration utility for radio interfaces and simple
>> +coordinator for IEEE 802.15.4 networks as an example users of MLME protocol.
>> +
>> +
>> +Kernel side
>> +=============
>> +
>> +Like with WiFi, there are several types of devices implementing IEEE 802.15.4.
>> +1) 'HardMAC'. The MAC layer is implemented in the device itself, the device
>> +   exports MLME and data API.
>> +2) 'SoftMAC' or just radio. These types of devices are just radio transceivers
>> +   possibly with some kinds of acceleration like automatic CRC computation and
>> +   comparation, automagic ACK handling, address matching, etc.
>> +
>> +Those types of devices require different approach to be hooked into Linux kernel.
>> +
>> +
>> +HardMAC
>> +=======
>> +
>> +See the header include/net/ieee802154/netdevice.h. You have to implement Linux
>> +net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family
>> +code via plain sk_buffs. The control block of sk_buffs will contain additional
>> +info as described in the struct ieee802154_mac_cb.
>
> are you sending IP packets over this ARPHRD_IEEE802154 network devices
> or are you just abusing it as a control interface. If it is the later
> then can we please stop doing this. I really dislike these irda0,
> wmaster0 and alike stuff. If you can't configure it as real IP device,
> you should not use struct net_device at all from my point of view. For
> all your control details you have netlink so no need for an extra device
> here unless it can actually talk IP (or similar like IPX etc.).

Hmm. Once I've thought about it, as net_device seemed a Really Big Thing to me
to be used for our stack. However from the beginning we wanted to use plain BSD
sockets API, we wanted to use sk_buffs (of course) for the whole
message interface.
And when prototyping lowpan_device, I ended duplicating lots of net_device
functionality on my own.
Either we have to develop some lightweight "net_device" abstracted from IP & Ko,
but containing sk_buff queues, header ops, etc, or end up with functionality
duplication and hacks like in bluetooth (where skb->dev is used to store hci_dev
instead of net_device).

Hmm. AX.25, AppleTalk, CAN, DecNet, most of other procotols sitting inside
Linux kernel do use net_device structure, why should we differ?

Moreover, once we implement 6lowpan support (an encapsulation for IPv6 frames
into IEEE 802.15.4 ones) it will be possible to send IPv6 frames directly over
IEEE 802.15.4.

Hi Dmitry,

> >> Add MAINTAINERS entry and a small text describing our stack interfaces,
> >> how to hook the drivers, etc.
> >>
> >> Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
> >> Signed-off-by: Sergey Lapin <slapin@ossfans.org>
> >> ---
> >>  Documentation/networking/ieee802154.txt |   76 +++++++++++++++++++++++++++++++
> >>  MAINTAINERS                             |   12 +++++
> >>  2 files changed, 88 insertions(+), 0 deletions(-)
> >>  create mode 100644 Documentation/networking/ieee802154.txt
> >>
> >> diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt
> >> new file mode 100644
> >> index 0000000..a0280ad
> >> --- /dev/null
> >> +++ b/Documentation/networking/ieee802154.txt
> >> @@ -0,0 +1,76 @@
> >> +
> >> +             Linux IEEE 802.15.4 implementation
> >> +
> >> +
> >> +Introduction
> >> +============
> >> +
> >> +The Linux-ZigBee project goal is to provide complete implementation
> >> +of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack
> >> +of protocols for organizing Low-Rate Wireless Personal Area Networks.
> >> +
> >> +Currently only IEEE 802.15.4 layer is implemented. We have choosen
> >> +to use plain Berkeley socket API, the generic Linux networking stack
> >> +to transfer IEEE 802.15.4 messages and a special protocol over genetlink
> >> +for configuration/management
> >> +
> >> +
> >> +Socket API
> >> +==========
> >> +
> >> +int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
> >> +.....
> >> +
> >> +The address family, socket addresses etc. are defined in the
> >> +include/net/ieee802154/af_ieee802154.h header or in the special header
> >> +in our userspace package (see either linux-zigbee sourceforge download page
> >> +or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee).
> >> +
> >> +One can use SOCK_RAW for passing raw data towards device xmit function. YMMV.
> >> +
> >> +
> >> +MLME - MAC Level Management
> >> +============================
> >> +
> >> +Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands.
> >> +See the include/net/ieee802154/nl802154.h header. Our userspace tools package
> >> +(see above) provides CLI configuration utility for radio interfaces and simple
> >> +coordinator for IEEE 802.15.4 networks as an example users of MLME protocol.
> >> +
> >> +
> >> +Kernel side
> >> +=============
> >> +
> >> +Like with WiFi, there are several types of devices implementing IEEE 802.15.4.
> >> +1) 'HardMAC'. The MAC layer is implemented in the device itself, the device
> >> +   exports MLME and data API.
> >> +2) 'SoftMAC' or just radio. These types of devices are just radio transceivers
> >> +   possibly with some kinds of acceleration like automatic CRC computation and
> >> +   comparation, automagic ACK handling, address matching, etc.
> >> +
> >> +Those types of devices require different approach to be hooked into Linux kernel.
> >> +
> >> +
> >> +HardMAC
> >> +=======
> >> +
> >> +See the header include/net/ieee802154/netdevice.h. You have to implement Linux
> >> +net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family
> >> +code via plain sk_buffs. The control block of sk_buffs will contain additional
> >> +info as described in the struct ieee802154_mac_cb.
> >
> > are you sending IP packets over this ARPHRD_IEEE802154 network devices
> > or are you just abusing it as a control interface. If it is the later
> > then can we please stop doing this. I really dislike these irda0,
> > wmaster0 and alike stuff. If you can't configure it as real IP device,
> > you should not use struct net_device at all from my point of view. For
> > all your control details you have netlink so no need for an extra device
> > here unless it can actually talk IP (or similar like IPX etc.).
> 
> Hmm. Once I've thought about it, as net_device seemed a Really Big Thing to me
> to be used for our stack. However from the beginning we wanted to use plain BSD
> sockets API, we wanted to use sk_buffs (of course) for the whole
> message interface.
> And when prototyping lowpan_device, I ended duplicating lots of net_device
> functionality on my own.
> Either we have to develop some lightweight "net_device" abstracted from IP & Ko,
> but containing sk_buff queues, header ops, etc, or end up with functionality
> duplication and hacks like in bluetooth (where skb->dev is used to store hci_dev
> instead of net_device).

that skb->dev pointer is typed as net_device is just a cosmetic detail
from my point of view. And having Bluetooth use it as hci_dev is not
actually a hack. We just can't send Bluetooth HCI skb directly to the IP
layer, but we also don't do that ;)

> Hmm. AX.25, AppleTalk, CAN, DecNet, most of other procotols sitting inside
> Linux kernel do use net_device structure, why should we differ?

Don't know about CAN since I never looked deep enough into it. However
for the other, they do transport some sort of networking packets over
it. So my point is as long as I can use ifconfig of ip to set an address
on these interfaces and route them it makes sense to. Just to reuse
net_device because it is convenient for a control interface sounds wrong
to me. The IrDA stuff is one big example of this.

> Moreover, once we implement 6lowpan support (an encapsulation for IPv6 frames
> into IEEE 802.15.4 ones) it will be possible to send IPv6 frames directly over
> IEEE 802.15.4.

So using the socket interfaces has nothing do with the net_device you
are creating. So that argument doesn't work for me. Even mac80211
nowadays uses a proper hardware abstraction (ieee80211_hw and
ieee80211_ops) and you should do the same.

Once you have actually implemented 6lowpan then these are the ones that
should use net_device and show up within ifconfig.

Regards

Marcel


--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

2009/6/5 Marcel Holtmann <marcel@holtmann.org>:
> Hi Dmitry,
>
>> >> Add MAINTAINERS entry and a small text describing our stack interfaces,
>> >> how to hook the drivers, etc.
>> >>
>> >> Signed-off-by: Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
>> >> Signed-off-by: Sergey Lapin <slapin@ossfans.org>
>> >> ---
>> >>  Documentation/networking/ieee802154.txt |   76 +++++++++++++++++++++++++++++++
>> >>  MAINTAINERS                             |   12 +++++
>> >>  2 files changed, 88 insertions(+), 0 deletions(-)
>> >>  create mode 100644 Documentation/networking/ieee802154.txt
>> >>
>> >> diff --git a/Documentation/networking/ieee802154.txt b/Documentation/networking/ieee802154.txt
>> >> new file mode 100644
>> >> index 0000000..a0280ad
>> >> --- /dev/null
>> >> +++ b/Documentation/networking/ieee802154.txt
>> >> @@ -0,0 +1,76 @@
>> >> +
>> >> +             Linux IEEE 802.15.4 implementation
>> >> +
>> >> +
>> >> +Introduction
>> >> +============
>> >> +
>> >> +The Linux-ZigBee project goal is to provide complete implementation
>> >> +of IEEE 802.15.4 / ZigBee / 6LoWPAN protocols. IEEE 802.15.4 is a stack
>> >> +of protocols for organizing Low-Rate Wireless Personal Area Networks.
>> >> +
>> >> +Currently only IEEE 802.15.4 layer is implemented. We have choosen
>> >> +to use plain Berkeley socket API, the generic Linux networking stack
>> >> +to transfer IEEE 802.15.4 messages and a special protocol over genetlink
>> >> +for configuration/management
>> >> +
>> >> +
>> >> +Socket API
>> >> +==========
>> >> +
>> >> +int sd = socket(PF_IEEE802154, SOCK_DGRAM, 0);
>> >> +.....
>> >> +
>> >> +The address family, socket addresses etc. are defined in the
>> >> +include/net/ieee802154/af_ieee802154.h header or in the special header
>> >> +in our userspace package (see either linux-zigbee sourceforge download page
>> >> +or git tree at git://linux-zigbee.git.sourceforge.net/gitroot/linux-zigbee).
>> >> +
>> >> +One can use SOCK_RAW for passing raw data towards device xmit function. YMMV.
>> >> +
>> >> +
>> >> +MLME - MAC Level Management
>> >> +============================
>> >> +
>> >> +Most of IEEE 802.15.4 MLME interfaces are directly mapped on netlink commands.
>> >> +See the include/net/ieee802154/nl802154.h header. Our userspace tools package
>> >> +(see above) provides CLI configuration utility for radio interfaces and simple
>> >> +coordinator for IEEE 802.15.4 networks as an example users of MLME protocol.
>> >> +
>> >> +
>> >> +Kernel side
>> >> +=============
>> >> +
>> >> +Like with WiFi, there are several types of devices implementing IEEE 802.15.4.
>> >> +1) 'HardMAC'. The MAC layer is implemented in the device itself, the device
>> >> +   exports MLME and data API.
>> >> +2) 'SoftMAC' or just radio. These types of devices are just radio transceivers
>> >> +   possibly with some kinds of acceleration like automatic CRC computation and
>> >> +   comparation, automagic ACK handling, address matching, etc.
>> >> +
>> >> +Those types of devices require different approach to be hooked into Linux kernel.
>> >> +
>> >> +
>> >> +HardMAC
>> >> +=======
>> >> +
>> >> +See the header include/net/ieee802154/netdevice.h. You have to implement Linux
>> >> +net_device, with .type = ARPHRD_IEEE802154. Data is exchanged with socket family
>> >> +code via plain sk_buffs. The control block of sk_buffs will contain additional
>> >> +info as described in the struct ieee802154_mac_cb.
>> >
>> > are you sending IP packets over this ARPHRD_IEEE802154 network devices
>> > or are you just abusing it as a control interface. If it is the later
>> > then can we please stop doing this. I really dislike these irda0,
>> > wmaster0 and alike stuff. If you can't configure it as real IP device,
>> > you should not use struct net_device at all from my point of view. For
>> > all your control details you have netlink so no need for an extra device
>> > here unless it can actually talk IP (or similar like IPX etc.).
>>
>> Hmm. Once I've thought about it, as net_device seemed a Really Big Thing to me
>> to be used for our stack. However from the beginning we wanted to use plain BSD
>> sockets API, we wanted to use sk_buffs (of course) for the whole
>> message interface.
>> And when prototyping lowpan_device, I ended duplicating lots of net_device
>> functionality on my own.
>> Either we have to develop some lightweight "net_device" abstracted from IP & Ko,
>> but containing sk_buff queues, header ops, etc, or end up with functionality
>> duplication and hacks like in bluetooth (where skb->dev is used to store hci_dev
>> instead of net_device).
>
> that skb->dev pointer is typed as net_device is just a cosmetic detail
> from my point of view. And having Bluetooth use it as hci_dev is not
> actually a hack. We just can't send Bluetooth HCI skb directly to the IP
> layer, but we also don't do that ;)
>
>> Hmm. AX.25, AppleTalk, CAN, DecNet, most of other procotols sitting inside
>> Linux kernel do use net_device structure, why should we differ?
>
> Don't know about CAN since I never looked deep enough into it. However
> for the other, they do transport some sort of networking packets over
> it. So my point is as long as I can use ifconfig of ip to set an address
> on these interfaces and route them it makes sense to. Just to reuse
> net_device because it is convenient for a control interface sounds wrong
> to me. The IrDA stuff is one big example of this.

Hmm. Let's make things clear: do you request for ip/ifconfig to be working
 upon a net_device or do you request that network packets are transmitted
over the net_device?

>> Moreover, once we implement 6lowpan support (an encapsulation for IPv6 frames
>> into IEEE 802.15.4 ones) it will be possible to send IPv6 frames directly over
>> IEEE 802.15.4.
>
> So using the socket interfaces has nothing do with the net_device you
> are creating. So that argument doesn't work for me. Even mac80211
> nowadays uses a proper hardware abstraction (ieee80211_hw and
> ieee80211_ops) and you should do the same.

We have more or less the same abstraction for the simple radios (if you'd like,
please check the serie at the branch for-review-v2, or the serie that was posted
several days ago. Basically simple radio provide interface for packet rx/tx,
energy detection, etc. Then mac802154 (mac80211 analogy) comes into play:
all radio packets, queue processing, etc. are guided by master interface, which
multiplexes packets  from/to one or several ARPHRD_IEEE802154 interfaces.
Those interfaces then decode if the packet is beacon, command or data frame,
passes data frames to socket family, calls netlink callbacks for commands, etc.

While I understand that master interface can be dropped/replaced by
non-net_device thing, I think that logical interfaces should be provided
via net_device. Please correct me if I'm wrong here.

For HardMAC (that part that is presented in this patchseri) we've cut
this scheme
directly at ARPHRD_IEEE802154 device. The device driver on it's own sends/
receives data frames via hardware and calls MLME callbacks where appropriate.

> Once you have actually implemented 6lowpan then these are the ones that
> should use net_device and show up within ifconfig.

On Fri, Jun 5, 2009 at 6:25 PM, Marcel Holtmann<marcel@holtmann.org> wrote:
>> Hmm. AX.25, AppleTalk, CAN, DecNet, most of other procotols sitting inside
>> Linux kernel do use net_device structure, why should we differ?
>
> Don't know about CAN since I never looked deep enough into it. However
> for the other, they do transport some sort of networking packets over
> it. So my point is as long as I can use ifconfig of ip to set an address
> on these interfaces and route them it makes sense to. Just to reuse
> net_device because it is convenient for a control interface sounds wrong
> to me. The IrDA stuff is one big example of this.
>

ieee802154 does actually transport networking packets. It is
networking and not just another peer-to-peer interface, so I guess it
shall be implemented as a network.

Kind regards,
Maxim
--
To unsubscribe from this list: send the line "unsubscribe netdev" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html