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').
The operator RamLUT supports kernels on the output.
For information on the latency of the operator, see Table 43, 'Individual Latencies of the Operators in Library Memory'.
Typical use cases for 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 after the synthesis process at the time when the applet is used during runtime.
-
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.
-
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 in the 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. 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.
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]](../common/images/admon/note.png) |
Platform-specific values |
|---|---|
|
RAM Port Width and System Clock are platform-specific. See Appendix. Device Resources for detailed information on your individual platform. |
| Property | Value |
|---|---|
| Operator Type | M |
| Input Link | I, read address input |
| Output Link | O, image data output |
|
|
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. Check Appendix. Device Resources for more information. |
|
|
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. Check Appendix. Device Resources for more information. |
| 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. |
|
The use of operator RamLUT is shown in the following examples:
-
'2D Shading Correction / Flat Field Correction Using Operator RamLUT'
Examples - The example shows the implementation of a 2D shading correction. Correction values are stored in the operator RamLUT. The applet performs a high precision offset and gain correction.
-
'Functional Example for Specific Operators of Library Color, Base and Memory'
Examples - Demonstration of how to use the operator
Prev
