Operator RamLUT (imaFlex)

Operator Library: Memory

This operator implements a large lookup table (LUT) based on the Frame Grabber RAM, usually DRAM. One VisualApplets resource of type RAM is required (see 'Allocation of Device Resources'). Multiple resources of type RAM use the same physical RAM with the shared memory concept. Documentation for how to use the shared memory is available in the Application Note: Shared Memory.

The operator RamLUT supports kernels on the output.

Typical use cases for this operator are color space classification problems.

The operator facilitates the programming of the LUT content in two ways. For both ways, the LUT has to be programmed after the synthesis process at the time when the applet is used during runtime.

  1. One possibility of programming the LUT is a register interface which offers address- value-parameters InitAddress and InitData. First, set the address using parameter InitAddress. Next, write the data into parameter InitData. Writing the data causes the operator to actually write to the LUT and replace the previous value. If you use kernels, writing to the last kernel element causes the operator to actually write to the LUT and replace the previous value.

  2. The second possibility of programming the LUT is the usage of a file containing the content. The file access is faster than the register access, but requires some attention. The file can be in different formats. The format has to be defined by parameter InitFileMode:

    • text_with_checks

      In this mode the init file has to be a text file where the value strings are separated by either blanks, tab stops, line feeds (LF), or carriage return line feeds (CRLF). The operator checks these files for errors and reports an error if the file can't be used.

      Each value represents a kernel element and needs to be a decimal number within the correct range.

      The following figure demonstrates the file for a 4x3 kernel:

    • text_raw

      This mode is similar to mode text_with_checks but comprises less checks for errors. In this mode each value must be provided in a separate line. Loading a file in this mode is faster compared to the text_with_checks mode. The example from above would look as follows in text_raw mode:

    • binary

      The binary mode assumes a binary file, where 8 bytes are used for each kernel entry of a LUT element. If the kernel entry values can be represented by less than 64 bit, the unused bits are ignored. This is the fastest method of writing values into the LUT. The example from above would look as follows in binary mode:

    In all three modes the number of entries in the files must not exceed the number of LUT elements and the number of values must be a multiple of KernelSize. Thus, the files must contain up to 2^InputBitWidth * KernelSize values.

    When an init file contains 2^InputBitWidth * KernelSize values, then the LUT memory gets overwritten completely, starting from address 0. In this case, the parameter InitAddress is not touched.

    When an init file contains less entries, then partial initialization is performed. Then, initialization is done starting from the address given by the InitAddress parameter. The parameter InitAddress is automatically incremented to the next position after the last written LUT entry. This allows to monitor how many LUT entries were written. When the file contains more than (2^InputBitWidth - InitAddress) * KernelSize values, then initialization will stop after writing the last entry of the LUT and InitAddress is set to 0.

    Parameter InitFilename specifies the file that contains the initial values. Finally, writing value 1 to parameter LoadInitFile starts reading the file and, if accepted, writing the values to the hardware. Writing 0 to parameter LoadInitFile doesn't cause the loading of the values. This can be useful if you do not want the initial file to be loaded to the hardware during the applet initialization process.

    During simulation, loading an init file is done the same way as during runtime. For partial configuration or in case of errors, it may be useful to check the output in the simulation log (you may need to activate Show Details in the Simulation dialog).

Note that the DRAM technology offers very poor performance for random access. In a worst case scenario when each consecutive access to the DRAM causes a page miss and requires a new row activation, the DRAM throughput suffers 90% loss of the maximal performance, resulting in about 10% bandwidth usage.

The input link can handle dynamic line widths, as well as empty lines and empty frames. Consequently, the output link can handle the same image dimensions.

Bandwidth Optimization

For optimal performance, the used number of data bits should match as closely as possible the number provided in the module parameter RamDataWidth. The maximum bandwidth going through the operator is reached if the product of bit width and kernel size is equal to the internal RAM port width RamDataWidth.

Available for Hardware Platform
imaFlex CXP-12 Penta
imaFlex CXP-12 Quad

I/O Properties

Property Value
Operator Type M
Input Link I, read address input
Output Link O, image data output

Supported Link Format

Link Parameter Input Link I Output Link O
Bit Width [1, RAM Address Width]1 [1, 64]2
Arithmetic unsigned as I
Parallelism 1 as I
Kernel Columns 1 [1, Ram Data Width / Bit Width]
Kernel Rows 1 [1, Ram Data Width / Bit Width / Kernel Columns]
Img Protocol {VALT_IMAGE2D, VALT_LINE1D, VALT_PIXEL0D} as I
Color Format VAF_GRAY as I
Color Flavor FL_NONE as I
Max. Img Width any as I
Max. Img Height any as I

1

The allowed input bit width depends on the physical memory of the frame grabber and on how many operators share the RAM. The RamAddressWidth parameter provides the maximum address bits that can be used. Note that this number may change depending on the number of RAM-based operators in the design.

2

The allowed output bit width depends on the physical memory of the frame grabber. The bit width is limited to 64 bit but several kernel components may be stored. The product of (bit width * kernel size) must not exceed the native RAM data width shown in parameter RamDataWidth.

Parameters

RamDataWidth
Type static write parameter
Default 0
Range Integer number

This parameter provides the number of data bits that can be used at the RAM interface. It's the maximum number of bits the output can provide (if kernels are used properly).

RamAddressWidth
Type static write parameter
Default 0
Range Integer number

This parameter provides the number of address bits that can be used.

InitAddress
Type dynamic write parameter
Default 0
Range [0, 2^InputBitWidth-1]

This parameter defines the address of the data defined by the parameter InitData. See the descriptions above.

InitData
Type dynamic write parameter
Default 0
Range [0, 2^OutputBitWidth-1]

This parameter defines the data that is written to the address defined by the parameter InitAddress. Writing to this parameter starts the actual writing into hardware. See the descriptions above.

InitFileLoadMode
Type dynamic write parameter
Default text_with_checks
Range {text_with_checks, text_raw, binary}

This parameter defines the file format and the mode of the file that is loaded into the lookup table. See the descriptions above.

InitFileName
Type dynamic write parameter
Default InitRamLut.txt
Range

This parameter defines the name of the initialization file.

LoadInitFile
Type dynamic write parameter
Default 0
Range [0, 1]

To start loading the file specified by the InitFileName parameter into the LUT, write the value 1 to this parameter. See the descriptions above.

  Prev     Level Up     Next  
Content Top Home