Made a protocol crate and moved some docs into it.

Author: jonathanpallant

README.md

@@ -53,204 +53,12 @@ this system only one side is actually transferring useful data at any time, so
 whilst the Header is being sent the Host will receive Padding Bytes of `0xFF` in
 return (which can be discarded).
 
-A transfer is comprised of three stages.
+The NBMC exposes a number of registers - some can be read, some can be written
+to, some are cleared when written to.
 
-1. `>` Request
-2. `-` Turn-Around
-3. `<` Reponse
-
-A *Request* is a sequence of bytes sent from the *Host* to the *NBMC*.
-*Turn-Around* is a period of time of interdeterminate length during which
-the *Host* clocks out dummy bytes and the *NBMC* responds with `0xFF` bytes,
-which indicate that it has not yet formulated the *Response*. This period ends,
-with the transmission of the *Response* from the *NBMC* to the *Host*. 
-
-There are different kinds of *Request* that can be made. Each has a
-corresponding *Response*.
-
-| Request Type       | Contains                        | Length       | Response Type |
-| ------------------ | ------------------------------- | ------------ | ------------- |
-| Read               | Type, Register#, Length, CRC    | 4            | Read          |
-| Short Write        | Type, Register#, Data Byte, CRC | 4            | Short         |
-| Long Write Start   | Type, Register#, Length, CRC    | 4            | Short         |
-| Long Write Payload | `Length` Bytes, CRC             | `Length` + 1 | Short         |
-
-| Response Type | Contains                    | Length       |
-| ------------- | --------------------------- | ------------ |
-| Short         | Result, CRC                 | 2            |
-| Read          | Result, `Length` Bytes, CRC | `Length` + 2 |
-
-To allow the *NBMC* to be efficient at receiving data over SPI, it is important
-that the first *Request* received after the `nCS` pin goes active-low is of a
-fixed length. Here, all of the initial *Requests* have a fixed size of four
-bytes. A *Long Write Start Request* tells the *NBMC* to expect a *Request* of a
-different length to follow immediately after, which allows the *NBMC* to
-re-configure the DMA to expect the longer length *Request*. The *Long Write
-Payload* MUST only be sent following a *Long Write Start*, and without resetting
-the `nCS` signal in-between.
-
-### Request Types
-
-* `0xC0`: Read
-* `0xC1`: Read (alternate)
-* `0xC2`: Short Write 
-* `0xC3`: Long Write
-
-### Response Results
-
-* `0xA0`: OK
-* `0xA1`: CRC Failure
-* `0xA2`: Bad Request Type
-* `0xA3`: Bad Register#
-* `0xA4`: Bad Length
-
-### Read Request / Response Sequence
-
-A *Read Request* consists of four 8-bit values:
-
-* A *Type* byte of either `0xC0` or `0xC1` marking this as a *Read Request*.
-* A *Register#*, indicating which register within the *NBMC* the *Host* wishes
-  to read.
-* A Length, indicating how many bytes are to be read from the given *Register#*.
-* A *CRC*, which is the CRC-8 of the proceeding three bytes.
-
-The *Type* byte should alternate between `0xC0` and `0xC1` so that the *NBMC*
-can tell if the *Read Request* is a repeat of the previous request. This may
-occur, for example, if the *Read Response* fails its CRC check on arrival at the
-*Host*. Because a *Read Request* can have side-effects (like removing bytes from
-a FIFO), a repeated *Read Request* should return preceisely the same values as
-before, rather than, say, fetching more new bytes from the FIFO. This allows the
-FIFO to be read in a lossless fashion, even when there is occasional corruption
-on the SPI bus.
-
-A *Read Response* consists of a variable number of 8-bit values:
-
-* A *Response Result* code indicating whether the read operation was successful
-  or not.
-* A *Payload* consisting of the number of bytes requested in the *Read
-  Operation* (only present if the *Result* byte indicates Success)
-* A *CRC*, which is the CRC-8 of all the proceeding bytes.
-
-#### Example of Success
-
-```mermaid
-sequenceDiagram
-
-Host->>NBMC: ReadRequest(25, 5)
-Note over Host, NBMC: Read 5 bytes from Register 25
-
-NBMC->>NBMC: Reads from register
-
-NBMC->>Host: Response(OK, [0, 1, 2, 3, 4])
-
-Note over Host, NBMC: Host get the five bytes
-```
-
-#### Example of Failure
-
-```mermaid
-sequenceDiagram
-
-Host->>NBMC: ReadRequest(25, 200)
-Note over Host, NBMC: Read 200 bytes from Register 25
-
-NBMC->>Host: Response(BadLength)
-
-Note over Host, NBMC: NBMC says no.
-```
-
-### Short Write Request / Response Sequence
-
-A *Short Write Request* consists of four 8-bit values:
-
-* A *Type* byte of `0xC2` marking this as a *Short Write Request*.
-* A *Register#*, indicating which register within the *NBMC* the *Host* wishes to write to.
-* A *Data Byte*, which is to be written to the given *Register#*.
-* A *CRC*, which is the CRC-8 of the proceeding three bytes.
-
-A *Short Response* is sent in returning, containing two bytes:
-
-* A [*Response Result*](#response-result-codes) code indicating whether the read
-  operation was successful or not.
-* A *CRC*, which is the CRC-8 of all the sole proceeding byte.
-
-You could equally consider a *Short Response* as a single 16-bit big-endian
-value, being one of `0xA069`, `0xA16E`, `0xA267`, `0xA360` or `0xA475`.
-
-#### Example of Success
-
-```mermaid
-sequenceDiagram
-
-Host->>NBMC: ShortWriteRequest(10, 0xAA)
-Note over Host, NBMC: Write 0xAA to Register 10
-
-NBMC->>NBMC: Writes to register
-
-NBMC->>Host: Response(OK)
-
-Note over Host, NBMC: NBMC is happy.
-```
-
-### Long Write Request / Response Sequence
-
-A *Long Write Request* consists of four 8-bit values:
-
-* A *Type* byte of `0xC2` marking this as a *Short Write Request*.
-* A *Register#*, indicating which register within the *NBMC* the *Host* wishes to write to.
-* A *Length*, which is the number of payload bytes to follow in the subsequent *Long Write Payload*.
-* A *CRC*, which is the CRC-8 of the proceeding three bytes.
-
-A *Short Response* is sent, as per [Short Write
-Request](#short-write-request--response-sequence)
-
-If a *Short Response* is received containing a *Response Result* of **OK**
-(`0xA0`), the *NBMC* is ready to receive a *Long Write Payload*. If any other
-*Response Result* is received, the *Long Write Payload* must not be send and
-`nCS` must be raised to indicate the end of the transaction.
-
-A *Long Write Payload* consists of a variable number of 8-bit values:
-
-* A *Payload* consisting of the number of bytes requested in the *Long Write Request*
-* A *CRC*, which is the CRC-8 of all the proceeding bytes.
-
-This message must always contain exactly the number of bytes stated in the
-*Length* field of the *Long Write Request*, plus one additional CRC byte.
-
-A second *Short Response* is then sent, as per [Short Write
-Request](#short-write-request--response-sequence). The `nCS` signal must be
-raised at this point to restart the write sequence, regardless of the specific
-*Response Result* sent.
-
-#### Example of Success
-```mermaid
-sequenceDiagram
-
-Host->>NBMC: LongWriteRequest(16, 5)
-Note over Host, NBMC: Prepare to write 5 bytes to Register 16
-
-NBMC->>NBMC: Thinks for while
-
-NBMC->>Host: Response(OK)
-
-Note over Host, NBMC: NBMC is ready to take 5 bytes.
-
-Host->>NBMC: LongWritePayload([0, 1, 2, 3, 4])
-Note over Host, NBMC: Five bytes are sent
-
-NBMC->>NBMC: Checks CRC
-
-NBMC->>Host: Response(CrcFailure)
-
-Note over Host, NBMC: NBMC is sad. The five bytes<br/>must have been corrupted as their CRC didn't match.
-```
-
-### Cancelling
-
-Any *Request* can be cancelled by the *Host* lifting `nCS` high before the
-*Request* has finished sending. This allows the *NBMC* to accomodate unexpected
-*Host* reboots (as during a reboot it is expected that the `nCS` line will be
-raised).
+See [neotron-bmc-protocol's README](./neotron-bmc-protocol/README.md) for more
+details of how the registers are accessed. The registers themselves are defined
+below.
 
 ## System Registers
 

neotron-bmc-protocol/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "neotron-bmc-protocol"
+version = "0.1.0"
+edition = "2021"
+license = "BlueOak-1.0.0"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

neotron-bmc-protocol/LICENCE.md

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules.  The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice.  If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+***As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim.***