fpga Command
============

The `fpga` command allows for various operations on the FPGA (Field Programmable Gate Array) device, such as booting, halting, enabling/disabling, and reading/writing specific registers. It provides a low-level interface for interacting with the FPGA hardware.

Usage
-----
The basic syntax for the `fpga` command is as follows:

.. code-block::

    fpga <operation> [options]

Arguments
----------

- operation: (Required) The specific operation to perform on the FPGA. This can be one of the following:
  - --boot: Boot the FPGA.
  - --halt: Halt the FPGA.
  - --disable-on: Disable the FPGA and turn it ON.
  - --disable-off: Disable the FPGA and turn it OFF.
  - write: Write a value to an FPGA register.
  - read: Read values from one or more FPGA registers.

Options
-------
The following options can be used with certain operations:

- `-a <address>`: Specify the register address (16-bit value) for read/write operations.
- `-v <value>`: Specify the value to write to the register (16-bit value).
- `-n <number>`: Specify the number of registers to read (only valid with the `read` operation).

Description
-----------
The `fpga` command interacts with the FPGA hardware to perform various tasks. The available operations include:

1. **Boot FPGA**: Boots the FPGA into its running state.
2. **Halt FPGA**: Halts the FPGA from its current operation.
3. **Disable FPGA**: Turns the FPGA OFF or ON based on the specified option.
4. **Register Write**: Writes a specified value to an FPGA register at a given address.
5. **Register Read**: Reads values from one or more FPGA registers.

Each operation may require additional parameters such as a register address and value, especially when interacting with the FPGA’s internal memory.

Examples
--------

1. **Boot the FPGA:**

   .. code-block::

       fpga --boot

   This will boot the FPGA.

2. **Halt the FPGA:**

   .. code-block::

       fpga --halt

   This will halt the FPGA.

3. **Disable FPGA to OFF state:**

   .. code-block::

       fpga --disable-off

   This will turn the FPGA OFF.

4. **Write to a register:**

   .. code-block::

       fpga write -a 0x1234 -v 0xABCD

   This will write the value `0xABCD` to the register at address `0x1234`.

5. **Read from a register:**

   .. code-block::

       fpga read -a 0x1234

   This will read the value from the register at address `0x1234` and display it.

6. **Read multiple registers:**

   .. code-block::

       fpga read -a 0x1234 -n 5

   This will read values from 5 consecutive registers starting at address `0x1234`.

Error Handling
--------------
If there is an error with the input or execution, the following error messages may be shown:

- **"invalid operation, please specify a valid operation"**: This error occurs if an invalid operation is specified.
- **"Error in parameters parsing"**: This error occurs if the parameters are not correctly parsed for the operation.
- **"Register address must be set with -a option (0xXXXX format)"**: This error occurs when a register address is not set for register-related operations.
- **"Register value must be set with -v option (0xXXXX format)"**: This error occurs when the register value is not set for write operations.
- **"Error accessing FPGA register memory"**: This error occurs when there is a failure in reading or writing to the FPGA register memory.

Notes
-----
- The `fpga` command provides a powerful interface for low-level FPGA control, making it essential for hardware debugging and management.
- All register addresses and values are expected to be in 16-bit format.
- When reading from registers, users can specify the number of registers to read, which defaults to 1 if not provided.