Convolution 2D (zdnn_conv2d)

Description

Perform 2D convolution over an input tensor in zDNN transformed format, as follows:

The input tensor in convolved with the kernel tensor.
The bias tensor is added to the results.
If the activation function, act_func, is not CONV2D_ACT_NONE, the activation function is applied to the results.
If act_func is set to CONV2D_ACT_RELU and clipping_value is not NULL or 0, clipping is performed against the intermediate result (z), where z = min(intermediate_result, clipping_value).
The result is stored into the provided output zDNN tensor.

Format

zdnn_status zdnn_fusedconv2d(const zdnn_ztensor *input,
                             const zdnn_ztensor *kernel,
                             const zdnn_ztensor *bias,
                             zdnn_pool_padding padding_type,
                             uint32_t stride_height, uint32_t stride_width,
                             zdnn_conv2d_act act_func, 
                             const void *clipping_value, zdnn_ztensor *output);

Parameters

zdnn_ztensor *input: An input tensor with original values to be downsampled in the output tensor. See Convolution 2D requirements for requirements. The tensor must satisfy the requirements in General zTensor requirements.
zdnn_ztensor *kernel: The kernel tensor to convolve with the input tensor. This must be a ZDNN_CNNK_HWCK tensor with a pre-transformed shape of [kernel_height, kernel_width, channels_in, channels_out]. See Convolution 2D requirements for additional requirements. The tensor must satisfy the requirements in General zTensor requirements.
zdnn_ztensor *bias: The bias tensor to add to the convolved results. This must be a ZDNN_1D tensor with a pre-transformed shape of [channels_out]. See Convolution 2D requirements for additional requirements. The tensor must satisfy the requirements in General zTensor requirements.
zdnn_pool_padding padding_type: The type of padding to use for the pooling operations. Valid values are SAME_PADDING or VALID_PADDING. For information about "same" and "valid" padding, see What is the difference between 'SAME' and 'VALID' padding in tf.nn.max_pool of tensorflow?.
uint32_t stride_height: Number of positions the kernel moves over the input's dim3 dimension at each step. See Convolution 2D requirements for requirements.
uint32_t stride_width: Number of positions the kernel moves over the input's dim2 dimension at each step. See Convolution 2D requirements for requirements.
zdnn_conv2d_act act_func: The activation function to apply to the results. Valid values are CONV2D_ACT_NONE or CONV2D_ACT_RELU.
void *clipping_value: A pointer to an FP32 value used to clip the elements of the input tensor. This value must not be negative. If this value is set to NULL or 0, no clipping occurs. This value is ignored if act_func is not set to CONV2D_ACT_RELU.
zdnn_ztensor *output: The output tensor that will hold the result of the operation. This must be a ZDNN_NHWC tensor with a pre-transformed shape of [num_batches, height_out, width_out, channels_out]. See Convolution 2D requirements for additional requirements. The tensor must satisfy the requirements in General zTensor requirements.

Convolution 2D requirements

Table 1 summarizes the requirements for the input, input_kernel, input_bias, and output tensors for convolution 2D operations based on the specified strides and padding.

Table 1. Summary of requirements for convolution 2D operations
Strides and padding	`input` (num_batches, height_in, width_in, channels_in)	`kernel` (kernel_height, kernel_width, channels_in, channels_out)	`bias` (channels_out)	`output` (num_batches, height_out, width_out, channels_out)
Strides > 0 and ≤ 13 and SAME padding	–	Both `kernel_height` and `kernel_width` must be ≤ 64.	–	`height_out` = ceil(`height_in` ÷ `stride_height`) `width_out` = ceil(`width_in` ÷ `stride_width`)
Strides > 0 and ≤ 13 and VALID padding	`height_in` must be ≥ `kernel_height`. `width_in` must be ≥ `kernel_width`.	Both `kernel_height` and `kernel_width` must be ≤ 64.	–	`height_out` = ceil((`height_in` − `kernel_height` + 1) ÷ `stride_height`) `width_out` = ceil((`width_in` − `kernel_width` + 1) ÷ `stride_width`)
Strides = 0 and VALID padding	`height_in` must be = `kernel_height`. width_in must be = kernel_width	Both `kernel_height` and `kernel_width` must be ≤ 448.	–	Both `height_out` and `width_out` must be 1.

Returns

One of the following zdnn_status indicators:

Status	Meaning
ZDNN_OK	Success.
ZDNN_INVALID_SHAPE	Shape of the input or output tensor is invalid based on the given kernel and stride parameters. Other general shape violations (such as, exceeds MDIS, and others).
ZDNN_INVALID_TYPE	See General failing statuses.
ZDNN_INVALID_FORMAT
ZDNN_INVALID_STRIDE_PADDING
ZDNN_INVALID_STRIDES
ZDNN_INVALID_CLIPPING_VALUE
Hardware statuses	See Hardware statuses.
ZDNN_FUNC_RC_F000	Invalid `padding_type` value.
ZDNN_FUNC_RC_F001	Invalid `act_func` value.
ZDNN_FUNC_RC_F002	`stride_height` = 0 and `stride_width` = 0, but either the `kernel_height` or `kernel_width` value is greater than 448.
ZDNN_FUNC_RC_F003	`stride_height` > 0 and `stride_width` > 0, but either the `kernel_height` or `kernel_width` value is greater than 64.
ZDNN_FUNC_RC_F004	Either the `stride_height` or `stride_width` value is greater than 13.

Since

1.0.0

Requirements

This function requires that:

The zdnn_is_nnpa_installed function returns true.
The underlying hardware supports zDNN APIs 1.0.x or later at run time.

See Validating the environment at run time.