espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2026-08-15 15:17:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Initial preparation to post I-D.rquattle-spinel-unified to Internet D… (#1596)

Browse Source 
* Initial preparation to post I-D.rquattle-spinel-unified to Internet Draft queue.

- Rename draft-spinel-protocol to draft-rquattle-spinel-unified.
- Starting point for I-D.rquattle-spinel-basis, i.e. the non-Thread basis of Spinel.
- Change IID to NLI (issue #1488)
- Move the glossary to {spinel-basis-glossary.md} so it can be included from both drafts.
- Correct a character encoding problem in {spinel-data-packing.md}.

* Add a comment to note the IPR category.
This commit is contained in:
james woodyatt
2017-04-26 15:21:10 -07:00
committed by Jonathan Hui
parent f392421d2c
commit 988648f3cb
6 changed files with 276 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/spinel-protocol-src/draft-rquattle-spinel-basis.md.in
+184
View File
@@ -0,0 +1,184 @@
%%%
title = "Spinel: A basis for control and management of network interface co-processors"
abbrev = "Spinel Basis (@SOURCE_VERSION@)"
category = "std"
docName = "draft-rquattle-spinel-basis-@SOURCE_VERSION@"
ipr = "trust200902"
keyword = ["Spinel", "IPv6", "NCP"]
date = @SOURCE_DATE@
[pi]
editing = "yes"
private = "OpenThread"
compact = "yes"
subcompact = "yes"
comments = "yes"
[[author]]
initials = "R."
surname = "Quattlebaum"
fullname = "Robert S. Quattlebaum"
organization = "Nest Labs"
[author.address]
email = "[email protected]"
[author.address.postal]
street = "3400 Hillview Ave."
city = "Palo Alto"
region = "California"
code = "94304"
country = "USA"
[[author]]
initials = "j.h."
surname = "woodyatt"
fullname = "james woodyatt"
organization = "Google, Inc."
role = "editor"
[author.address]
email = "[email protected]"
[author.address.postal]
street = "3400 Hillview Ave."
city = "Palo Alto"
region = "California"
code = "94304"
country = "USA"
%%%
.# Abstract
This document specifies the basis of the Spinel protocol, which facilitates the control and management of IPv6 network interfaces in nodes where general purpose application processors offload network functions at their interfaces to network co-processors (NCP) connected by simple communication links like serial data channels. Spinel was initially designed for use with Thread network co-processors, but its basis is general purpose and intended to be easily adapted to other types of IPv6 network interface.
{mainmatter}
# Introduction #
Spinel is designed to enable the interoperation over simple serial connections between general purpose device operating systems (OS) and network co-processors (NCP) for the purpose of controlling and managing their IPv6 network interfaces, achieving the following goals:
* Adopt a layered approach to the protocol design, allowing future support for other types of IPv6 link.
* Minimize the number of required commands/methods by supporting a rich, property-based programming interface.
* Support NCPs capable of multiple simultaneous IPv6 interfaces.
* Support NCPs capable of communicating simultaneously on more than one physical link.
* Gracefully handle the addition of new features and capabilities without necessarily breaking backward compatibility.
* Be as minimal and light-weight as possible without unnecessarily sacrificing flexibility.
On top of this core framework, properties and commands enable various common features of IPv6. In related and forthcoming documents, the Spinel protocol is extended to support NCP implementations for specific IPv6 link types, e.g. Thread.
## Property Overview ##
Spinel is largely a property-based protocol, similar to representational state transfer (REST), with a property defined for every attribute that an OS needs to create, read, update or delete in the function of an IPv6 interface. The inspiration of this approach was memory-mapped hardware registers for peripherals. The goal is to avoid, as much as possible, the use of large complicated structures and/or method argument lists. The reason for avoiding these is because they have a tendency to change, especially early in development. Adding or removing a property from a structure can render the entire protocol incompatible. By using properties, you simply extend the protocol with an additional property.
Almost all features and capabilities are implemented using properties. Most new features that are initially proposed as commands can be adapted to be property-based instead. Notable exceptions include "Host Buffer Offload" ((#feature-host-buffer-offload)) and "Network Save" ((#feature-network-save)).
In Spinel, properties are keyed by an unsigned integer between 0 and 2,097,151 (See (#packed-unsigned-integer)).
### Property Methods ###
Properties may support one or more of the following methods:
* `VALUE_GET`
* `VALUE_SET`
* `VALUE_INSERT`
* `VALUE_REMOVE`
Additionally, the NCP can send updates to the host (either synchronously or asynchronously) that inform the host about changes to specific properties:
* `VALUE_IS`
* `VALUE_INSERTED`
* `VALUE_REMOVED`
### Property Types ###
Conceptually, there are three different types of properties:
* Single-value properties
* Multiple-value (Array) properties
* Stream properties
#### Single-Value Properties ####
Single-value properties are properties that have a simple representation of a single value. Examples would be:
* Current radio channel (Represented as a unsigned 8-bit integer)
* Network name (Represented as a UTF-8 encoded string)
* 802\.15.4 PAN ID (Represented as a unsigned 16-bit integer)
The valid operations on these sorts of properties are `GET` and `SET`.
#### Multiple-Value Properties ####
Multiple-Value Properties have more than one value associated with them. Examples would be:
* List of channels supported by the radio hardware.
* List of IPv6 addresses assigned to the interface.
* List of capabilities supported by the NCP.
The valid operations on these sorts of properties are `VALUE_GET`, `VALUE_SET`, `VALUE_INSERT`, and `VALUE_REMOVE`.
When the value is fetched using `VALUE_GET`, the returned value is the concatenation of all of the individual values in the list. If the length of the value for an individual item in the list is not defined by the type then each item returned in the list is prepended with a length (See (#arrays)). The order of the returned items, unless explicitly defined for that specific property, is undefined.
`VALUE_SET` provides a way to completely replace all previous values. Calling `VALUE_SET` with an empty value effectively instructs the NCP to clear the value of that property.
`VALUE_INSERT` and `VALUE_REMOVE` provide mechanisms for the insertion or removal of individual items *by value*. The payload for these commands is a plain single value.
#### Stream Properties ####
Stream properties are special properties representing streams of data. Examples would be:
* Network packet stream ((#prop-stream-net))
* Raw packet stream ((#prop-stream-raw))
* Debug message stream ((#prop-stream-debug))
* Network Beacon stream ((#prop-mac-scan-beacon))
All such properties emit changes asynchronously using the `VALUE_IS` command, sent from the NCP to the host. For example, as IPv6 traffic is received by the NCP, the IPv6 packets are sent to the host by way of asynchronous `VALUE_IS` notifications.
Some of these properties also support the host send data back to the NCP. For example, this is how the host sends IPv6 traffic to the NCP.
These types of properties generally do not support `VALUE_GET`, as it is meaningless.
{{spinel-frame-format.md}}
{{spinel-data-packing.md}}
{{spinel-commands.md}}
{{spinel-prop.md}}
{{spinel-status-codes.md}}
{{spinel-tech-thread.md}}
{{spinel-feature-network-save.md}}
{{spinel-feature-host-buffer-offload.md}}
{{spinel-feature-jam-detect.md}}
{{spinel-feature-gpio.md}}
{{spinel-feature-trng.md}}
{{spinel-security-considerations.md}}
{backmatter}
{{spinel-framing.md}}
{{spinel-test-vectors.md}}
{{spinel-example-sessions.md}}
{{spinel-basis-glossary.md}}
# Acknowledgments #
Special thanks to Abtin Keshavarzian, Martin Turon, Arjuna Sivasithambaresan and Jonathan Hui for their substantial contributions and feedback related to this document.
<!-- Editor
-- If we have missed anyone who has contributed to this document, please let the editor know ASAP.
-->
This document was prepared using [mmark](https://github.com/miekg/mmark) by (Miek Gieben) and [xml2rfc (version 2)](http://xml2rfc.ietf.org/).
doc/spinel-protocol-src/draft-spinel-protocol.md.in → doc/spinel-protocol-src/draft-rquattle-spinel-unified.md.in
+54 -61
View File
@@ -1,34 +1,51 @@
%%%
title = "Spinel Host-Controller Protocol"
abbrev = "Spinel Protocol (@SOURCE_VERSION@)"
category = "std"
docName = "draft-spinel-protocol-@SOURCE_VERSION@"
ipr = "none"
keyword = ["Spinel", "OpenThread", "Thread", "NCP"]
date = @SOURCE_DATE@
title = "Spinel Host-Controller Protocol"
abbrev = "Spinel Protocol (@SOURCE_VERSION@)"
category = "info"
docName = "draft-rquattle-spinel-unified-@SOURCE_VERSION@"
ipr = "noDerivativesTrust200902"
keyword = ["Spinel", "IPv6", "NCP"]
date = @SOURCE_DATE@
[pi]
editing = "yes"
private = "OpenThread"
compact = "yes"
subcompact = "yes"
comments = "yes"
[[author]]
initials = "R."
surname = "Quattlebaum"
fullname = "Robert S. Quattlebaum"
role = "editor"
organization = "Nest Labs"
[author.address]
email = "[email protected]"
[author.address.postal]
street = "3400 Hillview Ave."
city = "Palo Alto"
region = "California"
code = "94304"
country = "USA"
editing = "yes"
private = "OpenThread"
compact = "yes"
subcompact = "yes"
comments = "yes"
[[author]]
initials = "R."
surname = "Quattlebaum"
fullname = "Robert S. Quattlebaum"
organization = "Nest Labs"
[author.address]
email = "[email protected]"
[author.address.postal]
street = "3400 Hillview Ave."
city = "Palo Alto"
region = "California"
code = "94304"
country = "USA"
[[author]]
initials = "j.h."
surname = "woodyatt"
fullname = "james woodyatt"
organization = "Google, Inc."
role = "editor"
[author.address]
email = "[email protected]"
[author.address.postal]
street = "3400 Hillview Ave."
city = "Palo Alto"
region = "California"
code = "94304"
country = "USA"
%%%
.# Abstract
@@ -46,13 +63,18 @@ This document is a work in progress and subject to change.
.# Copyright Notice
Copyright (c) 2016, Nest Labs, Inc.
Copyright (c) 2016-2017, Nest Labs, Inc.
All rights reserved.
<!-- RQ
-- We may want to consider a license more appropriate for documentation.
-->
<!-- jhw
-- I have set the IPR field in the preamble to 'noDerivativesTrust200902'
while we are not ready to give change control of Spinel to IETF.
-->
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
@@ -334,6 +356,8 @@ is meaningless.
{{spinel-example-sessions.md}}
{{spinel-basis-glossary.md}}
# Acknowledgments #
Special thanks to Abtin Keshavarzian, Martin Turon, Arjuna Sivasithambaresan
@@ -347,34 +371,3 @@ to this document.
This document was prepared using [mmark](https://github.com/miekg/mmark)
by (Miek Gieben) and [xml2rfc (version 2)](http://xml2rfc.ietf.org/).
# Glossary #
<!-- RQ -- Alphabetize before finalization. -->
NCP
: Acronym for Network Control Processor.
Host
: Computer or Micro-controller which controls the NCP.
TID
: Transaction Identifier. May be a value between zero and fifteen.
See (#tid-transaction-identifier) for more information.
IID
: Interface Identifier. May be a value between zero and three.
See (#iid-interface-identifier) for more information.
PUI
: Packed Unsigned Integer. A way to serialize an unsigned integer
using one, two, or three bytes. Used throughout the Spinel protocol.
See (#packed-unsigned-integer) for more information.
FCS
: Final Checksum. Bytes added to the end of a packet to help determine
if the packet was received without corruption.
PHY
: Physical layer. Refers to characteristics and parameters related to
the physical implementation and operation of a networking medium.
doc/spinel-protocol-src/spinel-basis-glossary.md
+24
View File
@@ -0,0 +1,24 @@
# Glossary #
<!-- RQ -- Alphabetize before finalization. -->
NCP
: Network Control Processor.
OS
: Operating System, i.e. the IPv6 node using Spinel to control and manage one or more of its IPv6 network interfaces.
TID
: Transaction Identifier. May be a value between zero and fifteen. See (#tid-transaction-identifier) for more information.
NLI
: Network Link Identifier. May be a value between zero and three. See (#nli-network-link-identifier) for more information.
PUI
: Packed Unsigned Integer. A way to serialize an unsigned integer using one, two, or three bytes. Used throughout the Spinel protocol. See (#packed-unsigned-integer) for more information.
FCS
: Final Checksum. Bytes added to the end of a packet to help determine if the packet was received without corruption.
PHY
: Physical layer. Refers to characteristics and parameters related to the physical implementation and operation of a networking medium.
doc/spinel-protocol-src/spinel-data-packing.md
+1 -1
View File
@@ -123,7 +123,7 @@ minus 9. (9 is the number of bytes taken up by a byte and two longs)
The datatype signature `CLLDU` is illegal because we can't determine
where the last field (a zero-terminated UTF8 string) starts. But the
datatype `CLLdU` *is* legal, because the parser can determine the
exact length of the data blob—allowing it to know where the start
exact length of the data blob-- allowing it to know where the start
of the next field would be.
## Structured Data
doc/spinel-protocol-src/spinel-frame-format.md
+4 -8
View File
@@ -17,7 +17,7 @@ The header byte is broken down as follows:
0 1 2 3 4 5 6 7
+---+---+---+---+---+---+---+---+
| FLG | IID | TID |
| FLG | NLI | TID |
+---+---+---+---+---+---+---+---+
<!-- RQ -- Eventually, when https://github.com/miekg/mmark/issues/95
@@ -25,7 +25,7 @@ is addressed, the above table should be swapped out with this:
| 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|
| FLG || IID || TID ||||
| FLG || NLI || TID ||||
-->
### FLG: Flag
@@ -39,13 +39,9 @@ defining the first two bit in this way we can disambiguate between
Spinel frames and HCI frames (which always start with either `0x01`
or `0x04`) without any additional framing overhead.
### IID: Interface Identifier
### NLI: Network Link Identifier
The Interface Identifier (IID) is a number between 0 and 3 which
identifies which subinterface the frame is intended for. This allows
the protocol to support connecting to more than one network at once.
The first subinterface (0) is considered the primary subinterface and
MUST be supported. Support for all other subinterfaces is OPTIONAL.
The Network Link Identifier (NLI) is a number between 0 and 3, which is associated by the OS with one of up to four IPv6 zone indices corresponding to conceptual IPv6 interfaces on the NCP. This allows the protocol to support IPv6 nodes connecting simultaneously to more than one IPv6 network link using a single NCP instance. The first Network Link Identifier (0) MUST refer to a distinguished conceptual interface provided by the NCP for its IPv6 link type. The other three Network Link Identifiers (1, 2 and 3) MAY be dissociated from any conceptual interface.
### TID: Transaction Identifier
doc/spinel-protocol-src/spinel-test-vectors.md
+9 -9
View File
@@ -19,7 +19,7 @@ Decimal Value | Packet Octet Encoding
## Test Vector: Reset Command
* IID: 0
* NLI: 0
* TID: 0
* CMD: 1 (`CMD_RESET`)
@@ -29,7 +29,7 @@ Frame:
## Test Vector: Reset Notification
* IID: 0
* NLI: 0
* TID: 0
* CMD: 6 (`CMD_VALUE_IS`)
* PROP: 0 (`PROP_LAST_STATUS`)
@@ -41,7 +41,7 @@ Frame:
## Test Vector: Scan Beacon
* IID: 0
* NLI: 0
* TID: 0
* CMD: 7 (`CMD_VALUE_INSERTED`)
* PROP: 51 (`PROP_MAC_SCAN_BEACON`)
@@ -79,7 +79,7 @@ CMD_VALUE_SET(PROP_STREAM_NET)
## Test Vector: Fetch list of on-mesh networks
* IID: 0
* NLI: 0
* TID: 4
* CMD: 2 (`CMD_VALUE_GET`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)
@@ -90,7 +90,7 @@ Frame:
## Test Vector: Returned list of on-mesh networks
* IID: 0
* NLI: 0
* TID: 4
* CMD: 6 (`CMD_VALUE_IS`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)
@@ -111,7 +111,7 @@ Frame:
## Test Vector: Adding an on-mesh network
* IID: 0
* NLI: 0
* TID: 5
* CMD: 4 (`CMD_VALUE_INSERT`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)
@@ -130,7 +130,7 @@ Frame:
## Test Vector: Insertion notification of an on-mesh network
* IID: 0
* NLI: 0
* TID: 5
* CMD: 7 (`CMD_VALUE_INSERTED`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)
@@ -149,7 +149,7 @@ Frame:
## Test Vector: Removing a local on-mesh network
* IID: 0
* NLI: 0
* TID: 6
* CMD: 5 (`CMD_VALUE_REMOVE`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)
@@ -161,7 +161,7 @@ Frame:
## Test Vector: Removal notification of an on-mesh network
* IID: 0
* NLI: 0
* TID: 6
* CMD: 8 (`CMD_VALUE_REMOVED`)
* PROP: 90 (`PROP_THREAD_ON_MESH_NETS`)