Oni v2 (#68)

* Draft for version 2 of the ONI spec
- Reorganized controller into separate pages
- Introduce procedures for variable word alignments in high-bw streams
- Modified register access to allow queued transactions
- Introduce the possibility of optional features
- Added an expanded address map

* Fix titles

* Add address space overview

* Rewrite channel access concurrency description

* Split device page

* Remove grammatically erroneous commas

* Remove special devices section from hubs

Redundant since it is on its own file.

* Fix duplicate sections and text

- Special devices was duplicated
- Device descriptor was duplicated

* Clarify text for hub clocks

* Update text related to hub clocks

* Update device sample definitions
- Change hub conter name
- Split write and read frames

* Clarify text for concurrent access

* Manually "rebase" branches issue-1 and issue-3 on oni-v2

- An actual rebase was too difficult, so I brought those branches over
  manually

* Address review comments

* Address review comments

* Update data frame format to C-style

* Clarify acquisition counter definition

* Reference network topology on hierarchy page

- Reference the formal concept of a network topology and note that ONI
  hardware is arranged in a tiered star similar to USB

* Address review comments

* Clarify the meaning of the Trigger register

- Add and note to clarify the precise meaning of the Trigger register
  within the device register programming interface on the controller.

* Improve register maps
- Name controller registers
- Name hub info device registers
- specift gub info device address map
- add hub datasheet requirement
- clarify optional controller features

* Add link to latency register in acquisition counter admonition

* Reword device channel list

* Clarify register description
- Add glossary term for registers
- Specify cotroller and device registers con channel types page

* Address review on addresses.rst

* Address review comments

* Address further reviews to issues-40-42

* Address reviews in issue 39

* Style pass: All titles must be camel case

* Style pass: read/write

* Style pass: grammar, spelling, formatting, etc.

* Full read through of spec

- Looked over the spec as a complete document and created issues for
  things I felt unsure about
- Some formatting changes and minor textual changes for grammer,
  clarity, etc

* Added 'tomli' to lock file

---------

Co-authored-by: Aaron Cuevas Lopez <[email protected]>
Co-authored-by: jonnew <[email protected]>

Author: 3 people

Pipfile

@@ -6,6 +6,7 @@ verify_ssl = true
 [packages]
 sphinx = "*"
 pydata-sphinx-theme = "0.13.3"
+linuxdoc = "*"
 sphinx-tabs = "*"
 make = "*"
 breathe = "*"

Pipfile.lock

@@ -360,7 +360,7 @@
 <parametername><ref refid="classoni_1_1_o_n_i_exception" kindref="compound">ONIException</ref></parametername>
 </parameternamelist>
 <parameterdescription>
-<para>Thrown when there is an error during hardware initialization (e.g. an invalid device table).</para>
+<para>Thrown when there is an error during hardware initialization (e.g., an invalid device table).</para>
 </parameterdescription>
 </parameteritem>
 </parameterlist>

source/api/bindings/clroni/doxygen-xml/classoni_1_1_context.xml

@@ -25,7 +25,7 @@
         <argsstring></argsstring>
         <name>HardwareID</name>
         <briefdescription>
-<para>ONIX hub hardware ID (e.g. host or headstage type). </para>
+<para>ONIX hub hardware ID (e.g., host or headstage type). </para>
         </briefdescription>
         <detaileddescription>
         </detaileddescription>

source/api/bindings/clroni/doxygen-xml/classoni_1_1_hub.xml

@@ -179,7 +179,7 @@ bandwidths, and required response latencies. The buffer sizes default to the
 minimum size for a given device table (the maximum frame read and write sizes
 across devices in the table aligned to the bus width of hardware communication
 link). This provides the lowest latency, but is optimal only for very low
-bandwidth acquisition and deterministic and low-latency threads (e.g. those
+bandwidth acquisition and deterministic and low-latency threads (e.g., those
 found on real-time operating system). On a normal computer, these buffers can
 be set manually to optimize the bandwidth/latency trade off. For example, to
 set the buffer read and write sizes to 1024 and 8192 bytes respectively, use
@@ -255,23 +255,23 @@ Reading Data Frames
 ********************************************
 :struct:`oni_frame_t`'s are minimal packets containing metadata and raw binary
 data blocks from a single device within the device table. A
-:struct:`oni_size_t` is defined as
+:struct:`oni_frame_t` is defined as
 
 .. code-block:: c
 
-    struct oni_frame {
-        const uint64_t dev_idx;  // Device index that produced or accepts the frame
-        const uint32_t data_sz;  // Size in bytes of data buffer
-        const uint64_t time;     // Frame time (ACQCLKHZ)
-        uint8_t *data;           // Raw data block
+    struct oni_frame_t {
+        const oni_size_t dev_idx;           // Device index that produced or accepts the frame
+        const oni_size_t data_sz;           // Size in bytes of data buffer
+        const oni_counter_t acqclk_cnt;     // Acquisition clock (ACQCLKHZ) count at frame creation
+        uint8_t *data;                      // Raw data block
     };
 
 where ``dev_idx`` is the fully qualified device index within the device table
-(hub.index), ``data_sz`` is the size in bytes of the raw data block, ``time``
-is the system clock count that indicates the frame creation time, and, ``data``
-is a pointer to the raw data block. A single frame can be read from an
-acquisition context after it is started (see :ref:`start_ctx`) using repeated
-calls to ``oni_read_frame`` as follows:
+(hub.index), ``data_sz`` is the size in bytes of the raw data block,
+``acqclk_cnt`` is the acquisition clock count that indicates the frame creation
+time, and, ``data`` is a pointer to the raw data block. A single frame can be
+read from an acquisition context after it is started (see :ref:`start_ctx`)
+using repeated calls to ``oni_read_frame`` as follows:
 
 .. code-block:: c
 
@@ -310,9 +310,9 @@ steps to reading frames.
 
     // Required elements to create frame
     oni_frame_t *frame = NULL;
-    size_t dev_idx = 256;
-    size_t data_sz = 8; // or 16, 24, 32, etc
-    char data[] = {0, 1, 2, 3, 4, 5, 6, 7};
+    const size_t dev_idx = 256;
+    const size_t data_sz = 8; // Multiple of write size presented in device table
+    char data[] = {0, 1, 2, 3, 4, 5, 6, 7}; // Must be data_sz bytes long
 
     // Create a frame
     oni_create_frame(ctx, &frame, dev_idx, data, data_sz);
@@ -324,8 +324,8 @@ steps to reading frames.
     oni_destroy_frame(frame);
 
 First, a frame is created using a call to ``oni_create_frame`` (analogous to
-``oni_read_frame``, except that frame data is provided by the user instead of
-the hardware). In the preceding example, it is assumed that the user has
+``oni_read_frame``, except that frame data is provided by the caller instead of
+the hardware). In the preceding example, it is assumed that the caller has
 queried the device table to ensure that the device with qualified index 256 is
 writable and has a write size of 8 bytes. If the device at ``dev_idx`` does not
 accept writes or ``data``/``data_sz`` are not a multiple of the device write

source/api/liboni/liboni-example.rst

@@ -121,24 +121,23 @@ Frame
 ---------------------------------------
 .. struct:: oni_frame_t
 
-    .. member:: const oni_fifo_time_t time
 
-        Frame time (:macro:`ONI_OPT_ACQCLKHZ` host clock counter).
-
-    .. member:: const oni_fifo_dat_t dev_idx
+    .. member:: const oni_size_t dev_idx
 
         Device index that produced or accepts the frame.
 
+    .. member:: const oni_counter_t acqclk_cnt
+
+        Acquisition clock (:macro:`ONI_OPT_ACQCLKHZ`) count at the time
+        of frame creation.
+
     .. member:: const oni_fifo_dat_t data_sz
 
         Size of data in bytes.
 
     .. member:: uint8_t *data
 
-        Raw data block. This pointer is a zero-copy "view" into a private,
-        referenced-counted buffer managed by the acquisition context.  The
-        handle to this buffer is hidden by the API using some C ``union``
-        magic.
+        Pointer to a ``data_sz``-byte continuous data block.
 
     An ONI-compliant data frame implementation. :struct:`oni_frame_t`'s are
     produced by calls to :func:`oni_read_frame` and consumed by calls to
@@ -324,7 +323,7 @@ needed during the development of user-facing software.
 
     Change the value of a configuration register from specific devices within
     the current device table. This can be used to change the functionality of
-    devices, e.g. set filter bandwidth, select active channels, or change
+    devices, e.g., set filter bandwidth, select active channels, or change
     stimulation parameters.  Register specifications (addresses, read- and
     write-access, acceptable values, and descriptions) are provided on the
     :ref:`ONI-device datasheet <dev-datasheet>`.
@@ -346,7 +345,7 @@ needed during the development of user-facing software.
     :ref:`liboni_example_set_buffers`). :struct:`oni_frame_t`'s created during
     calls to :func:`oni_read_frame` are zero-copy views into this buffer.
 
-    .. attention:: It is the user's responsibility to free the resources allocated by
+    .. attention:: It is the caller's responsibility to free the resources allocated by
         this call by passing the resulting frame pointer to
         :func:`oni_destroy_frame`.
 
@@ -360,7 +359,7 @@ needed during the development of user-facing software.
 
     Create an :struct:`oni_frame_t` for consumption by :func:`oni_write_frame`.
 
-    .. attention:: It is the user's responsibility to free the resources allocated by
+    .. attention:: It is the caller's responsibility to free the resources allocated by
         this call by passing the resulting frame pointer to
         :func:`oni_destroy_frame`
 

source/api/liboni/oni.rst

@@ -10,9 +10,6 @@ Macro and constant definitions common to both :ref:`oni.h` and :ref:`onidriver.h
 Integer Types
 ---------------------------------------
 
-.. warning:: All of these types will be almost certainly be deprecated in
-    future API revisions to handle drivers with different channel bit widths.
-
 .. type:: uint32_t oni_size_t
 
     Data sizes are 32-bit uints.
@@ -33,13 +30,9 @@ Integer Types
 
     Registers have 32-bit values.
 
-.. type:: uint32_t oni_fifo_dat_t
-
-    FIFOs use 32-bit words.
-
-.. type:: uint64_t oni_fifo_time_t
+.. type:: uint64_t oni_counter_t
 
-    FIFO bound timers use 64-bit words.
+    Counters use 64-bit words.
 
 .. _onidef_context_options:
 

source/api/liboni/onidefs.rst

@@ -15,8 +15,8 @@ ONI specification and are not required to use the API.
 .. attention:: Many of the devices in this enumeration have no ready-made route
     to use in high-level software. This is true for a variety of reasons. For
     instance, they may be prototype hardware or test fixture that we wish to
-    maintain for backward compatibility (e.g. :macro:`ONIX_TESTREG0`). Or, they
-    may be a low level device (e.g. :macro:`ONIX_AD7617`) that is used in the
+    maintain for backward compatibility (e.g., :macro:`ONIX_TESTREG0`). Or, they
+    may be a low level device (e.g., :macro:`ONIX_AD7617`) that is used in the
     background by other, higher order devices in the list (e.g.
     :macro:`ONIX_FMCANALOG1R3`).
 

source/api/liboni/onix.rst

@@ -45,6 +45,7 @@
     'sphinx.ext.githubpages',
     'breathe',
     'sphinx_csharp',
+    'linuxdoc.rstFlatTable'
 ]
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

source/conf.py

@@ -9,16 +9,22 @@ the system:
 
   Stream Channel
     A unidirectional, asynchronous channel of continuous, N-bit word data along
-    with a signal indicating if it is ready to send/receive data. Two
-    directions are defined:
+    with a signal indicating if it is ready to send/receive data. Two directions
+    are defined:
 
     :Read:  Streams that transmit data from a device to the host computer.
     :Write: Streams that transmit data to a device from the host computer.
 
   Register Channel
-    A synchronous, bidirectional, N-bit, addressed digital bus. Each address is
-    a 32-bit value. Registers can be Read-only, Write-only or Read-Write. This
-    channel also has signals to indicate a successful or failed completion of a
-    register access operation. (e.g., An access to an non-existent address or a
-    non-allowed operation will return an error.)
+    A synchronous, bidirectional, addressed digital bus to access
+    :term:`registers<Register>`. Registers can be Read-only, Write-only or
+    Read/Write. Channels of this type MUST indicate a successful or failed
+    completion of a register access operation. (e.g., an access to a
+    non-existent address or a non-allowed operation will signal an error.)
+
+    .. note:: Both the controller and the devices can hold registers. Controller registers are
+      arranged in a fixed :ref:`address map<addresses>` and accessed through the
+      :ref:`configuration channel<conf-chan>`. :ref:`Device registers<dev-register>`
+      follow the address map defined on each device :ref:`datasheet<dev-datasheet>`
+      and are accessed through the :ref:`device register interface<register_interface>`.