Metadata-Version: 2.1
Name: kratos
Version: 0.0.31
Summary: Kratos is a fast hardware design language embedded in Python
Home-page: https://github.com/Kuree/kratos
Author: Keyi Zhang
Author-email: keyi@stanford.edu
License: UNKNOWN
Description: Kratos
        ======
        
        |Build Status| |Appveyor Build status| |PyPI - Version|
        |Coverage| |Documentation Status|
        
        Kratos is a hardware design language written in C++/Python. It
        differentiates itself from other DSL with the following design
        philosophy:
        
        - Fully debuggable: debug hardware just like debugging Python code!
        - Highly efficient: Python frontend powered by
          Modern C++ binding. Designed with multi-processing in mind.
        - Human-readable verilog: we know how difficult it is to read machine
          generated verilog. kratos has multiple passes to produce nice-looking
          verilog.
        - Generator of generators: every python object is a generator
          that can be modified at any time, even after instantiation. This allows
          complex passes on the generators without ripping old structure apart.
        - Keep the good parts of SystemVerilog, such as ``always_ff``,
          ``always_comb``, ``interface``, and ``unique case``. Users control
          how and when to generate these semantics.
        - Single source of truth: kratos encourages users to infuse generator
          information inside generator itself. This makes debugging and
          verification much easier.
        - Static elaboration: kratos allows user to write parametrized code,
          even in the ``always`` block, all in Python.
        - Type checking: kratos check the variable types
          for each assignment to make sure there is no implicit conversion.
        
        Install
        -------
        
        ::
        
           pip install kratos
        
        Pre-built wheels support all Python 3.6+ on Linux, Windows, and
        OSX. To build it from scratch, you need a ``C++17`` compatible
        compiler, such as ``g++-8`` or ``clang-8``.
        
        Documentation and Examples
        --------------------------
        
        You can check the documentation at `Read the
        Docs <https://kratos-doc.readthedocs.io/en/latest/>`__.
        
        Here are some examples to showcase the ability of kratos.
        
        Asnyc Reset Register
        ~~~~~~~~~~~~~~~~~~~~
        
        Python code that parametrizes based on the ``width``. Notice that we
        specify the sensitivity of the ``always_ff`` block when defining
        ``seq_code_block``.
        
        .. code:: python
        
           class AsyncReg(Generator):
               def __init__(self, width):
                   super().__init__("register")
        
                   # define inputs and outputs
                   self._in = self.input("in", width)
                   self._out = self.output("out", width)
                   self._clk = self.clock("clk")
                   self._rst = self.reset("rst")
        
                   # add combination and sequential blocks
                   self.add_code(self.seq_code_block)
        
               @always_ff((posedge, "clk"), (posedge, "rst"))
               def seq_code_block(self):
                   if self._rst:
                       self._out = 0
                   else:
                       self._out = self._in
        
        Here is the generated SystemVerilog
        
        .. code:: SystemVerilog
        
           module register (
             input logic clk,
             input logic [15:0] in,
             output logic [15:0] out,
             input logic rst
           );
        
        
           always_ff @(posedge clk, posedge rst) begin
             if (rst) begin
               out <= 16'h0;
             end
             else out <= in;
           end
           endmodule   // register
        
        
        Fanout module
        ~~~~~~~~~~~~~
        
        This is another example to showcase the kratos' ability to produce high-quality
        SystemVerilog. In practice we would not write it this way.
        
        .. code:: python
        
           class PassThrough(Generator):
               def __init__(self, num_loop):
                   super().__init__("PassThrough")
                   self.in_ = self.input("in", 1)
                   self.out_ = self.output("out", num_loop)
                   self.num_loop = num_loop
        
                   self.add_code(self.code)
        
               @always_comb
               def code(self):
                   if self.in_:
                       for i in range(self.num_loop):
                           self.out_[i] = 1
                   else:
                       for i in range(self.num_loop):
                           self.out_[i] = 0
        
        Here is generated SystemVerilog. Notice that the iteration variable ``i``
        has been properly checked and resized to avoid index out of range.
        
        .. code:: SystemVerilog
        
          module PassThrough (
            input logic in,
            output logic [3:0] out
          );
        
          always_comb begin
            if (in) begin
              for (int unsigned i = 0; i < 4; i += 1) begin
                  out[2'(i)] = 1'h1;
                end
            end
            else begin
              for (int unsigned i = 0; i < 4; i += 1) begin
                  out[2'(i)] = 1'h0;
                end
            end
          end
          endmodule   // PassThrough
        
        
        How to debug
        ------------
        
        Because Python is quite slow, By default the debug option is off. You
        can turn on debugging for individual modules. See
        ``tests/test_generator.py`` for more details).
        
        
        Use an IDE Debugger
        -------------------
        
        .. image:: https://cdn.jsdelivr.net/gh/Kuree/kratos-vscode@master/images/demo.gif
             :alt: demo
        
        Check out the kratos ecosystem below to see how to use an IDE to debug kratos design
        with ncsim/VCS!
        
        
        Ecosystem
        ---------
        
        Kratos has its own ecosystem to program behavioral verilog in Python. Most of them
        are plugins that will help users to debug, prototype, and testing.
        
        `kratos <https://github.com/Kuree/kratos>`__ is a programming model for
        building hardware. The main abstraction in kratos in a ``Generator``.
        ``Generator`` can be modified at any time through passes.
        
        `kratos-debug <https://github.com/Kuree/kratos-debug>`__ is a GUI for user to
        view generated verilog. It offers a source viewer to see the line mapping that
        kratos provides.
        
        `kratos-dpi <https://github.com/Kuree/kratos-dpi>`__ is a DPI plugin that
        allows users to run arbitrary Python code to emulate a SystemVerilog function.
        This is extremely helpful for rapid prototyping and testing.
        
        `kratos-runtime <https://github.com/Kuree/kratos-runtime>`__ is a necessary
        component if you want to debug kratos with standard simulators. It supports
        value inspection and breakpoints.
        
        `kratos-vscode <https://github.com/Kuree/kratos-vscode>`__ is a Visual Studio
        Code extension that allows user to debug with Kratos. The simulator has to be
        loaded with ``kratos-runtime``.
        
        .. |Build Status| image:: https://github.com/Kuree/kratos/workflows/Linux%20Wheel%20Test/badge.svg
           :target: https://github.com/Kuree/kratos/actions
        .. |Appveyor Build status| image:: https://ci.appveyor.com/api/projects/status/en1u36q9tdqbaoh9/branch/master?svg=true
           :target: https://ci.appveyor.com/project/Kuree/kratos/branch/master
        .. |PyPI - Version| image:: https://badge.fury.io/py/kratos.svg
           :target: https://pypi.org/project/kratos/
        .. |Coverage| image:: https://codecov.io/gh/Kuree/kratos/branch/master/graph/badge.svg
          :target: https://codecov.io/gh/Kuree/kratos
        .. |Documentation Status| image:: https://readthedocs.org/projects/kratos-doc/badge/?version=latest
           :target: https://kratos-doc.readthedocs.io/en/latest/?badge=latest
        
Platform: UNKNOWN
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
