Operator RamLUT

Operator Library: Memory

This operator implements a large Look Up Table (LUT) based on the Frame Grabber RAM, usually DRAM. One VisualApplets resource of type RAM is required (see 'Allocation of Device Resources').

Operator RamLUT supports kernels on the output.

For information on the latency of the operator, see Table 42, 'Individual Latencies of the Operators in Library Memory'.

The typical application fields of this operator are color space classification problems. For example on a microEnable IV family board the operator allows a lookup table of 2^24 entries, i.e. a classification look up table can be defined containing a value for each of the colors in the RGB 24 color space. The operator facilitates the programming of the LUT content in two ways. For both ways, the LUT has to be programmed post to 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 will cause 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 this files for errors and reports an error if the file cannot 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

      The 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 previous 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 will be ignored. This is the fastest method of writing values into the LUT. The Example from above would look like that in binarymode:

    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 containing the initial values. Finally, writing value one to parameter LoadInitFile starts the reading of the file and if accepted writing of the values to the hardware. Writing 0 to parameter LoadInitFile will not cause the loading of the values. This can be useful if it is unwanted that the initial file is 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 will suffer 90% loss of the maximal performance, resulting in about 10% bandwidth usage. However, by combining several DRAM banks together it is possible to increase the throughput even for the worst case. Tie 2 or more RamLUT operators together and let each of them process a different lookup job. If successive input values to not change quickly, the performance of the operator is much higher. Check the respective RAM technology and dimensions of your frame grabber in the hardware user guides.

Bandwidth Optimization

The theoretical bandwidth [bits/second] going through an operator that uses the Frame Grabber RAM (DRAM) is calculated in accord with the following formula:

However, the actual bandwidth is always less than the theoretical bandwidth due to the DRAM efficiency.

The maximum bandwidth going through the operator is reached if the product of Bit Width and Parallelism is equal to the internal RAM Port Width x 2 (true for read-only parameters).

[Note] Platform-specific values

RAM Port Width and System Clock are platform-specific. See Appendix. Device Resources for detailed information on your individual platform.

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, Ram Data Width]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. Check Appendix. Device Resources for more information.

2

The allowed output bit width depends on the physical memory of the frame grabber. The Bit Width is limited to 64 Bit, even if Ram Data Width is bigger. Check Appendix. Device Resources for more information.

Parameters

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

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

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

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

InitFileLoadMode
Type static parameter
Default text_with_checks
Range {text_with_checks, text_raw, binary}

The parameter defines the file format and the mode of the file being load to the lookup table. See 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 parameters starts the loading the file specified by parameter InitFileName into the LUT. See descriptions above.

Examples of Use

The use of operator RamLUT is shown in the following examples: