Operator Library: Memory
| Available for Hardware Platforms |
|---|
| imaFlex CXP-12 Penta |
| imaFlex CXP-12 Quad |
The operator allows you to upload image data from the host PC to the frame grabber RAM (DRAM). It provides continuous data output for an arbitrary number of regions of interest (ROI). An image file is used here as a universal data container. Therefore, uploaded images can contain any data such as coefficients. Each image is assigned to an output kernel. Additionally, the operator provides the same initialization interface as the RamLUT operator, where each memory address can be initialized manually, by text file or by binary file. All coefficient images are stored in the Frame Grabber RAM (DRAM). One VisualApplets resource of the type RAM is required. Check 'Allocation of Device Resources' for more information. For information on the latency of the operator, see Table 44, 'Individual Latencies of the Operators in Library Memory'. Multiple resources of the 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 CoefficientBufferMultiRoi supports kernels on the output. If the operator is initialized with image files, each image file is assigned to the corresponding output kernel. If the buffer is initialized manually, with a text file, or with a binary file, you have to make sure that the data is in order. The exact data formatting is described below.
The operator simplifies the programming of the buffer content in several ways. For each way, the buffer has to be programmed after the synthesis process at the time when the applet is used during runtime.
One possibility of programming the buffer is a register interface which offers the parameters InitAddress and InitData. First, set the address using the InitAddress parameter. Then, write the data into the InitData parameter.
Writing the data causes the operator to actually write to the buffer and replace the previous value. Writing to the last kernel element of the last parallel kernel causes the operator to actually write to the RAM and replace the previous value. The data at a RAM address has to be organized as follows (also see the animation above):
-
Each RAM address contains O.Parallelism * O.KernelColumns * O.KernelRows values.
-
As a result, InitData is an array of O.Parallelism * O.KernelColumns * O.KernelRows values.
-
First, all values of a kernel row have to be listed, i.e. iterated over each kernel column.
-
Then, the data iterates over all kernel rows.
-
Finally, the same is repeated for all parallel data kernels.
The second possibility of programming the buffer is using one or more files containing the content. The file access is faster than the register access, but requires some attention. The file can be in different formats. You must define the format with the InitFileMode parameter.
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 file needs to contain the exact number of kernel elements as values. If you use a parallelism greater than 1, the number of values must be parallelism * kernel elements.
The following figure demonstrates the file for a 4x3 kernel:
This mode is similar to the text_with_checks mode, but it has 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. Since each value is written in a separate line, the parallelism doesn't influence the data sequence in this file format. The example from above looks as follows in text_raw mode:
The binary mode assumes a binary file, where 8 bytes are used for each kernel entry. 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 RAM. Since all values are written consecutively, the parallelism doesn't influence the sequence of data values for this file format. The example from above looks as follows in the binary mode:
The image_file mode expects a list of image files in the InitFileName parameter that are separated by comma or semicolon. Each file is used to initialize one kernel value: the first init file is assigned to the first kernel value, the second file is assigned to the second kernel value and so on ...
Since this mode uses regular images, the parallelism is irrelevant for the
data format of the files. The init file can be of the image format
*.tif or *.bmp. The individual
image files don't have to be the same format and they also don't have to
contain the same number of pixels.
If the maximum number of bytes per image line reaches the borders of 32-bit integer values, the operator might fail to load the image. This can only occur, if the O.Max.Img.Width is close to its maximum width (2^RamAddressWidth) and the O.Parallelism is also greater than 1.
When an init file contains 2^RamAddressWidth * KernelSize * Parallelism values, then the memory gets overwritten completely, starting from address 0. In this case, the parameter InitAddress is not touched.
When an init file contains more data than can be written into the RAM, only part of the initialization file is used. The data at the beginning of the file is used until no more memory space is available.
When an init file contains less entries, then partial initialization is performed. In this case, initialization is starting from the address given by the InitAddress parameter. The parameter InitAddress is automatically incremented to the next position after the last written memory entry. This allows to monitor how many memory entries were written. When the file contains more than (2^RamAddressWidth - InitAddress) * KernelSize * Parallelism values, the initialization stops after writing the last entry of the memory and InitAddress is set to 0.
For the initialization modes specified above, the InitFilename parameter specifies the file that contains the initial values. Finally, writing the value 1 to the LoadInitFile parameter starts reading the file and, if accepted, writes the values to the hardware. Writing 0 to the LoadInitFile parameter doesn't cause loading the values. This can be useful, if you don't 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: activate in the dialog.
Once the operator's frame grabber RAM (DRAM) was initialized with image data, it reads out multiple regions of interest (ROI). With the following parameters you can define the ROIs:
-
Number of read ROIs: MaxNumRoI and NumRoI
-
The size and location of the ROIs: XOffset, XLength, YOffset, and YLength
The MaxNumRoI parameter specifies the maximum number of ROIs that can be read. Each ROI coordinate parameter field XLength, YLength, XOffset and YOffset has MaxNumRoI entries.
The parameter NumRoI specifies the actual number of ROIs the operator provides at the output. If NumRoI is set to dynamic, its value can't exceed the value of MaxNumRoI. If set to dynamic, NumRoI can be updated during image acquisition. While the acquisition is running, the operator cyclically reads the specified number of ROIs. The operator waits for the end of an ROI cycle until it changes to NumRoI.
All ROIs are read sequentially and are provided as individual images on the operator output: ROI 0, ROI 1, ROI 2,.. until ROI N-1. Where N is the current number of ROIs, that is read out, specified by the parameter NumRoI. The parameter fields XOffset, XLength, YOffset and YLength specify a set of ROIs. You can set these parameters to dynamic or static, which specifies whether you can adjust the parameter during runtime. The parameter type of all ROI parameters is adapted automatically, when the parameter type of one ROI parameter is set. Learn on how to configure field parameters in 'Parameter Editing'.
All possible rectangular regions are supported for ROI definitions as long as the maximum output frame dimensions are not exceeded, i.e. a single pixel, a single line, a single column, a rectangular region, or the complete frame can be defined as an ROI.
Different ROIs do not need to have the same size.
Each ROI can be defined individually.
ROIs can overlap and ROIs can repeat.
The X-coordinate parameters XOffset and XLength need to be in step size of the output parallelism.
You can define empty ROIs by setting XLength or YLength to zero. The operator then provides an empty image (or line with link type VALT_LINE1D) on its output. An empty image contains no pixels. An empty ROI with link type VALT_PIXEL0D results in no output at all.
If the operator is used with image protocol VALT_LINE1D or VALT_PIXEL0D, the ROIs are defined in relation to the initialization file(s), which is always regarded as two-dimensional image. The two-dimensional ROIs are read, but depending on the link type, the output is a sequence of ROI frames, lines or pixels.
With the link type VALT_LINE1D, the output is an infinite sequence of lines, where no separation between individually defined ROIs exists. Similarly, in link type VALT_PIXEL0D the operator provides an infinite sequence of pixels, where no separation between individual ROIs or even ROI lines exists.
The operator provides ROI data at its output as soon as the acquisition starts and the operator's output is not blocked by a succeeding operator. For information about the latency of the operator, see Table 44, 'Individual Latencies of the Operators in Library Memory'.
You can update all ROIs dynamically, if the ROI parameter types are set to dynamic. However, the updated ROIs are only applied after the current "ROI cycle" is done and all NumRoI ROIs were read.
![[Note]](../common/images/admon/note.png) |
High Number of ROIs And Timing |
|---|---|
|
With an increasing number of maximum ROI definitions, defined by parameter MaxNumRoI, the operator's BRAM consumption increases. This may lead to timing problems at high clock rates. For example, a MaxNumRoI of 65536 may not meet the timing in a full design. |
The following restrictions apply to the CoefficientBufferMultiRoi operator:
-
If the DRAM is not fully initialized, there is no check whether the ROI coordinates actually contain image data. In this case, the operator reads random dummy values from the memory.
-
The maximum link properties differ depending on the usage of the operator. Refer to the section Supported Link Format below for more information.
-
A high MaxNumRoI (close to its maximum of 65536) might lead to timing issues.
-
An excessively wide image might not be loadable, when InitFileLoadMode is set to image_file mode.
For optimal performance, the used number of data bits should match as closely as possible the number provided in the module's parameter RamDataWidth. The maximum bandwidth going through the operator is reached, if the product of bit width, kernel size and parallelism is equal to the internal RAM port width RamDataWidth. Note that the internal bit width can be increased by the usage of kernels, but a full kernel will still be addressed as a single pixel.
|
|
The range of the input bit width is:
The input bit width must not exceed the native RAM data width RamDataWidth. |
|
|
The product of bit width, parallelism and kernel size must not exceed the native RAM data width: 
|
|
|
The maximum image dimensions must not exceed the available RAM: 
This results in the following condition for O.MaxImageWidth and O.MaxImageHeight: 
|
| RamDataWidth | |
|---|---|
| Type | static write parameter |
| Default | N/A |
| Range | Integer number |
|
This parameter provides the maximum data width that can be used in the RAM. This parameter depends on the used hardware platform. |
|
| RamAddressWidth | |
|---|---|
| Type | static write parameter |
| Default | N/A |
| Range | Integer number |
|
This parameter provides the number of address bits that can be used. The number of available RAM slots is defined by 2^RamAddressWidth. The current RamAddressWidth depends on the hardware platform as well as on the current number of memory operators (i.e. operators that use a RAM resource) in the design. |
|
| InitAddress | |
|---|---|
| Type | dynamic write parameter |
| Default | 0 |
| Range | [0, 2^RamAddressWidth-1] |
|
This parameter defines the address of the data defined by the parameter InitData. This parameter can also be used as an offset address, when initializing the RAM with an init file. See the descriptions above. |
|
| InitData | |
|---|---|
| Type | dynamic write parameter |
| Default | 0 |
| Range | [0, 2^O.BitWidth-1] |
|
This field parameter defines the data that is written to the address defined by the parameter InitAddress. InitData contains O.Parallelism * O.KernelColumns * O.KernelRows values. Writing the last field of the InitData array causes the actual writing into hardware. See detailed descriptions above. |
|
| InitFileLoadMode | |
|---|---|
| Type | dynamic write parameter |
| Default | image_file |
| Range | {text_with_checks, text_raw, binary, image_file} |
|
This parameter defines the file format and the mode of the file(s) that is loaded into the lookup table.
See detailed descriptions above. |
|
| InitFileName | |
|---|---|
| Type | dynamic write parameter |
| Default | InitCoefficientBuffer.tif |
| Range | |
|
This parameter defines the name of the initialization file(s). If InitFileLoadMode is set to image_file, this parameter contains a list of files instead of one single file name. In the files list each entry has to be separated by either comma or semicolon. The number of specified files in image_file mode must be the same as the number of available kernel values (O.KernelColumns * O.KernelRows), when loading the files with LoadInitFile. This parameter accepts file names with leading and trailing white spaces and leading and trailing “"” or “'” characters. |
|
| LoadInitFile | |
|---|---|
| Type | dynamic write parameter |
| Default | 0 |
| Range | [0, 1] |
|
To start loading the file(s) specified by the InitFileName parameter into the RAM, write the value 1 to this parameter. See detailed descriptions above. |
|
| MaxNumRoI | |
|---|---|
| Type | static write parameter |
| Default | 1 |
| Range | [1, 65536] |
|
This parameter defines the maximum number of ROIs the operator can store. If NumRoI is set to static, this parameter can not be edited. Instead it will automatically have the same value as NumRoI. A very high number for the maximum ROI count MaxNumRoI might lead to timing issues, when building the applet. |
|
| NumRoI | |
|---|---|
| Type | dynamic/static write parameter |
| Default | 1 |
| Range | [1, MaxNumRoI] |
|
This parameter defines the number of ROIs actually used. The operator reads NumRoI ROIs before starting over with reading the first ROI. While the acquisition is running, the operator cyclically outputs NumRoI ROIs, until the output is blocked by a succeeding operator. If the parameter is set to static, the range is [1, 65536] and MaxNumRoI is disabled. |
|
| XOffset | |
|---|---|
| Type | dynamic/static read/write parameter |
| Default | 0 |
| Range | [0, O.MaxImgWidth - XLength] |
|
This field parameter defines the array of x-coordinates of the ROI's most left column. The step size is the parallelism. Learn on how to configure field parameters in 'Parameter Editing'. |
|
| XLength | |
|---|---|
| Type | dynamic/static read/write parameter |
| Default | 1024 |
| Range | [0, O.MaxImgWidth - XOffset] |
|
This field parameter defines the array of ROI widths. The step size is the parallelism. Learn on how to configure field parameters in 'Parameter Editing'. |
|
| YOffset | |
|---|---|
| Type | dynamic/static read/write parameter |
| Default | 0 |
| Range | [0, O.MaxImgHeight - YLength] |
|
This field parameter defines the array of y-coordinates of the ROIs first row. Learn on how to configure field parameters in 'Parameter Editing'. |
|
| YLength | |
|---|---|
| Type | dynamic/static read/write parameter |
| Default | 1024 |
| Range | [0, O.MaxImgHeight - YOffset] |
|
This field parameter defines the array of ROI heights. Learn on how to configure field parameters in 'Parameter Editing'. |
|
| LinesToSimulate | |
|---|---|
| Type | static write parameter |
| Default | 1 |
| Range | {1, 2^31-1} |
|
This parameter is used during the design time for the simulation and only if O.LinkType is set to VALT_LINE1D. This parameter defines how many ROI lines should be simulated by the operator. The ROIs are defined as two-dimensional areas in the initialization image(s), but the simulation output provides a sequence of lines cyclically iterating over all specified ROIs (starting over at ROI 0 after reading NumRoI ROI's lines). |
|
| PixelsToSimulate | |
|---|---|
| Type | static write parameter |
| Default | 1 |
| Range | {1, 2^31-1} |
|
This parameter is used during the design time for the simulation and only if O.LinkType is set to VALT_PIXEL0D. This parameter defines how many ROI pixels should be simulated by the operator. The ROIs are defined as two-dimensional areas in the initialization image(s), but the simulation output will provide a sequence of pixels cyclically iterating over all specified ROIs starting over at ROI 0 after reading NumRoI ROI's pixels. |
|
Prev
