camj.digital package

camj.digital.compute module

Digital Compute Library

This module defines the digital compute interface. It contains three types of compute units which can be used in digital simulation.

class camj.digital.compute.ADC(name: str, output_pixels_per_cycle: tuple, location, energy_per_pixel=600)

Bases: object

ADC compute unit

ADC is special in digital domain because it serves as an interface between digital and analog domain. Here, to perform digital simulation, we assume the computation starts with ADC. Users need to define ADC to launch digital simulation.

Parameters:

  • name (str) – name of this class.

  • output_pixels_per_cycle (tuple) – the output pixel rate per cycle. It should be in (H, W, C) format.

  • location – defines the location of the ADC. see general.enum for more details.

  • energy_per_pixel – the energy consumption generated in digital domain per pixel.

compute_energy()

Total Compute Energy

This function calculates the total compute energy for this compute instance. CamJ simulator calls this function after the simulation is finished.

Mathematically Expression:

Total Compute Energy = Energy per Pixel * Output Pixels

Returns:

Compute energy number in pJ (int)

get_total_read()

Calculate number of reads before output the given number of pixels defined by users.

Returns:

Number of Reads (int)

get_total_write()

Calculate number of writes to output the given number of pixels defined by users.

Returns:

Number of Write (int)

set_input_buffer(input_buffer)

Set Input Buffer

This function sets the input buffer for this compute unit. Each compute can have one input buffer, call this function multiple times will overwrite the old input buffer.

Parameters:

input_buffer – input buffer object for this compute instance.

Returns:

None

set_output_buffer(output_buffer)

Set Output Buffer

This function sets the output buffer for this compute unit. Each compute can have one output buffer, call this function multiple times will overwrite the old output buffer.

Parameters:

output_buffer – output buffer object for this compute instance.

Returns:

None

class camj.digital.compute.ComputeUnit(name: str, location: int, input_pixels_per_cycle: list, output_pixels_per_cycle: list, energy_per_cycle: float, num_of_stages: int)

Bases: object

Generic Compute Unit Interface

This is the generic Compute Unit interface for digital domain. It can be used to model any digital compute hardware that performs stencil operations.

Parameters:

  • name (str) – name of this class.

  • location – defines the location of the ADC. see general.enum for more details.

  • output_pixels_per_cycle (tuple) – the input pixel rate per cycle in order to perform computation. It should be a list of tuple. Each tuple should be in (H, W, C) format.

  • output_pixels_per_cycle – the output pixel rate per cycle. It should be in (H, W, C) format.

  • energy_per_cycle (float) – the average energy per cycle in unit of pJ.

  • num_of_stages (int) – number of stage of this compute unit in the pipeline.

Examples

To instantiate a 3x3x1 convolution operation with 3-stage pipeline. Each cycle, this compute unit takes 1x3x1 inputs and output 1x1x1. When fully pipelined, this compute unit consumes 9 pJ (9 operations, each takes 1 pJ).

>>> ComputeUnit(
    name = "ConvUnit",
    location = ProcessorLocation.COMPUTE_LAYER,
    input_pixels_per_cycle = [(1, 3, 1)],
    output_pixels_per_cycle = (1, 1, 1),
    energy_per_cycle = 9,   # pJ
    num_of_stages = 3,      # 3-stage pipeline
)
compute_energy()

Total Compute Energy

This function calculates the total compute energy for this compute instance. CamJ simulator calls this function after the simulation is finished.

Mathematically Expression:

Total Compute Energy = Energy per cycle * Compute Cycles

Returns:

Compute energy number in pJ (int)

get_total_read()

Calculate number of reads before output the given number of pixels defined by users.

Returns:

Number of Reads (int)

get_total_write()

Calculate number of writes to output the given number of pixels defined by users.

Returns:

Number of Write (int)

set_input_buffer(input_buffer)

Set Input Buffer

This function sets the input buffer for this compute unit. Each compute can have one input buffer, call this function multiple times will overwrite the old input buffer.

Parameters:

input_buffer – input buffer object for this compute instance.

Returns:

None

set_output_buffer(output_buffer)

Set Output Buffer

This function sets the output buffer for this compute unit. Each compute can have one output buffer, call this function multiple times will overwrite the old output buffer.

Parameters:

output_buffer – output buffer object for this compute instance.

Returns:

None

class camj.digital.compute.SystolicArray(name, location, size_dimension, energy_per_cycle)

Bases: object

This class emulate a classic architecture design, systolic array.

Parameters:

  • name (str) – name of this class.

  • location – defines the location of the ADC. see general.enum.ProcessorLocation for more details.

  • size_dimension (tuple) – the dimension of the systolic array in a format of (H, W).

  • energy_per_cycle (float) – the average energy per cycle in unit of pJ.

Example

To instantiate a 16x16 systolic array

>>> SystolicArray(
    name = "SystolicArray",
    location = ProcessorLocation.COMPUTE_LAYER,
    size_dimension = (16, 16),
    energy_per_cycle = 0.5 * 16 *16, # 0.5 pJ per MAC op
)
compute_energy()

Total Compute Energy

This function calculates the total compute energy for this compute instance. CamJ simulator calls this function after the simulation is finished.

Mathematically Expression:

Total Compute Energy = Energy per cycle * Compute Cycles

Returns:

Compute energy number in pJ (int)

get_total_read()

Calculate number of reads before output the given number of pixels defined by users.

Returns:

Number of Reads (int)

get_total_write()

Calculate number of writes to output the given number of pixels defined by users.

Returns:

Number of Write (int)

set_input_buffer(input_buffer)

Set Input Buffer

This function sets the input buffer for this compute unit. Each compute can have one input buffer, call this function multiple times will overwrite the old input buffer.

Parameters:

input_buffer – input buffer object for this compute instance.

Returns:

None

set_output_buffer(output_buffer)

Set Output Buffer

This function sets the output buffer for this compute unit. Each compute can have one output buffer, call this function multiple times will overwrite the old output buffer.

Parameters:

output_buffer – output buffer object for this compute instance.

Returns:

None

camj.digital.memory module

class camj.digital.memory.DigitalStorage(name: str, access_units: list, location=ProcessorLocation.INVALID)

Bases: object

Base class for digital storage class

This is the base class for digital storage memory.

IMPORTANT: Don’t use this class directly, use the derived class instead!

A very important attribute in DigitalStorage class is reserved_buffer. Reserved_buffer is used to find the consumer-producer connections between two hardware compute units. It is important to find whether the data dependency is ready or not.

class camj.digital.memory.DoubleBuffer(name: str, size: tuple, write_energy_per_word: int, read_energy_per_word: int, pixels_per_write_word: int, pixels_per_read_word: int, location: int)

Bases: DigitalStorage

This class emulates the hardware behavior of double buffer.

Parameters:

  • name (str) – name of this memory structure.

  • size (tuple) – the size of double buffer in a shape of (A, B, C). A is number of SRAM, B is the number of bank, C is the size of each bank.

  • location – the location of this memory unit.

  • write_energy_per_word (float) – energy cost for each write

  • read_energy_per_word (float) – energy cost for each read

  • pixels_per_write_word (int) – the length of each write. Unit in pixel

  • pixels_per_read_word (int) – the length of one read. Unit is pixel

total_memory_access_energy()

Calculate the total memory access energy

Returns:

the memory access energy in unit of pJ.

Return type:

Memory Access Energy (flaot)

class camj.digital.memory.FIFO(name: str, size: int, location: int, write_energy_per_word: int, read_energy_per_word: int, pixels_per_write_word: int, pixels_per_read_word: int)

Bases: DigitalStorage

FIFO Buffer

This class emulates the hardware behavior of FIFO. Each FIFO will have one read port and one write port.

Parameters:

  • name (str) – name of this memory structure.

  • size (tuple) – the size of FIFO in unit of pixel.

  • location – the location of this memory unit.

  • write_energy_per_word (float) – energy cost for each write

  • read_energy_per_word (float) – energy cost for each read

  • pixels_per_write_word (int) – the length of each write. Unit in pixel

  • pixels_per_read_word (int) – the length of one read. Unit is pixel

total_memory_access_energy()

Calculate the total memory access energy

Returns:

the memory access energy in unit of pJ.

Return type:

Memory Access Energy (flaot)

class camj.digital.memory.LineBuffer(name: str, size: tuple, location: int, write_energy_per_word: int, read_energy_per_word: int, pixels_per_write_word: int, pixels_per_read_word: int)

Bases: DigitalStorage

Line Buffer, extended from DigitalStorage base class

This class follows a specific memory access pattern. The size of this class defines the number of read and write per cycle. For instance, a size of (3, 128) line buffer can be read 3 pixels per cycle and can be written 1 pixel per cycle.

However, this class doesn’t check if per-cycle read and write surpass its capacity. This class does check if the number of read and write requests by consumer/producer can be fulfilled or not.

Parameters:

  • name (str) – name of this memory structure.

  • size (tuple) – the size of the line buffer in a shape of (A, B). A is the number of rows in this line buffer, B is the size of each row in unit of pixel.

  • location – the location of this memory unit.

  • write_energy_per_word (float) – energy cost for each write

  • read_energy_per_word (float) – energy cost for each read

  • pixels_per_write_word (int) – the length of each write. Unit in pixel

  • pixels_per_read_word (int) – the length of one read. Unit is pixel

total_memory_access_energy()

Calculate the total memory access energy

Returns:

the memory access energy in unit of pJ.

Return type:

Memory Access Energy (flaot)