Operator RamLUT

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 in 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 entries 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 entry 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 entry must be 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 like that 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 is smaller 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 like that in binary mode:

    In all three modes the number of entries in the files has to match with the number of LUT elements. Thus, the files must contain 2^InputBitWidth entries. A partial initialization is not possible.

    Parameter InitFilename specifies the file that contains the initial values. Finally, writing value one for 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.

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.

I/O Properties

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

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 access to the RAM. Parameter RamAddressWidth provides the maximum address bits which 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 static 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 read/write parameter
Default InitRamLut.txt
Range

This parameter defines the name of the initialization file.

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

Writing value one to this parameter starts loading the file specified by the parameter InitFileName into the LUT. See the descriptions above.