diff --git a/README.rst b/README.rst index 76bb426..e8286d2 100644 --- a/README.rst +++ b/README.rst @@ -4,9 +4,9 @@ Open Neuro Interface This documentation's source template was taken from the `Spinal HDL `_ project. -The theme is based on the `PyData Sphinx Theme `_ +The theme is based on the `PyData Sphinx Theme `_. -For more detailed usage instructions, see the `Open Ephys Doc Template `_ +For more detailed usage instructions, see the `Open Ephys Doc Template `_. How to build this documentation =============================== @@ -18,26 +18,26 @@ Requirements (Python 3): * pipenv (will automatically download all the project requirements from pypi) -Create a virtual environment with pipenv (will use the Pipfile for installing the necessary packages) +Create a virtual environment with pipenv (will use the Pipfile for installing the necessary packages). .. code:: shell pipenv install -then you can build the documentation +Then you can build the documentation. .. code:: shell pipenv run make html -if you want to run ``make`` multiple times, prepending ``pipenv run`` on each command can be annoying. -You can spawn a subshell with +If you want to run ``make`` multiple times, prepending ``pipenv run`` on each command can be annoying. +You can spawn a subshell with: .. code:: shell pipenv shell -and then you can use ``make`` the usual way +and then you can use ``make`` the usual way. .. code:: shell @@ -46,7 +46,7 @@ and then you can use ``make`` the usual way make latexpdf # for latex (will require latexpdf installed) make # list all the available output format -All the outputs will be in the docs folder (for html: docs/html) +All the outputs will be in the docs folder (for html: docs/html). without pipenv/virtualenv ------------------------- @@ -59,7 +59,7 @@ Requirements (Python 3): * sphinx * pydata-sphinx-theme=="0.13.3" -After installing the requirements you can run +After installing the requirements you can run: .. code:: shell diff --git a/source/_static/theme_overrides.css b/source/_static/theme_overrides.css index ffd69f6..d3268bd 100644 --- a/source/_static/theme_overrides.css +++ b/source/_static/theme_overrides.css @@ -81,7 +81,7 @@ /* navigation bar: when page title is selected*/ .navbar-nav > .active > .nav-link { background-color: #e6eddf !important; /* selected text background fill */ - color: #2f401f !important; /* selected text colour*/ + color: #2f401f !important; /* selected text color*/ font-weight: normal !important; transition-duration: 0.4s; /* how quickly to change*/ } diff --git a/source/api/bindings/clroni/index.rst b/source/api/bindings/clroni/index.rst index 412c0a2..b32952d 100644 --- a/source/api/bindings/clroni/index.rst +++ b/source/api/bindings/clroni/index.rst @@ -24,7 +24,7 @@ Windows ======================================= 1. Open the :code:`clroni.sln` solution in Visual Studio 2019 or newer. 2. "Running" the solution will compile the library and test program, and then - run the test program + run the test program. 3. The Nuget package can be built by right clicking the clroni project and clicking "pack". @@ -44,7 +44,7 @@ The :code:`clroni-repl` directory contains minimal working programs that use thi library 1. :code:`clroni-repl.exe` : Basic data acquisition loop. Communicate with - emmulated (e.g. :ref:`test_driver`) or actual (e.g. :ref:`riffa`) + emulated (e.g., :ref:`test_driver`) or actual (e.g., :ref:`riffa`) hardware. This will be automatically built when the Visual Studio solution is built. It diff --git a/source/api/bindings/cpponi/oni.rst b/source/api/bindings/cpponi/oni.rst index 762389e..22697cd 100644 --- a/source/api/bindings/cpponi/oni.rst +++ b/source/api/bindings/cpponi/oni.rst @@ -11,15 +11,15 @@ See https://semver.org/ for a complete explanation of these macro definitions. .. c:macro:: CPPONI_VERSION_MAJOR - MAJOR version for incompatible API changes + MAJOR version for incompatible API changes. .. c:macro:: CPPONI_VERSION_MINOR - MINOR version for added functionality that is backwards compatible + MINOR version for added functionality that is backwards compatible. .. c:macro:: CPPONI_VERSION_PATCH - PATCH version for backwards compatible bug fixes + PATCH version for backwards compatible bug fixes. .. c:macro:: CPPONI_MAKE_VERSION(major, minor, patch) @@ -37,7 +37,7 @@ See https://semver.org/ for a complete explanation of these macro definitions. .. code-block:: c - CPPONI_MAKE_VERSION(CPPONI_VERSION_MAJOR CPPONI_VERSION_MINOR, CPPONI_VERSION_PATCH). + CPPONI_MAKE_VERSION(CPPONI_VERSION_MAJOR CPPONI_VERSION_MINOR, CPPONI_VERSION_PATCH) .. function:: std::tuple oni::version() @@ -59,10 +59,10 @@ Errors Constructor. Not generally needed for cpponi use since :class:`oni::error_t` is constructed and thrown from within cpponi and - only need to be handled by the host application. + only needs to be handled by the host application. :param errnum: liboni error code integer, generally resulting from a non-zero - return value of an Underlying liboni function. + return value of an underlying liboni function. .. function:: const char *what() const noexcept override @@ -94,15 +94,15 @@ Frames `RAII `__-capable wrapper for :c:struct:`oni_frame_t`. User programs generally should not call the frame_t constructor directly but deal with frames created by a - :class:`oni::context_t` + :class:`oni::context_t`. .. function:: uint64_t time() const - :return: Underlying :c:struct:`oni_frame_t.time` + :return: Underlying :c:struct:`oni_frame_t.time`. .. function:: oni_dev_idx_t device_index() const - :return: Underlying :c:struct:`oni_frame_t.dev_idx` + :return: Underlying :c:struct:`oni_frame_t.dev_idx`. .. function:: template \ std::span data() const @@ -115,7 +115,7 @@ Frames `__ Automatically made available when compiled with stdlib >= C++20. Otherwise, this function reverts to returning a `std::vector - `__ + `__. Context -------------------------------------- @@ -140,7 +140,7 @@ Context :param host_idx: The index of the hardware we are going to manage using the initialized context and driver. A value of -1 will attempt to open the default host index and is useful if there is only a - single ONIX host managed by driver selected in :func:`oni_create_ctx` + single ONIX host managed by driver selected in :func:`oni_create_ctx`. :throws: `std::system_error `_ if underlying context cannot be allocated. @@ -160,7 +160,7 @@ Context .. function:: context_t &operator=(context_t &&rhs) noexcept - Move assignment operator. + Move assignment operator. :param rhs: Existing :class:`context_t` instance to move from. @@ -274,15 +274,15 @@ Context .. note:: ``data.size()`` must be #. An integer multiple of the selected ``dev_idx``'s write size as - indicated within the device table + indicated within the device table. #. Smaller than the internal write block memory size (see - :c:macro:`ONI_OPT_BLOCKWRITESIZE` and :ref:`liboni_example_set_buffers`) + :c:macro:`ONI_OPT_BLOCKWRITESIZE` and :ref:`liboni_example_set_buffers`). .. note:: `std::span `__ is automatically made available when compiled with stdlib >= C++20. Otherwise, this function reverts to returning a `std::vector - `__ + `__. .. seealso:: :c:func:`oni_create_frame` diff --git a/source/api/index.rst b/source/api/index.rst index fa5792d..307d9ea 100644 --- a/source/api/index.rst +++ b/source/api/index.rst @@ -31,5 +31,5 @@ Bindings :ref:`C++ Binding Reference ` C++17 & C++20 bindings for :ref:`liboni`. -:ref:`.NET Binding Refernece ` +:ref:`.NET Binding Reference ` CLR/.NET bindings for :ref:`liboni`. diff --git a/source/api/liboni/build.rst b/source/api/liboni/build.rst index 063828d..b9524ed 100644 --- a/source/api/liboni/build.rst +++ b/source/api/liboni/build.rst @@ -103,7 +103,7 @@ full leak check on ``host``: Build in Windows ******************************************** -Open the included `Visual Studio Coummunity +Open the included `Visual Studio Community `_ solution and press play. For whatever reason, it seems that the selected startup project is not consistently saved with the solution. So make sure that it is set to diff --git a/source/api/liboni/driver-translators/index.rst b/source/api/liboni/driver-translators/index.rst index 0dc297e..46d1c34 100644 --- a/source/api/liboni/driver-translators/index.rst +++ b/source/api/liboni/driver-translators/index.rst @@ -5,15 +5,15 @@ Driver Translators :Code: https://github.com/open-ephys/liboni/tree/main/api/liboni/drivers -There are a many existing `device drivers +There are many existing `device drivers `_ that support hardware for data acquisition. Some of these drivers can be used as a backend for ONI-compliant APIs if they provide some means to support the required ONI communication channels. Have a look at the :ref:`ONI controller spec ` for specifications of these channels. -An ONI hardware driver translator implements :ref:`onidriver.h` to convert, -potentially proprietary, device drivers (and corresponding hardware) into a +An ONI hardware driver translator implements :ref:`onidriver.h` to convert +potentially proprietary device drivers (and corresponding hardware) into a user space library that can be consumed by ONI-compliant APIs. These are loaded by the API at runtime and therefore are separate from the API both in terms of development and licensing requirements. diff --git a/source/api/liboni/index.rst b/source/api/liboni/index.rst index 5af1cae..c39a658 100644 --- a/source/api/liboni/index.rst +++ b/source/api/liboni/index.rst @@ -25,8 +25,8 @@ liboni implements the :ref:`oni-hw`. It is written in C to facilitate cross platform and cross-language use. It is composed of the following files: -#. :ref:`onidefs.h`: common definitions -#. :ref:`oni.h`: core API +#. :ref:`onidefs.h`: common definitions. +#. :ref:`oni.h`: core API. #. :ref:`onidriver.h`: device driver translation layer that must be implemented for a particular host hardware connection and firmware. diff --git a/source/api/liboni/liboni-example.rst b/source/api/liboni/liboni-example.rst index ebccd66..bdc6600 100644 --- a/source/api/liboni/liboni-example.rst +++ b/source/api/liboni/liboni-example.rst @@ -42,11 +42,11 @@ manage the hardware at the specified host index using the specified driver. .. note:: Specifying a host index of -1 will open the default slot and is useful in cases where there is only one piece of acquisition hardware in the - host computer (e.g. a single PCIe card). + host computer (e.g., a single PCIe card). -When multiple pieces of host hardware exist on a single host (e.g. multiple +When multiple pieces of host hardware exist on a single host (e.g., multiple PCIe cards), a new context must be created and initialized to manage each -one. In some cases (e.g. multiple PCIe cards in a single computer), these +one. In some cases (e.g., multiple PCIe cards in a single computer), these contexts can be synchronized so that each host receiver board shares a common hardware clock and acquisition trigger (see :ref:`sync_ctx` for an example). This is not always possible. For instance, multiple USB hosts cannot be @@ -55,7 +55,7 @@ synchronized. .. attention:: :func:`oni_init_ctx` cannot be called on a previously initialized context. Doing so will return an error. -If the device configuration is changed following context initialization (e.g. a +If the device configuration is changed following context initialization (e.g., a headstage is plugged in or turned on), a context reset must be issued to instruct the initialized context to re-evaluate its device table. This can be done via @@ -114,7 +114,7 @@ defined as: .. attention:: ``device_t.idx`` is the fully qualified address (hub.index) of a device within the acquisition hierarchy. Do not expect these values to increase linearly with the position in array returned when querying the device table as - some bit ranges are used to specifiy the hub address. + some bit ranges are used to specify the hub address. .. _liboni_example_read_write_reg: @@ -124,9 +124,9 @@ It is often necessary to inspect and configure devices prior to or during acquisition. As described in the ONI specification, a device is a leaf element in the device table with *at least* the following properties: -#. Its own register address space -#. Register access through a standardized register programming interface -#. A datasheet that describes access to these registers +#. Its own register address space. +#. Register access through a standardized register programming interface. +#. A datasheet that describes access to these registers. Device registers can be read as follows: @@ -139,7 +139,7 @@ Here, ``dev_idx`` is the fully specified device table index (hub.index) found in the device table, ``addr`` is the register address as specified within the ONI device datasheet. Because this is a register read, ``val`` is just a pointer to a register to be filled during the read. This function will return -an error if the context is in an inappropriate state (e.g. not initialized), +an error if the context is in an inappropriate state (e.g., not initialized), the specified device is not in the device table, or the register is write-only. Registers can be written as follows: @@ -223,7 +223,7 @@ context option: reg = 1; oni_set_opt(ctx, ONI_OPT_RUNNING, ®, sizeof(oni_size_t)); -.. attention:: Following the start of data acqusition, hardware memory +.. attention:: Following the start of data acquisition, hardware memory resources are used to queue incoming device data. To prevent buffer overflows, the user must issue calls to ``oni_read_frame`` fast enough to keep up with data production. @@ -287,7 +287,7 @@ calls to ``oni_read_frame`` as follows: In the preceding example, ``frame`` is initialized to ``NULL`` because a call to ``oni_read_frame`` will assign its contents to an existing, pre-allocated memory block (see :ref:`liboni_example_set_buffers`). ``oni_read_frame`` will -return an error if the acquisition context is in an inappropriate state (e.g. +return an error if the acquisition context is in an inappropriate state (e.g., not started). If the hardware is not producing frames, it will wait indefinitely. @@ -339,13 +339,13 @@ size, then ``oni_create_frame`` will return an error. .. warning:: Attempting to write multi-packet frames that are larger than :macro:`ONI_OPT_BLOCKWRITESIZE` will result in a error. -After a frame has been created, it can then be written to to hardware using +After a frame has been created, it can then be written to hardware using ``oni_write_frame``. Just like frames produced by ``oni_read_frame``, frames generated by ``oni_create_frame`` must be disposed of using ``oni_destroy_frame`` when the are no longer needed. .. tip:: Frames created using ``oni_create_frame`` can be reused by re-writing - their data field following a frame write + their data field following a frame write. The following example shows a single frame being used for two writes with a change in the data field in between writes: diff --git a/source/api/liboni/making-drivers.rst b/source/api/liboni/making-drivers.rst index 06d7b07..2737dda 100644 --- a/source/api/liboni/making-drivers.rst +++ b/source/api/liboni/making-drivers.rst @@ -33,7 +33,7 @@ opaque pointer of type :c:type:`oni_driver_ctx` and stored in a field of in :c:func:`oni_driver_create_ctx` and accessed through the :c:type:`oni_driver_ctx` parameter present in most function calls. No static variables can be used to keep any state information. This is necessary for multiple instances of the driver - to exist simultaneously, acessing different devices of the same type. + to exist simultaneously, accessing different devices of the same type. An example of such a context for a simple, file-descriptor accessed device, could be @@ -106,7 +106,7 @@ operation. all allocated resources. .. code-block:: c - :caption: Context managment examples + :caption: Context management examples. oni_driver_ctx oni_driver_create_ctx() { @@ -164,7 +164,7 @@ interface used. else return ONI_EPATHINVALID; } -.. note:: Read operations must return the same number of bytes as requested, or it will be treated as an error +.. note:: Read operations must return the same number of bytes as requested, or it will be treated as an error. .. _making_drivers_functions_register: @@ -180,7 +180,7 @@ Again, the specifics on how to access such registers are dependent on the hardwa trigger, when performing a reset or starting/stopping acquisition. .. code-block:: c - :caption: Examples of register access + :caption: Examples of register access. int oni_driver_read_config(oni_driver_ctx driver_ctx, oni_config_t config, oni_reg_val_t *value) { @@ -232,7 +232,7 @@ function can simply return :c:macro:`ONI_ESUCCESS`. would act before, during low-level register access. .. code-block:: c - :caption: Example post-option callback + :caption: Example post-option callback. int oni_driver_set_opt_callback(oni_driver_ctx driver_ctx, int oni_option, const void *value, size_t option_len) { @@ -267,10 +267,10 @@ A driver translator must be able to report its name and version information. This is done using the :ref:`oni_driver_info_t` structure, which contains information following the `Semantic Versioning `_ specification. This structure should be a constant, and a pointer to it should -be returned by :c:func:`oni_get_driver_info` +be returned by :c:func:`oni_get_driver_info`. .. code-block:: c - :caption: Example implemention + :caption: Example implementation const oni_driver_info_t oni_driver_info = { .name = "simple", diff --git a/source/api/liboni/oni.rst b/source/api/liboni/oni.rst index 3668cc6..f5f91e1 100644 --- a/source/api/liboni/oni.rst +++ b/source/api/liboni/oni.rst @@ -51,13 +51,13 @@ Acquisition Context .. attention:: Context details are hidden in the implementation file (``oni.c``). Direct manipulation of :type:`oni_ctx` data members is never - nessesary or correct. + necessary or correct. Each :type:`oni_ctx` instance manages the device driver, device table, read and write buffers, acquisition run state, etc. Following a hardware reset, which is triggered either by a call to :func:`oni_init_ctx` or :func:`oni_set_opt` using the :macro:`ONI_OPT_RESET` context option, the - context run state is set to ``UNINTIALIZED`` and the device table is pushed + context run state is set to ``UNINITIALIZED`` and the device table is pushed onto the host signal stream by the host hardware as `COBS `_-encoded packets. On the signal stream, the device table is organized as follows, @@ -86,28 +86,28 @@ Device Fully qualified **RSV.RSV.HUB.IDX** device table index. - :RSV: 8-bit unsigned integer (reserved) - :HUB: 8-bit unsigned integer indicating the hub index - :IDX: 8-bit unsigned integer indicating the device index + :RSV: 8-bit unsigned integer (reserved). + :HUB: 8-bit unsigned integer indicating the hub index. + :IDX: 8-bit unsigned integer indicating the device index. .. member:: oni_dev_id_t id - Device ID number (see :ref:`onix.h` for ONIX-specific definitions) + Device ID number (see :ref:`onix.h` for ONIX-specific definitions). .. member:: oni_size_t read_size - Device data read size per frame in bytes + Device data read size per frame in bytes. .. member:: oni_size_t write_size - Device data write size per frame in bytes + Device data write size per frame in bytes. An ONI-compliant device implementation. An :struct:`oni_device_t` describes one of potentially many pieces of hardware managed by an :type:`oni_ctx`. Examples of individual devices might include ephys chips, IMUs, optical stimulators, camera sensors, etc. - .. tip:: Look at device index defintions in :ref:`onix.h` to see available + .. tip:: Look at device index definitions in :ref:`onix.h` to see available ONIX-specific device definitions and enum ranges that will not interfere with ONIX for custom or closed-source projects. @@ -123,15 +123,15 @@ Frame .. member:: const oni_fifo_time_t time - Frame time (:macro:`ONI_OPT_ACQCLKHZ` host clock counter) + Frame time (:macro:`ONI_OPT_ACQCLKHZ` host clock counter). .. member:: const oni_fifo_dat_t dev_idx - Device index that produced or accepts the frame + Device index that produced or accepts the frame. .. member:: const oni_fifo_dat_t data_sz - Size of data in bytes + Size of data in bytes. .. member:: uint8_t *data @@ -186,7 +186,7 @@ needed during the development of user-facing software. streaming, memory management, etc. On success the selected driver is loaded and an :type:`oni_ctx` is allocated and created, and its handle is passed to the user. Many API functions take a :type:`oni_ctx` as a first - agrument. + argument. :param drv_name: A string specifying the device driver used by the context to control hardware. This string corresponds a compiled @@ -196,14 +196,14 @@ needed during the development of user-facing software. :return: An opaque handle to the newly created context if successful. Otherwise it shall return ``NULL`` and set ``errno`` to ``EAGAIN``. - :example: See :ref:`liboni_example_ctx_creation` + :example: See :ref:`liboni_example_ctx_creation`. .. seealso:: :func:`oni_get_opt` - Inspect :type:`oni_ctx` state + Inspect :type:`oni_ctx` state. :func:`oni_set_opt` - Modify :type:`oni_ctx` state + Modify :type:`oni_ctx` state. .. function:: int oni_init_ctx(oni_ctx ctx, int host_idx) @@ -214,20 +214,20 @@ needed during the development of user-facing software. following events occur: #. All required data streams are opened. - #. A hardware reset issued using :macro:`ONI_OPT_RESET` + #. A hardware reset issued using :macro:`ONI_OPT_RESET`. #. A device table is obtained from the hardware. #. The minimal :macro:`ONI_OPT_BLOCKREADSIZE` and :macro:`ONI_OPT_BLOCKWRITESIZE` values are calculated and stored. #. The context run state is moved from ``UNINITIALIZED`` to ``IDLE``. - :param ctx: The acquisition context to be initialized + :param ctx: The acquisition context to be initialized. :param host_idx: The index of the hardware we are going to manage using the initialized context and driver. A value of -1 will attempt to open the default host index and is useful if there is only a - single ONIX host managed by driver selected in :func:`oni_create_ctx` + single ONIX host managed by driver selected in :func:`oni_create_ctx`. :return: 0 on success otherwise see :ref:`onidef_error_codes`. - :example: See :ref:`liboni_example_ctx_creation` + :example: See :ref:`liboni_example_ctx_creation`. .. function:: int oni_destroy_ctx(oni_ctx ctx) @@ -240,7 +240,7 @@ needed during the development of user-facing software. :param ctx: The acquisition context to close. :return: 0 on success otherwise see :ref:`onidef_error_codes`. - :example: See :ref:`liboni_example_ctx_destruction` + :example: See :ref:`liboni_example_ctx_destruction`. .. function:: int oni_get_opt(oni_ctx ctx, int option, void *value, size_t *size) @@ -256,15 +256,15 @@ needed during the development of user-facing software. :ref:`onidef_context_options` for a description of each possible ``option``, including access constraints. - :param ctx: :type:`oni_ctx` context to read an option from + :param ctx: :type:`oni_ctx` context to read an option from. :param option: Selected option to read. See :ref:`onidef_context_options` for valid options. - :param value: buffer to store value of ``option`` after it is read + :param value: buffer to store value of ``option`` after it is read. :param size: Pointer to the size of ``value`` buffer (including terminating null character, if applicable) in bytes. :return: 0 on success otherwise see :ref:`onidef_error_codes`. :example: See :ref:`liboni_example_device_table` and - :ref:`liboni_example_set_buffers` + :ref:`liboni_example_set_buffers`. .. seealso:: :ref:`onidef_context_options` @@ -282,14 +282,14 @@ needed during the development of user-facing software. disobeyed, the function will error. See :ref:`onidef_context_options` for description of each possible ``option``, including access constraints. - :param ctx: :type:`oni_ctx` context to read an option from + :param ctx: :type:`oni_ctx` context to read an option from. :param option: Selected option to set. See :ref:`onidef_context_options` for valid options. - :param value: buffer containing data to be written to ``option`` + :param value: buffer containing data to be written to ``option``. :param size: Size of ``value`` buffer (including terminating null character, if applicable) in bytes. - :return: 0 on success otherwise see :ref:`onidef_error_codes` - :example: See :ref:`liboni_example_device_table` and :ref:`liboni_example_set_buffers` + :return: 0 on success otherwise see :ref:`onidef_error_codes`. + :example: See :ref:`liboni_example_device_table` and :ref:`liboni_example_set_buffers`. .. seealso:: :ref:`onidef_context_options` @@ -312,13 +312,13 @@ needed during the development of user-facing software. read- and write-access, and descriptions) are provided on the :ref:`ONI-device datasheet `. - :param ctx: :type:`oni_ctx` context that manages the requested device - :param dev_idx: fully-qualified device index within the device table - :param addr: Address of register to be read + :param ctx: :type:`oni_ctx` context that manages the requested device. + :param dev_idx: fully-qualified device index within the device table. + :param addr: Address of register to be read. :param value: Pointer to an unsigned integer that will store the value of the register at ``addr`` on ``dev_idx``. - :return: 0 on success otherwise see :ref:`onidef_error_codes` - :example: See :ref:`liboni_example_read_write_reg` + :return: 0 on success otherwise see :ref:`onidef_error_codes`. + :example: See :ref:`liboni_example_read_write_reg`. .. function:: int oni_write_reg(const oni_ctx ctx, oni_dev_idx_t dev_idx, oni_reg_addr_t addr, oni_reg_val_t value) @@ -329,32 +329,32 @@ needed during the development of user-facing software. write-access, acceptable values, and descriptions) are provided on the :ref:`ONI-device datasheet `. - :param ctx: :type:`oni_ctx` context that manages the requested device - :param dev_idx: fully-qualified device index within the device table - :param addr: Address of register to be read + :param ctx: :type:`oni_ctx` context that manages the requested device. + :param dev_idx: fully-qualified device index within the device table. + :param addr: Address of register to be read. :param value: Value to write to the register at ``addr`` on ``dev_idx``. - :return: 0 on success otherwise see :ref:`onidef_error_codes` - :example: See :ref:`liboni_example_read_write_reg` + :return: 0 on success otherwise see :ref:`onidef_error_codes`. + :example: See :ref:`liboni_example_read_write_reg`. .. function:: int oni_read_frame(const oni_ctx ctx, oni_frame_t **frame) Read high-bandwidth data from the data input channel. :func:`oni_read_frame` allocates host memory and populates it with a single :struct:`oni_frame_t` struct using the data input stream. This call will - block until either enough data available on the stream to construct an + block until enough data is available on the stream to construct an underlying block buffer (see :macro:`ONI_OPT_BLOCKREADSIZE` and :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 this call by passing the resulting frame pointer to - :func:`oni_destroy_frame` + :func:`oni_destroy_frame`. :param ctx: :type:`oni_ctx` context that manages the high-bandwidth input - channel that the frame will be read from - :param frame: NULL pointer to reference using internal memory - :return: 0 on success otherwise see :ref:`onidef_error_codes` - :example: See :ref:`liboni_example_read_frame` + channel that the frame will be read from. + :param frame: NULL pointer to reference using internal memory. + :return: 0 on success otherwise see :ref:`onidef_error_codes`. + :example: See :ref:`liboni_example_read_frame`. .. function:: int oni_create_frame(const oni_ctx ctx, oni_frame_t **frame, oni_dev_idx_t dev_idx, void* data, size_t data_sz) @@ -365,14 +365,14 @@ needed during the development of user-facing software. :func:`oni_destroy_frame` :param ctx: :type:`oni_ctx` context that manages the high-bandwidth output - channel that the frame will be written through - :param frame: NULL pointer to reference using internal memory + channel that the frame will be written through. + :param frame: NULL pointer to reference using internal memory. :param dev_idx: fully-qualified device index within the device table that the frame will be written to. :param data: Raw data block to be copied into the frame. :param data_sz: Size of ``data`` in byes. - :return: 0 on success otherwise see :ref:`onidef_error_codes` - :example: See :ref:`liboni_example_write_frame` + :return: 0 on success otherwise see :ref:`onidef_error_codes`. + :example: See :ref:`liboni_example_write_frame`. .. attention:: ``data_sz`` Must be @@ -388,14 +388,14 @@ needed during the development of user-facing software. :param ctx: :type:`oni_ctx` context that manages the high-bandwidth output channel that the frame will be written through - :param frame: Pointer to frame created duing a call to :func:`oni_create_frame` + :param frame: Pointer to frame created during a call to :func:`oni_create_frame` :return: 0 on success otherwise see :ref:`onidef_error_codes` :example: See :ref:`liboni_example_write_frame` .. tip:: Frames created by using :func:`oni_create_frame` can be written to a device multiple times by using them as input arguments to :func:`oni_write_frame` multiple times. This allows pre-allocation of - frame resources from improved latency and determinism in closed-loop + frame resources for improved latency and determinism in closed-loop applications. .. function:: void oni_destroy_frame(oni_frame_t *frame) @@ -412,7 +412,7 @@ needed during the development of user-facing software. number is for backwards compatible bug fixes. When this function returns, input pointers will reference the library's version. - :param major: major library version for incompatible API changes + :param major: major library version for incompatible API changes. :param minor: minor library version for backwards compatible changes. :param patch: patch number for backwards compatible bug fixes. @@ -423,12 +423,12 @@ needed during the development of user-facing software. version. :param ctx: :type:`oni_ctx` context of which the loaded driver translator information - will be reported - :return: A pointer to a constant structure containing the driver translator information + will be reported. + :return: A pointer to a constant structure containing the driver translator information. .. function:: const char *oni_error_str(int err) Convert a return code (see :ref:`onidef_error_codes`) into a human readable string. - :param err: The error code to convert + :param err: The error code to convert. diff --git a/source/api/liboni/onidefs.rst b/source/api/liboni/onidefs.rst index fadffcd..eed94ff 100644 --- a/source/api/liboni/onidefs.rst +++ b/source/api/liboni/onidefs.rst @@ -11,35 +11,35 @@ 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 + future API revisions to handle drivers with different channel bit widths. .. type:: uint32_t oni_size_t - Data sizes are 32-bit uints + Data sizes are 32-bit uints. .. type:: uint32_t oni_dev_id_t - Device IDs are 32-bit values + Device IDs are 32-bit values. .. type:: uint32_t oni_dev_idx_t - Device idx are 32-bit, byte.byte.btye.byte addresses + Device idx are 32-bit, byte.byte.byte.byte addresses. .. type:: uint32_t oni_reg_addr_t - Registers use a 32-bit address + Registers use a 32-bit address. .. type:: uint32_t oni_reg_val_t - Registers have 32-bit values + Registers have 32-bit values. .. type:: uint32_t oni_fifo_dat_t - FIFOs use 32-bit words + FIFOs use 32-bit words. .. type:: uint64_t oni_fifo_time_t - FIFO bound timers use 64-bit words + FIFO bound timers use 64-bit words. .. _onidef_context_options: @@ -85,7 +85,7 @@ corresponding context option type used during calls to these functions. not reset context options or the sample counter. All data not shifted out of hardware will be cleared. To obtain the very first samples produced by high-bandwidth devices, see :macro:`ONI_OPT_RESETACQCOUNTER` to see how to - start acqusition sychronously with a clock reset. + start acquisition synchronously with a clock reset. =================== ================================================== Option value type :type:`oni_reg_val_t` @@ -98,9 +98,9 @@ corresponding context option type used during calls to these functions. .. macro:: ONI_OPT_RESET (``3``) - Trigger global hardware reset. Any value great than 0 will trigger a + Trigger global hardware reset. Any value greater than 0 will trigger a hardware reset. In this case, acquisition is stopped and resets are issued - to all devices in the device table. Following a + to all devices in the device table. =================== ================================================== Option value type :type:`oni_reg_val_t` @@ -127,13 +127,13 @@ corresponding context option type used during calls to these functions. .. macro:: ONI_OPT_ACQCLKHZ (``5``) - Host system acqusition clock frequency in Hz, derived from + Host system acquisition clock frequency in Hz, derived from :macro:`ONI_OPT_SYSCLKHZ`. This describes the frequency of the clock used - to drive the acqusition counter which is used timestamp data frames. + to drive the acquisition counter which is used to timestamp data frames. =================== ================================================== Option value type :type:`oni_reg_val_t` - Option description Host acqusition clock frequency in Hz + Option description Host acquisition clock frequency in Hz Default value N/A Access Read Required run state IDLE or RUNNING @@ -142,9 +142,9 @@ corresponding context option type used during calls to these functions. .. macro:: ONI_OPT_RESETACQCOUNTER (``6``) - Trigger a reset of the acqusition clock counter. A value of 1 will trigger - an acqusition clock counter reset. A value of 2 or greater will trigger - synchronous acqusition clock counter reset and set :macro:`ONI_OPT_RUNNING` + Trigger a reset of the acquisition clock counter. A value of 1 will trigger + an acquisition clock counter reset. A value of 2 or greater will trigger + synchronous acquisition clock counter reset and set :macro:`ONI_OPT_RUNNING` to 1. =================== ================================================== @@ -158,8 +158,8 @@ corresponding context option type used during calls to these functions. .. macro:: ONI_OPT_HWADDRESS (``7``) - The address of the host hardware within the acqusition computer. - Determines the sychronization role of the hardware in multi-host + The address of the host hardware within the acquisition computer. + Determines the synchronization role of the hardware in multi-host systems. =================== ================================================== @@ -409,7 +409,7 @@ as the underlying hardware endpoint for functions such as :func:`oni_get_opt`, .. macro:: ONI_CONFIG_REG_ADDR ( ``1``) - Device register access: Target adress + Device register access: Target address .. macro:: ONI_CONFIG_REG_VALUE @@ -453,7 +453,7 @@ as the underlying hardware endpoint for functions such as :func:`oni_get_opt`, .. macro:: ONI_CONFIG_HWADDRESS ( ``10``) - The address of the host hardware within the acqusition computer. Accessed through :macro:`ONI_OPT_HWADDRESS` + The address of the host hardware within the acquisition computer. Accessed through :macro:`ONI_OPT_HWADDRESS` .. _oni_driver_info_t: diff --git a/source/api/liboni/onidriver.rst b/source/api/liboni/onidriver.rst index f28d4f9..8594739 100644 --- a/source/api/liboni/onidriver.rst +++ b/source/api/liboni/onidriver.rst @@ -12,7 +12,7 @@ Constants and Types .. enum:: oni_read_stream_t - Represent the available data streams from the device to the host + Represent the available data streams from the device to the host. .. macro:: ONI_READ_STREAM_DATA @@ -26,7 +26,7 @@ Constants and Types .. enum:: oni_write_stream_t - Represent the available data streams from the host to the device + Represent the available data streams from the host to the device. .. macro:: ONI_WRITE_STREAM_DATA @@ -46,7 +46,7 @@ Constants and Types Functions ------------------------ All driver translators must implement these functions. They are called -internally by the public interface decribed in :ref:`oni.h` and perform direct +internally by the public interface described in :ref:`oni.h` and perform direct hardware access as needed. .. alias:: oni_driver_create_ctx @@ -71,7 +71,7 @@ hardware access as needed. Destroys the driver translator context and frees its resources. - :param driver_ctx: Handle to the open context to destroy + :param driver_ctx: Handle to the open context to destroy. :return: 0 on success otherwise see :ref:`onidef_error_codes`. @@ -79,10 +79,10 @@ hardware access as needed. Initializes a driver translator context opening a specific hardware instance. - :param driver_ctx: Handle to the context to be initialized + :param driver_ctx: Handle to the context to be initialized. :param host_idx: Index of the hardware device to open. The enumeration depends - on the specific hardware. ``-1`` always means open the first available device + on the specific hardware. ``-1`` always means open the first available device. :return: 0 on success otherwise see :ref:`onidef_error_codes`. @@ -90,11 +90,11 @@ hardware access as needed. Performs a read operation over the specified input stream. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param stream: The input stream to perform the read operation on + :param stream: The input stream to perform the read operation on. - :param data: Pointer to the data buffer. It must be big enough to fit the requested amount of data + :param data: Pointer to the data buffer. It must be big enough to fit the requested amount of data. :param size: Size, in bytes, of the data to read. Must read this amount from the device. @@ -105,11 +105,11 @@ hardware access as needed. Performs a write operation over the specified output stream. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param stream: The output stream to perform the write operation on + :param stream: The output stream to perform the write operation on. - :param data: Pointer to the data buffer. It must contain the amount of data requested to write + :param data: Pointer to the data buffer. It must contain the amount of data requested to write. :param size: Size, in bytes, of the data to write. @@ -119,11 +119,11 @@ hardware access as needed. Performs a read operation from one of the hardware configuration registers described in the ONI specification. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param config: Register to read from + :param config: Register to read from. - :param value: Variable to store the register value after it is read + :param value: Variable to store the register value after it is read. :return: 0 on success otherwise see :ref:`onidef_error_codes`. @@ -131,11 +131,11 @@ hardware access as needed. Performs a write operation to one of the hardware configuration registers described in the ONI specification. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param config: Register to write to + :param config: Register to write to. - :param value: Value to be written + :param value: Value to be written. :return: 0 on success otherwise see :ref:`onidef_error_codes`. @@ -145,7 +145,7 @@ hardware access as needed. use this for any internal adjustment required. See :ref:`making_drivers` for examples. If this function is not used, it is safe to do nothing and return :macro:`ONI_ESUCCESS`. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. :param oni_option: Option set, as specified in the originating :func:`oni_set_opt` call. @@ -160,11 +160,11 @@ hardware access as needed. Sets an internal option specific to the driver translator. Called directly by :c:func:`oni_set_driver_opt`. If no such options exist in a specific driver this can be an empty function returning :macro:`ONI_EINVALOPT`. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param driver_option: Option index to set, specific to the device driver translator + :param driver_option: Option index to set, specific to the device driver translator. - :param value: buffer containing data to be written to ``driver_option`` + :param value: buffer containing data to be written to ``driver_option``. :param option_len: Size of ``value`` buffer (including terminating null character, if applicable) in bytes. @@ -176,11 +176,11 @@ hardware access as needed. Reads an internal option specific to the driver translator. Called directly by :c:func:`oni_get_driver_opt`. If no such options exist in a specific driver this can be an empty function returning :macro:`ONI_EINVALOPT`. - :param driver_ctx: Context handling the device driver translator state + :param driver_ctx: Context handling the device driver translator state. - :param driver_option: Option index to read, specific to the device driver translator + :param driver_option: Option index to read, specific to the device driver translator. - :param value: buffer to store value of ``driver_option`` after it is read + :param value: buffer to store value of ``driver_option`` after it is read. :param option_len: Pointer to the size of ``value`` buffer (including terminating null character, if applicable) in bytes. @@ -189,7 +189,7 @@ hardware access as needed. .. function:: const oni_driver_info_t *oni_driver_info() - Provides static information about the driver translator + Provides static information about the driver translator. - :return: A :ref:`oni_driver_info_t` structure containing information about the driver translator + :return: A :ref:`oni_driver_info_t` structure containing information about the driver translator. diff --git a/source/api/liboni/onix.rst b/source/api/liboni/onix.rst index 97aef61..208329a 100644 --- a/source/api/liboni/onix.rst +++ b/source/api/liboni/onix.rst @@ -55,7 +55,7 @@ ONI specification and are not required to use the API. .. macro:: ONIX_TS4231 (``6``) - Triad semiconductor TS421 optical to digital converter + Triad semiconductor TS4231 optical to digital converter .. macro:: ONIX_DINPUT32 @@ -130,7 +130,7 @@ ONI specification and are not required to use the API. .. macro:: ONIX_TS4231V2ARR (``21``) - Triad semiconductor TS421 optical to digital converter array targeting V2 base-stations + Triad semiconductor TS4231 optical to digital converter array targeting V2 base-stations .. macro:: ONIX_FMCANALOG1R3 @@ -150,7 +150,7 @@ ONI specification and are not required to use the API. .. macro:: ONIX_TS4231V1ARR (``25``) - Triad semiconductor TS421 optical to digital converter array targeting V1 base-stations + Triad semiconductor TS4231 optical to digital converter array targeting V1 base-stations .. macro:: ONIX_MAX10ADCCORE diff --git a/source/hw-spec/comm_channels.rst b/source/hw-spec/comm_channels.rst index e04fb26..4a737ce 100644 --- a/source/hw-spec/comm_channels.rst +++ b/source/hw-spec/comm_channels.rst @@ -12,13 +12,13 @@ the system: 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 + :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 + register access operation. (e.g., An access to an non-existent address or a non-allowed operation will return an error.) diff --git a/source/hw-spec/controller.rst b/source/hw-spec/controller.rst index a667855..6ae94e6 100644 --- a/source/hw-spec/controller.rst +++ b/source/hw-spec/controller.rst @@ -2,7 +2,7 @@ Controller ========== -The controller’s purpose is to interface an ONI hardware system with the host +The controller's purpose is to interface an ONI hardware system with the host computer. It aggregates and routes device data and provides transparent access to all devices, independently of their physical location. The host also contains a common clock that is used to timestamp data from all devices, @@ -29,7 +29,7 @@ is defined as a single register read or write cycle to an individual address. The required characteristics of these channels are described in the following sections. A complete understanding of their use during software development -requires an undersanding of the the :ref:`oni-api`. +requires an understanding of the :ref:`oni-api`. .. _data-rd-chan: @@ -115,7 +115,7 @@ Additionally, it is the channel over which the controller sends the device table to the host following a system reset. Signal data MUST be framed into packets using Consistent Overhead Byte Stuffing (`COBS `__). -Within this scheme, packets are delimited using 0’s and always have the +Within this scheme, packets are delimited using 0's and always have the following format: :: @@ -205,7 +205,7 @@ Address Name Type Device Register Programming Interface ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The device programming interface allows transparent access to each device’s +The device programming interface allows transparent access to each device's :ref:`register map `. It defines a general purpose bus that hides the specifics of any particular implementation. It is composed of the following configuration channel registers: @@ -220,7 +220,7 @@ configuration channel registers: - ``Register Value``: Value to be written to or read from and that corresponds to the register ``Register Address`` of device located at - ``Device Address``. + ``Device Address``. - ``Read/Write``: A flag indicating if a read or write should be performed. 0 indicates read operation. A value > 0 indicates write operation. @@ -238,7 +238,7 @@ configuration channel registers: Appropriate values of ``Register Address`` and ``Register Value`` are determined by: -- Looking at a device’s data sheet if the device is an integrated circuit and +- Looking at a device's data sheet if the device is an integrated circuit and using :ref:`raw registers `. - Examining the :ref:`ONI Device Datasheet ` for :ref:`managed registers `. @@ -255,7 +255,7 @@ must be performed: cannot be issued. 2. The target device is selected by writing its address, as featured on the - device map, into ``Device Address`` on the controller + device map, into ``Device Address`` on the controller. 3. The desired register address within the device register map is written into ``Register Address`` on the controller. 4. The ``Read/Write`` register on the controller is set to 0x00. @@ -276,7 +276,7 @@ must be performed: - Failed to read the register in which case the value of ``Register Value`` contains invalid data. -7. If operation was successful, the ``Register Value`` can be read +7. If operation was successful, the ``Register Value`` can be read. Register Write Sequence ^^^^^^^^^^^^^^^^^^^^^^^ @@ -306,8 +306,8 @@ sequence must be performed: 6. The signal stream must be pumped until either ``CONFIGWACK`` or ``CONFIGWNACK`` is received indicating that the controller has either: - - Successfully completed writing the specified device register - - Failed to write the register + - Successfully completed writing the specified device register. + - Failed to write the register. Following successful or unsuccessful device register read or write, the appropriate ACK or NACK packets *must* be passed to the :ref:`signal channel @@ -340,7 +340,7 @@ control over, the entire acquisition system: - ``Reset Acquisition Counter``: This register is used to reset the counter generating the ``Common_Timestamp`` used in the :ref:`device frames `. - A value if 1 will reset the counter to 0 without affecting the ``Running`` + A value of 1 will reset the counter to 0 without affecting the ``Running`` state. A value of 2 will reset the counter and, at the same time, set ``Running`` to 1, starting data production. diff --git a/source/hw-spec/dev_table.rst b/source/hw-spec/dev_table.rst index 5ae955f..3e53aee 100644 --- a/source/hw-spec/dev_table.rst +++ b/source/hw-spec/dev_table.rst @@ -3,7 +3,7 @@ Device Table ============ The collection of :ref:`devices ` governed by a :ref:`controller -` is referred as a device table. The :ref:`controller ` +` is referred to as a device table. The :ref:`controller ` is responsible for creating this aggregate and sending it to the computer following a reset. The table consists of an :ref:`addressed ` list of :ref:`device descriptors `. diff --git a/source/hw-spec/devices.rst b/source/hw-spec/devices.rst index 5a5bc9e..ea3bd18 100644 --- a/source/hw-spec/devices.rst +++ b/source/hw-spec/devices.rst @@ -3,10 +3,10 @@ Devices ======= Devices are the endpoint of most ONI transactions. They can represent a -physical element interfacing with the environment (e.g. an external sensor with +physical element interfacing with the environment (e.g., an external sensor with a digital communication interface), something programmed within the firmware to -emulate this (e.g. a digital logic module on an FPGA) or a purely internal data -source (e.g. a controller based digital logic module that generates system +emulate this (e.g., a digital logic module on an FPGA) or a purely internal data +source (e.g., a controller based digital logic module that generates system status reports). A device exposes the following :ref:`communication channels `: @@ -39,7 +39,7 @@ Device ID. Device IDs are 32-bit integers with the following format: implementations. Open Ephys is 0x00. - ``Device``: 16-bit Device ID. This number identifies not only the type of data produced or consumed by a device, but also a particular implementation. - For instance, the same sensor will have a unique Device IDs for each digital + For instance, the same sensor will have a unique Device ID for each digital module implementation that is used to communicate with it. This number can optionally be divided in two 8-bit values so long as the resulting 16-bit integer is unique within a particular “Company” (there is no need for unary @@ -63,15 +63,15 @@ table `. The descriptor must contain the following information: - ``Device_ID``: :ref:`As previously described. `. - ``Device_Version``: A version number to distinguish between implementations of a singular device type. Different versions that address minor issues MUST - NOT change the device’s sample data format or alter an existing register + NOT change the device's sample data format or alter an existing register map. However, register additions that do not affect the existing register map - are allowed. Any change that warrants a modification of a device’s streaming + are allowed. Any change that warrants a modification of a device's streaming data format, read size, write size, or existing register map MUST be implemented as a new :ref:`Device ID `. - ``Read_Sample_Size``: The length in bytes of a single :ref:`device sample ` produced by the device and sent to the :ref:`read stream `. -- ``Write_Sample_Size``: The length in bytes that of a single :ref:`device +- ``Write_Sample_Size``: The length in bytes of a single :ref:`device sample ` consumed by the device from the :ref:`write stream `. @@ -113,8 +113,8 @@ Register Type Device registers can be separated into two types: - **Raw registers**: Those that correspond 1:1 to the physical register space - of an external electrical component. (e.g.: The register map in the - manufacturer datasheet of a sensor IC) + of an external electrical component (e.g., the register map in the + manufacturer datasheet of a sensor IC). - **Managed registers**: Those designed to interface exclusively with an ONI system, usually implemented in firmware and described in a :ref:`ONI Device Datasheet `. @@ -136,7 +136,7 @@ power-on. Whenever a device receives a reset request generated by the controller, registers might either be reset to their power-on value or keep their current value. This can be defined independently for each register. -All register writes, regardless of reset behavior, MUST be immediate (i.e.: for +All register writes, regardless of reset behavior, MUST be immediate (i.e., for a Read-Write register, reading a register after being written must reflect the new value). However, the *effects* of a register might not occur until the next reset. An example of this type of behavior is registers that operate on the @@ -181,8 +181,8 @@ Preamble The following information is required in the preamble: 1. **Informal device name**: Name of the device. There are no textual - requirements for this field. (e.g. ChipXYX, Chip XYX, and My~Chip-12ab!, are - all valid) + requirements for this field. (e.g., ChipXYX, Chip XYX, and My~Chip-12ab!, are + all valid). 2. **Author(s)**: Device firmware or chip creator(s). Can be a person/people or a company, group, or organization. 3. **Device Version**: The :ref:`device version ` that this datasheet @@ -202,21 +202,21 @@ Register Map Raw Registers ^^^^^^^^^^^^^^^^^^^ If the device uses :ref:`raw registers `, then a link to the -manufacturer’s datasheet is all that is required so long as it contains the +manufacturer's datasheet is all that is required so long as it contains the register documentation equivalent to that required by :ref:`managed registers `. However, the register map can also be reproduced for -clarity or if the manufacturer’s datasheet is missing required information. +clarity or if the manufacturer's datasheet is missing required information. Managed Registers ^^^^^^^^^^^^^^^^^ If the device uses :ref:`managed registers `, a table that describes the managed register map is required. There are no formatting requirements for this -table, but it MUST contain the following columns +table, but it MUST contain the following columns: - **Address**: Register address within the :ref:`register map `. - **Name**: Human readable name for the register. Only capital ASCII letters and underscores are allowed, with no spaces or special characters (e.g. - ``VALID`` and ``ALSO_VALID`` vs. ``NotValid`` and ``ALSO-NOT-VALID``). + ``VALID`` and ``ALSO_VALID`` vs. ``NotValid`` and ``ALSO-NOT-VALID``). - **Access**: Read-only, write-only, or read-write. - **Time of Effect**: When does a register write affect hardware state? Immediately or following reset? @@ -224,7 +224,7 @@ table, but it MUST contain the following columns - **Reset Action**: Upon a reset, what happens to the register? Does it maintain its previous state or get reset to some value? If the latter, then what value? -- **Description**: Word description of the register’s function +- **Description**: Word description of the register's function. Additional columns are permitted so long as their information does not conflict with that in the required columns. diff --git a/source/hw-spec/glossary.rst b/source/hw-spec/glossary.rst index e532ad0..1f4fedc 100644 --- a/source/hw-spec/glossary.rst +++ b/source/hw-spec/glossary.rst @@ -24,7 +24,7 @@ elements and/or its context within the specification. API ONI application programming interface that can be used to develop software - to aquire from and control ONI-compliant hardware. + to acquire from and control ONI-compliant hardware. .. seealso:: :ref:`oni-api` @@ -34,7 +34,7 @@ elements and/or its context within the specification. ONI-compliant :term:`API`. Multiple :term:`controllers ` can coexist in a single :term:`Host Computer` and need not use the same :term:`Driver Translator`. Controllers communicate via :term:`API` calls - that manipulate an :term:`Acquisition Context` and a :term:`Device Table` , + that manipulate an :term:`Acquisition Context` and a :term:`Device Table`, which affect controller state using the driver translator. :term:`Hubs ` are connected to the controller where data to/from their devices is packed and transmitted to/from the host computer. The controller contains a @@ -45,7 +45,7 @@ elements and/or its context within the specification. Device A configurable piece of hardware with its own register address space - (e.g. an integrated circuit) or a digital “core” that emulates this. + (e.g., an integrated circuit) or a digital “core” that emulates this. Devices may or may not produce and/or accept :term:`streaming data ` , but that must at least implement a minimal :term:`register programming channel `. They must be documented, using a @@ -72,8 +72,8 @@ elements and/or its context within the specification. A collection of :term:`device addresses ` and corresponding metadata for all :ref:`devices ` governed by a :term:`controller `. The device table contains all meta-information required to - for proper interaction with each device. E.g. packet read-size, packet - write-size, burst read cycles, etc. + for proper interaction with each device (e.g., packet read-size, packet + write-size, burst read cycles, etc.). .. seealso:: :ref:`Device Table Specification ` @@ -91,7 +91,7 @@ elements and/or its context within the specification. :term:`API`. Host Interconnect - A hardware abstraction layer consisting of a physical bus (e.g. PCIe, USB, + A hardware abstraction layer consisting of a physical bus (e.g., PCIe, USB, or Ethernet) along with a :term:`Driver Translator` that the :term:`Controller` uses to communicate with the :term:`Host Computer`. @@ -111,6 +111,6 @@ elements and/or its context within the specification. Port A `physical bus `__ between a :term:`Hub` and a :term:`Controller`. This could be an external link to - a :term:`Hub` that is separated from the :term:`Controller` (e.g. a wire or + a :term:`Hub` that is separated from the :term:`Controller` (e.g., a wire or wireless communication channel) or it could be a bus inside of the :term:`Controller` in the case of a local hub. diff --git a/source/hw-spec/hubs.rst b/source/hw-spec/hubs.rst index 7cdc2a7..ab4b3b1 100644 --- a/source/hw-spec/hubs.rst +++ b/source/hw-spec/hubs.rst @@ -3,13 +3,13 @@ Hubs ==== Hubs are collections of devices sharing a common clock. They can be independent -hardware aggregates connected to the controller (e.g. a headstage for neural -acquisition) or a logical partition of existing hardware (e.g. a collection of +hardware aggregates connected to the controller (e.g., a headstage for neural +acquisition) or a logical partition of existing hardware (e.g., a collection of devices implemented in the same firmware as the controller). Hubs that exist on hardware that is physically separated from the :ref:`controller ` are -referred as remote hubs, while hubs existing on the controller are local hubs. +referred to as remote hubs, while hubs existing on the controller are local hubs. An ONI-compliant system MUST implement at least one local hub, located at -:ref:`Hub_Index 0 ` and sharing the clock of controller’s main +:ref:`Hub_Index 0 ` and sharing the clock of controller's main state machine, and can implement up to 253 additional hubs, local or remote. All devices reflecting or modifying the :ref:`controller ` state and/or reporting errors or similar status messages must be implemented in local hub 0. @@ -20,9 +20,9 @@ to generate a ``Hub_Timestamp`` for a :ref:`data sample `. Data from all the devices of a hub is collected and passed to the controller. The specific interface between a hub and the controller is highly implementation-dependent and, thus, not in the scope of this document. In -any case, it is the duty of the hub to to provide the controller with all the +any case, it is the duty of the hub to provide the controller with all the device descriptors and communication channels in a transparent manner. It is -common for a remote hub to feature a centralized IC (e.g. an FPGA or +common for a remote hub to feature a centralized IC (e.g., an FPGA or microcontroller) integrating the device controllers and communication interface to fill this duty, but other schemes are possible. @@ -45,7 +45,7 @@ Information Device Every hub in an ONI system must feature a special device, located at :ref:`Device_Address ` 0xFE, which supplies information about the hub. Because this device is required to exist at a fixed address, it is not listed -to the device table and, thus, has no :ref:`device descriptor `. The only +in the device table and, thus, has no :ref:`device descriptor `. The only communication channel it must expose is the register interface, and it must not include any streams. The required register map is: @@ -77,7 +77,7 @@ the complete width. The detailed meaning of each register is: value, and thus be included in the automatic listings of existing ONI API implementations. Open Ephys is 0x00. - ``Hub``: 16-bit Hub ID. This number usually identifies a physical product - and would correpond to a stock keeping unit SKU) or part number in a + and would correspond to a stock keeping unit SKU or part number in a commercial setting. However, there is no formal restriction on these bits other than uniqueness. @@ -86,8 +86,8 @@ the complete width. The detailed meaning of each register is: require a new ID. These are typically related to a PCB revision. - **Firmware version**: A 16-bit value specifying firmware or gateware version - of the main component driving the hub (e.g.: An FPGA, microcontroller, or - EEPROM for logic-free hubs) + of the main component driving the hub (e.g., an FPGA, microcontroller, or + EEPROM for logic-free hubs). - **Safe firmware version**: (Optional) For hubs that allow online updates of the firmware, 16-bit version of the fallback safe image, if any. diff --git a/source/index.rst b/source/index.rst index 74aeac9..033ad0c 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,4 +1,4 @@ -.. title:: Home +W.. title:: Home .. toctree:: :hidden: @@ -11,7 +11,7 @@ ======================================== Open Neuro Interface ======================================== -ONI is a hardware specification and API that facilitiates the creation of +ONI is a hardware specification and API that facilitates the creation of tools for neural data acquisition. This standard allows the creation of neural recording devices that support **arbitrary mixtures of sensors, probes, and actuators**. The hope is that ONI will streamline the development of new @@ -19,29 +19,29 @@ hardware for neural data acquisition and guarantee interoperability between ONI-compliant hardware and software. We also hope that the use of common protocols will allow easy integration of disparate hardware to develop rich feedback control loops for neuroscience projects. If you are interested in -developing against this specification (e.g. for a miniscope, headstage, -position tracker, 2P microscope, etc) or improving it, we would love to `hear +developing against this specification (e.g., for a miniscope, headstage, +position tracker, 2P microscope, etc.) or improving it, we would love to `hear from you `__ and talk about the best way to proceed. Specification Goals =================== -- Potential for low latency round trip times with a computer in the loop +- Potential for low latency round trip times with a computer in the loop. - Potential for high-bandwidth, bidirectional communication (thousands of - neural data channels; multiple high-resolution cameras) + neural data channels, multiple high-resolution cameras). - Acquisition and control of arbitrary hardware components using a common - computer interface + computer interface. - Support generic mixes of data sources and sinks from multiple, - asynchronous pieces of hardware - - Generic, system-wide hardware configuration - - Generic, system-wide, bidirectional data streaming + asynchronous pieces of hardware. + - Generic, system-wide hardware configuration. + - Generic, system-wide, bidirectional data streaming. - Hardware synchronization of multiple systems on a single host computers or - across multiple host computers -- Cross platform + across multiple host computers. +- Cross platform. - Aimed at the creation of interoperable physical devices, gateware, firmware, - and APIs + and APIs. Contents --------