3. mcdnn_ops_train

此实体包含常用的训练函数算法，例如批量归一化，softmax，丢弃等。mcdnn_ops_train库依赖于mcdnn_ops_infer。

3.1. API参考

3.1.1. API函数

3.1.1.1. mcdnnActivationBackward()

此函数计算神经元激活函数的梯度。

mcdnnStatus_t mcdnnActivationBackward(
mcdnnHandle_t                   handle,
mcdnnActivationDescriptor_t     activationDesc,
const void                      *alpha,
const mcdnnTensorDescriptor_t   yDesc,
const void                      *y,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dy,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *x,
const void                      *beta,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx)

该函数支持就地操作，这意味着dy和dx指针可以相等。但是，这要求相应的张量描述符相同（特别是，输入和输出的步幅必须匹配才能支持就地操作）。所有张量格式都支持4维和5维。但是，当xDesc和yDesc的步幅相等且都为HW-packed时，可以获得最佳性能。对于超过5维的张量，必须压缩其空间维度。

参数

handle

输入。已创建的mcDNN上下文的句柄。更多信息，参见mcdnnHandle_t。

activationDesc

输入。激活描述符。更多信息，参见mcdnnActivationDescriptor_t。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将计算结果与输出层中的先验值混合，如下所示： dstValue = alpha[0]*result + beta[0]*priorDstValue。

yDesc

输入。已初始化的输入张量描述符的句柄。更多信息，参见mcdnnTensorDescriptor_t。

y

输入。数据指针，指向与张量描述符yDesc关联的GPU内存。

dyDesc

输入。已初始化的输入差分张量描述符的句柄。

dy

输入。数据指针，指向与张量描述符dyDesc关联的GPU内存。

xDesc

输入。已初始化的输出张量描述符的句柄。

x

输入。数据指针，指向与输出张量描述符xDesc关联的GPU内存。

dxDesc

输入。已初始化的输出差分张量描述符的句柄。

dx

输出。数据指针，指向与输出张量描述符dxDesc关联的GPU内存。

返回值

MCDNN_STATUS_SUCCESS

此函数启用成功。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• 输入差分张量和输出差分张量的nStride，cStride，hStride，wStride步幅不同，并使用就地操作。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。不受支持的配置示例如下：

• 输入张量和输出张量的n，c，h，w维度不同。

• 输入张量和输出张量的数据类型不同。

• 输入张量和输入差分张量的nStride、cStride、hStride和wStride步幅不同。

• 输出张量和输出差分张量的nStride、cStride、hStride和wStride步幅不同。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。

3.1.1.2. mcdnnBatchNormalizationBackward()

该函数执行反向BN层计算。对于BN层，可参见Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift。

mcdnnStatus_t mcdnnBatchNormalizationBackward(
mcdnnHandle_t                   handle,
mcdnnBatchNormMode_t            mode,
const void                      *alphaDataDiff,
const void                      *betaDataDiff,
const void                      *alphaParamDiff,
const void                      *betaParamDiff,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *x,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dy,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx,
const mcdnnTensorDescriptor_t   bnScaleBiasDiffDesc,
const void                      *bnScale,
void                            *resultBnScaleDiff,
void                            *resultBnBiasDiff,
double                          epsilon,
const void                      *savedMean,
const void                      *savedInvVariance)

Only 4D and 5D tensors are supported. 在训练，反向传播和推理过程中的epsilon值必须相同。当所有x、dy和dx都使用HW-packed张量时，可以获得更高的性能。 有关此函数中使用的参数的辅助张量描述符生成信息，请参见mcdnnDeriveBNTensorDescriptor()。

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

alphaDataDiff, betaDataDiff

输入。指向缩放系数（主机内存中）的指针，用于将dx梯度输出与目标张量中的先验值混合，如下所示： dstValue = alphaDataDiff[0]*resultValue + betaDataDiff[0]*priorDstValue。

alphaParamDiff, betaParamDiff

输入。指向缩放系数（主机内存中）的指针，用于将resultBnScaleDiff和resultBnBiasDiff梯度输出与目标张量中的先验值混合，如下所示： dstValue = alphaParamDiff[0]*resultValue + betaParamDiff[0]*priorDstValue。

xDesc, dxDesc, dyDesc

输入。已初始化的张量描述符的句柄。

x

输入。数据指针，指向与张量描述符xDesc关联的GPU内存，用于层的x数据。

dy

输入。数据指针，指向与张量描述符dyDesc关联的GPU内存，用于反向传播差分dy输入。

dx

输入/输出。数据指针，指向与张量描述符dxDesc关联的GPU内存，用于生成与x相关的差分输出。

bnScaleBiasDiffDesc

输入。以下五个张量的共享张量描述符：bnScale，resultBnScaleDiff，resultBnBiasDiff，savedMean和savedInvVariance。此张量描述符的维度取决于归一化模式。更多信息，参见mcdnnDeriveBNTensorDescriptor()。

备注

对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，必须为double。

bnScale

输入。设备内存中指向BN scale参数的指针。

备注

该层的计算不需要bnBias参数。

resultBnScaleDiff, resultBnBiasDiff

输出。指针，指向此函数计算得到的scale差分和bias差分，位于设备内存中。请注意，这些scale梯度和bias梯度是此BN操作特定的权重梯度，根据定义不会反向传播。

epsilon

输入。BN公式中使用的Epsilon值。其值应等于或大于mcdnn.h中为MCDNN_BN_MIN_EPSILON定义的值。在正向和反向函数中应使用相同的Epsilon值。

savedMean, savedInvVariance

输入。可选的cache参数，包含在正向传递过程中计算并保存的中间结果。为保证工作正常，在调用此反向函数之前，层的x和bnScale数据必须保持不变。

备注

这两个参数可以为NULL，但只能同时为NULL。建议使用此cache，因为内存开销相对较小。

支持的配置

此函数支持多种描述符的以下数据类型组合。

数据 类型 配置	xDesc	bnScale BiasMean VarDesc	alphaData Diff, beta DataDiff ,alphaPa ramDiff, betaParam Diff	dyDesc	dxDesc
PSEU DO_HALF_ CONFIG	MCDNN_ DATA_ HALF	MCDNN_ DATA_ FLOAT	MC DNN_DATA _FLOAT	MCDNN_ DATA_ HALF	MCDNN_ DATA_ HALF
FLOAT_ CONFIG	MCDNN_ DATA_ FLOAT	MCDNN_ DATA_ FLOAT	MCDNN_ DATA_ FLOAT	MCDNN_ DATA_ FLOAT	MCDNN_ DATA_ FLOAT
D OUBLE_ CONFIG	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alpha、beta、x、dy、dx、bnScale、resultBnScaleDiff和resultBnBiasDiff中任意指针为NULL。

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中bnScaleBiasDiffDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• savedMean和savedInvVariance指针中只有一个为NULL。

• epsilon值小于MCDNN_BN_MIN_EPSILON。

• 任意一对xDesc、dyDesc和dxDesc的维度或数据类型不匹配。

3.1.1.3. mcdnnBatchNormalizationBackwardEx()

此函数是mcdnnBatchNormalizationBackward()的扩展，用于使用快速NHWC半持久内核执行反向BN层计算。

mcdnnStatus_t mcdnnBatchNormalizationBackwardEx (
mcdnnHandle_t                       handle,
mcdnnBatchNormMode_t                mode,
mcdnnBatchNormOps_t                 bnOps,
const void                          *alphaDataDiff,
const void                          *betaDataDiff,
const void                          *alphaParamDiff,
const void                          *betaParamDiff,
const mcdnnTensorDescriptor_t       xDesc,
const void                          *xData,
const mcdnnTensorDescriptor_t       yDesc,
const void                          *yData,
const mcdnnTensorDescriptor_t       dyDesc,
const void                          *dyData,
const mcdnnTensorDescriptor_t       dzDesc,
void                                *dzData,
const mcdnnTensorDescriptor_t       dxDesc,
void                                *dxData,
const mcdnnTensorDescriptor_t       dBnScaleBiasDesc,
const void                          *bnScaleData,
const void                          *bnBiasData,
void                                *dBnScaleData,
void                                *dBnBiasData,
double                               epsilon,
const void                          *savedMean,
const void                          *savedInvVariance,
const mcdnnActivationDescriptor_t   activationDesc,
void                                *workspace,
size_t                              workSpaceSizeInBytes
void                                *reserveSpace
size_t                              reserveSpaceSizeInBytes);

如果workspace为NULL并且传入的workSpaceSizeInBytes为零，则该API的功能将与非扩展函数mcdnnBatchNormalizationBackward完全相同。 此workspace不需要清理。此外，workspace不必在正向和反向传递之间保持不变，因为它不用于传递任何信息。

此扩展函数可以接受指向GPU workspace的workspace指针，以及来自用户的workSpaceSizeInBytes（workspace大小）。

bnOps输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

仅支持4D和5D张量。在训练，反向传播和推理过程中的epsilon值必须相同。 张量布局为NCHW时，若x、dy和dx都使用HW-packed张量时，可以获得更高的性能。

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

bnOps

输入。操作模式。目前，仅在NHWC布局中支持MCDNN_BATCHNORM_OPS_BN_ACTIVATION和MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION。 更多信息，参见mcdnnBatchNormOps_t。此输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

alphaDataDiff, betaDataDiff

输入。指向缩放系数（主机内存中）的指针，用于将dx梯度输出与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

alphaParamDiff, betaParamDiff

输入。指向缩放系数（主机内存中）的指针，用于将dBnScaleData和dBnBiasData梯度输出与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, x, yDesc, yData, dyDesc, dyData

输入。用于层的x数据，反向传播梯度输入dy，原始正向输出y数据的张量描述符和指针，位于设备内存中。如果bnOps设置为MCDNN_BATCHNORM_OPS_BN，则不需要yDesc和yData，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dzDesc, dxDesc

输入。用于计算梯度输出dz和dx的张量描述符和指针，位于设备内存中。 当bnOps为MCDNN_BATCHNORM_OPS_BN或MCDNN_BATCHNORM_OPS_BN_ACTIVATION时，不需要dzDesc，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dzData, dxData

输出。用于计算梯度输出dz和dx的张量描述符和指针，位于设备内存中。 当bnOps为MCDNN_BATCHNORM_OPS_BN或MCDNN_BATCHNORM_OPS_BN_ACTIVATION时，不需要dzData，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dBnScaleBiasDesc

输入。以下6个张量的共享张量描述符：bnScaleData、bnBiasData、dBnScaleData、dBnBiasData、savedMean和savedInvVariance。更多信息，参见mcdnnDeriveBNTensorDescriptor()。 此张量描述符的维度取决于归一化模式。

备注

对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，必须为double。

bnScaleData

输入。设备内存中指向BN scale参数的指针。(在 Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift中，数量scale称为gamma)。

bnBiasData

输入。设备内存中指向BN bias参数的指针。(在 Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift中，bias称为beta)。 此参数仅在执行激活时使用。

dBnScaleData, dBnBiasData

输出。设备内存中分别指向bnScaleData和bnBiasData梯度的指针。

epsilon

输入。BN公式中使用的Epsilon值。其值应等于或大于mcdnn.h中为MCDNN_BN_MIN_EPSILON定义的值。在正向和反向函数中应使用相同的Epsilon值。

savedMean, savedInvVariance

输入。可选的cache参数，包含在正向传递过程中计算并保存的中间结果。为保证工作正常，在调用此反向函数之前，层的x和bnScaleData、bnBiasData数据必须保持不变。请注意这两个参数可以为NULL，但只能同时为NULL。建议使用此cache，因为内存开销相对较小。

activationDesc

输入。激活操作的描述符。

当bnOps输入设置为MCDNN_BATCHNORM_OPS_BN_ACTIVATION或MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

workspace

输入。指向GPU工作空间的指针。如果workspace为NULL并且传入的workSpaceSizeInBytes为零，则该API的功能将与非扩展函数mcdnnBatchNormalizationBackward()完全相同。

workSpaceSizeInBytes

输入。workspace的大小。它必须足够大，才能通过此函数触发快速NHWC半持久内核。

reserveSpace

输入。指针，指向用作reserveSpace的GPU工作空间。

reserveSpaceSizeInBytes

输入。reserveSpace的大小。它必须等于或大于mcdnnGetBatchNormalizationTrainingExReserveSpaceSize()所需的量。

mcdnnBatchNormalizationBackwardEx()支持的配置

数据类型配置	xDesc, yDesc	dBnSc aleBiasDesc	alp haDataDiff, betaDa taDiff,alph aParamDiff, be taParamDiff	dyDesc, dzDesc, dxDesc
PSEUDO_HA LF_CONFIG	MCDNN_ DATA_HALF	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_ DATA_HALF
FLO AT_CONFIG	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT
DOUB LE_CONFIG	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alphaDataDiff、betaDataDiff、alphaParamDiff、betaParamDiff、x、dy、dx、bnScale、resultBnScaleDiff和resultBnBiasDiff中任意指针为NULL。

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中dBnScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• savedMean和savedInvVariance指针中只有一个为NULL。

• epsilon值小于MCDNN_BN_MIN_EPSILON。

• 任意一对xDesc、dyDesc或dxDesc的维度或数据类型不匹配。

3.1.1.4. mcdnnBatchNormalizationForwardTraining

此函数在训练阶段执行正向BN层计算。对于BN层，可参见Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift。

mcdnnStatus_t mcdnnBatchNormalizationForwardTraining(
mcdnnHandle_t                   handle,
mcdnnBatchNormMode_t            mode,
const void                      *alpha,
const void                      *beta,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *x,
const mcdnnTensorDescriptor_t   yDesc,
void                            *y,
const mcdnnTensorDescriptor_t   bnScaleBiasMeanVarDesc,
const void                      *bnScale,
const void                      *bnBias,
double                          exponentialAverageFactor,
void                            *resultRunningMean,
void                            *resultRunningVariance,
double                          epsilon,
void                            *resultSaveMean,
void                            *resultSaveInvVariance)

仅支持4D和5D张量。

在训练，反向传播和推理过程中的epsilon值必须相同。 对于推理阶段，使用mcdnnBatchNormalizationForwardInference。

当x和y都使用HW-packed张量时，可以获得更高的性能。 有关此函数中使用的参数的辅助张量描述符生成信息，请参见mcdnnDeriveBNTensorDescriptor()。

参数

handle

已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将层输出值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, yDesc

设备内存中用于层的x和y数据的张量描述符和指针。更多信息，参见mcdnnTensorDescriptor_t。

x

输入。数据指针，指向与张量描述符xDesc关联的GPU内存，用于层的x输入数据。

y

输入。数据指针，指向与张量描述符yDesc关联的GPU内存，用于BN层的y输出。

bnScaleBiasMeanVarDesc

共享张量描述符，用于通过mcdnnDeriveBNTensorDescriptor()获取的辅助张量。此张量描述符的维度取决于归一化模式。

bnScale, bnBias

输入。设备内存中用于BN scale和bias参数的指针。 请注意，bnBias参数可以替换上一层的bias参数以提高效率。

exponentialAverageFactor

输入。移动平均（Moving Average，MA）计算中使用的系数如下：

runningMean = runningMean*(1-factor) + newMean*factor

在对函数的第N次调用中使用factor=1/(1+n)可进行累积移动平均（Cumulative Moving Average，CMA）计算，例如：

CMA[n] = (x[1]+…+x[n])/n

例如：

CMA[n+1] = (n*CMA[n]+x[n+1])/(n+1)

= ((n+1)*CMA[n]-CMA[n])/(n+1) + x[n+1]/(n+1)

= CMA[n]*(1-1/(n+1))+x[n+1]*1/(n+1)

= CMA[n]*(1-factor) + x(n+1)*factor

resultRunningMean, resultRunningVariance

输入/输出。移动均值（Running mean）和方差（Running variance）张量（与scale和bias张量具有相同的描述符）。这两个指针可以为NULL，但只能同时为NULL。 存储在resultRunningVariance中（或作为推理模式中的输入被传入）的值是样本方差，是方差[x]的移动平均值，其中方差是根据模式在batch或spatial+batch维度上进行计算的。 如果这些指针不为NULL，则张量应初始化为一些合理的值或0。

epsilon

输入。BN公式中使用的Epsilon值。其值应等于或大于mcdnn.h中为MCDNN_BN_MIN_EPSILON定义的值。在正向和反向函数中应使用相同的Epsilon值。

resultSaveMean, resultSaveInvVariance

输出。可选的cache参数，用于保存在正向传递过程中计算得到的中间结果。当用于mcdnnBatchNormalizationBackward()函数时，这些缓冲区可用来加速反向传递。 用户不能直接使用存储在resultSaveMean和resultSaveInvVariance缓冲区的中间结果。根据BN模式，存储在resultSaveInvVariance中的结果可能会有所不同。为保证cache正常工作，在调用反向函数之前，输入层数据必须保持不变。 请注意这两个参数可以为NULL，但只能同时为NULL。在这种情况下，将不会保存中间统计信息，并且mcdnnBatchNormalizationBackward()必须进行重新计算。建议使用此cache，由于这些张量的维数乘积远小于数据张量的维数乘积，因此内存开销相对较小。

支持的mcdnnBatchNormalizationForwardTraining()配置

数据类型 配置	xDesc	bnScaleBias MeanVarDesc	alpha, beta	yDesc
PSEUDO_HA LF_CONFIG	MCDNN_ DATA_HALF	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_ DATA_HALF
FLO AT_CONFIG	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT	MCDNN_D ATA_FLOAT
DOUB LE_CONFIG	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE	MCDNN_DA TA_DOUBLE
PS EUDO_BFLOAT 16_CONFIG	MCDNN_ DATA _BFLOAT16	MCDNN_ DATA _FLOAT	MCDNN_ DATA _FLOAT	MCDNN_ DATA _BFLOAT16

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alpha、beta、x、y、bnScale和bnBias中任一指针为NULL。

• xDesc或yDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中bnScaleBiasMeanVarDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• resultSaveMean和resultSaveInvVariance指针中只有一个为NULL。

• resultRunningMean和resultRunningInvVariance指针中只有一个为NULL。

• epsilon值小于MCDNN_BN_MIN_EPSILON。

• xDesc或yDesc的维度或数据类型不匹配。

3.1.1.5. mcdnnBatchNormalizationForwardTrainingEx()

该函数是mcdnnBatchNormalizationForwardTraining()的扩展，用于执行正向BN层计算。

mcdnnStatus_t mcdnnBatchNormalizationForwardTrainingEx(
mcdnnHandle_t                       handle,
mcdnnBatchNormMode_t                mode,
mcdnnBatchNormOps_t                 bnOps,
const void                          *alpha,
const void                          *beta,
const mcdnnTensorDescriptor_t       xDesc,
const void                          *xData,
const mcdnnTensorDescriptor_t       zDesc,
const void                          *zData,
const mcdnnTensorDescriptor_t       yDesc,
void                                *yData,
const mcdnnTensorDescriptor_t       bnScaleBiasMeanVarDesc,
const void                          *bnScaleData,
const void                          *bnBiasData,
double                              exponentialAverageFactor,
void                                *resultRunningMeanData,
void                                *resultRunningVarianceData,
double                              epsilon,
void                                *saveMean,
void                                *saveInvVariance,
const mcdnnActivationDescriptor_t   activationDesc,
void                                *workspace,
size_t                              workSpaceSizeInBytes
void                                *reserveSpace
size_t                              reserveSpaceSizeInBytes);

当满足以下条件时，此API将触发新的半持久NHWC内核：

• 所有张量，即x、y、dz、dy和dx，必须是NHWC完全压缩，并且类型必须是MCDNN_DATA_HALF。

• 输入参数模式必须设置为MCDNN_BATCHNORM_SPATIAL_PERSISTENT。

• workspace不是NULL。

• 之前，C张量维度应始终是4的倍数。只有当bnOps为MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，C张量维度应是4的倍数。

• WorkSpaceSizeInBytes等于或大于mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize()所需的量。

• ReserveSpaceSizeInBytes等于或大于mcdnnGetBatchNormalizationTrainingExReserveSpaceSize()所需的量。

• 必须保留使用mcdnnBatchNormalizationForwardTrainingEx()存储在reserveSpace中的内容。

如果workspace为NULL并且传入的workSpaceSizeInBytes为零，则该API的功能将与非扩展函数mcdnnBatchNormalizationForwardTraining()完全相同。 此workspace不需要清理。此外，workspace不必在正向和反向传递之间保持不变，因为它不用于传递任何信息。

此扩展函数可以接受指向GPU workspace的workspace指针，以及来自用户的workSpaceSizeInBytes（workspace大小）。

bnOps输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

仅支持4D和5D张量。在训练，反向传播和推理过程中的epsilon值必须相同。

张量布局为NCHW时，若x、dy和dx都使用HW-packed张量时，可以获得更高的性能。

参数

handle

已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

bnOps

输入。快速NHWC内核的操作模式。更多信息，参见mcdnnBatchNormOps_t。此输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将层输出值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, xData, zDesc, zData, yDesc, yData

设备内存中的张量描述符和指针，用于层的输入x和输出y，以及用于在激活之前对BN操作的结果进行残差相加的可选z张量输入。可选的zDes和zData描述符仅在bnOps为MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时使用，否则用户可以传入NULL。使用时，z的维度应与x和最终输出y的维度完全相同。更多信息，参见mcdnnTensorDescriptor_t。

bnScaleBiasMeanVarDesc

共享张量描述符，用于通过mcdnnDeriveBNTensorDescriptor()获取的辅助张量。此张量描述符的维度取决于归一化模式。

bnScaleData, bnBiasData

输入。设备内存中用于BN scale和bias参数的指针。 请注意，bnBiasData参数可以替换上一层的bias参数以提高效率。

exponentialAverageFactor

输入。移动平均（Moving Average，MA）计算中使用的系数如下：

runningMean = runningMean*(1-factor) + newMean*factor

在对函数的第N次调用中使用factor=1/(1+n)可进行累积移动平均（Cumulative Moving Average，CMA）计算，例如：

CMA[n] = (x[1]+…+x[n])/n

例如：

CMA[n+1] = (n*CMA[n]+x[n+1])/(n+1)

= ((n+1)*CMA[n]-CMA[n])/(n+1) + x[n+1]/(n+1)

= CMA[n]*(1-1/(n+1))+x[n+1]*1/(n+1)

= CMA[n]*(1-factor) + x(n+1)*factor

resultRunningMeanData, resultRunningVarianceData

输入/输出。指向移动均值和移动方差数据的指针。这两个指针可以为NULL，但只能同时为NULL。存储在resultRunningVarianceData中（或作为推理模式中的输入被传入）的值是样本方差，是方差[x]的移动平均值，其中方差是根据模式在batch或spatial+batch维度上进行计算的。如果这些指针不为NULL，则张量应初始化为一些合理的值或0。

epsilon

输入。BN公式中使用的Epsilon值。其值应等于或大于mcdnn.h中为MCDNN_BN_MIN_EPSILON定义的值。在正向和反向函数中应使用相同的Epsilon值。

saveMean, saveInvVariance

输出。可选的cache参数，包含在正向传递过程中计算并保存的中间结果。为保证工作正常，在调用此反向函数之前，层的x和bnScaleData、bnBiasData数据必须保持不变。 请注意这两个参数可以为NULL，但只能同时为NULL。建议使用此cache，因为内存开销相对较小。

activationDesc

输入。激活操作的张量描述符。

当bnOps输入设置为MCDNN_BATCHNORM_OPS_BN_ACTIVATION或MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

workspace, workSpaceSizeInBytes

输入。workspace是指向GPU工作空间的指针，workSpaceSizeInBytes是workspace的大小。当workspace不为NULL且workSpaceSizeInBytes足够大，张量布局为NHWC且数据类型配置受支持时，此函数将触发一个新的半持久NHWC内核以进行BN操作。此workspace不需要清理。此外，workspace不需要在正向和反向传递之间保持不变。

reserveSpace

输入。指针，指向用作reserveSpace的GPU工作空间。

reserveSpaceSizeInBytes

输入。reserveSpace的大小。必须等于或大于mcdnnGetBatchNormalizationTrainingExReserveSpaceSize()所需的量。

支持的mcdnnBatchNormalizationForwardTrainingEx()配置

数据类型 配置	xDesc	bnScale BiasMean VarDesc	alpha, beta	zDesc	yDesc
PSEUDO _HALF_ CONFIG	MCDNN_ DATA _HALF	MCDNN_ DATA _FLOAT	MCDNN_ DATA _FLOAT	MCDNN_ DATA _HALF	MCDNN_ DATA _HALF
FLOAT_ CONFIG	MCDNN_ DATA _FLOAT	MCDNN_ DATA _FLOAT	MCDNN_ DATA _FLOAT	不支持	MCDNN_ DATA _FLOAT
DOUBLE_ CONFIG	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE	MCDNN_ DATA_ DOUBLE	不支持	MCDNN_ DATA_ DOUBLE

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alpha、beta、x、y、bnScaleData和bnBiasData中任一指针为NULL。

• xDesc或yDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中bnScaleBiasMeanVarDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• saveMean和saveInvVariance指针中只有一个为NULL。

• resultRunningMeanData和resultRunningInvVarianceData指针中只有一个为NULL。

• epsilon值小于MCDNN_BN_MIN_EPSILON。

• xDesc和yDesc的维度或数据类型不匹配。

3.1.1.6. mcdnnDivisiveNormalizationBackward()

该函数执行反向DivisiveNormalization层计算。

mcdnnStatus_t mcdnnDivisiveNormalizationBackward(
mcdnnHandle_t                   handle,
mcdnnLRNDescriptor_t            normDesc,
mcdnnDivNormMode_t              mode,
const void                      *alpha,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *x,
const void                      *means,
const void                      *dy,
void                            *temp,
void                            *temp2,
const void                      *beta,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx,
void                            *dMeans)

支持的张量格式为NCHW（适用于4D）和NCDHW（适用于5D），具有任意非重叠非负值步幅。仅支持4D和5D张量。

参数

handle

输入。已创建的mcDNN库描述符的句柄。

normDesc

输入。已初始化的LRN参数描述符的句柄（此描述符用于LRN和DivisiveNormalization层）。

mode

输入。DivisiveNormalization层操作模式。目前仅支持实现MCDNN_DIVNORM_PRECOMPUTED_MEANS。归一化是使用用户要预计算的均值输入张量来执行的。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将层输出值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, x, means

输入。设备内存中用于层的x和means数据的张量描述符和指针。请注意，means张量应由用户进行预计算。它还可以包含任意有效值（不需要是实际means值，例如可以是高斯内核卷积的结果）。

dy

输入。设备内存中的张量指针，用于层的dy累积损失差分数据（cumulative loss differential data）（错误反向传播）。

temp, temp2

Workspace. 设备内存中的临时张量。这些张量用于在反向传递过程中计算中间值。但在从正向到反向传递的过程中可以不保留。正向和反向传递都使用xDesc作为其描述符。

dxDesc

输入。dx和dMeans的张量描述符。

dx, dMeans

输出。设备内存中的张量指针，用于输出累积梯度dx和dMeans（dLoss/dx和dLoss/dMeans）的层。两者共享相同的描述符。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• x，dx，temp和temp2中任一张量指针为NULL。

• 任意输入张量或输出张量的维数不在[4,5]范围内。

• alpha或beta指针为NULL。

• xDesc和dxDesc之间的维度不匹配。

• LRN描述符参数超出其有效范围。

• 任意张量步幅均为负的。

MCDNN_STATUS_UNSUPPORTED

该函数不支持已提供的配置，例如，不支持输入和输出张量之间的步幅不匹配（同一维度下）。

3.1.1.7. mcdnnDropoutBackward()

此函数以dy执行反向丢弃操作，以dx返回结果。 如果在正向丢弃操作期间，x上的值被传播到y，那么在反向丢弃操作期间，dy的值会传播到dx，否则，dx值将设置为0。

mcdnnStatus_t mcdnnDropoutBackward(
mcdnnHandle_t                   handle,
const mcdnnDropoutDescriptor_t  dropoutDesc,
const mcdnnTensorDescriptor_t   dydesc,
const void                      *dy,
const mcdnnTensorDescriptor_t   dxdesc,
void                            *dx,
void                            *reserveSpace,
size_t                          reserveSpaceSizeInBytes)

完全压缩的张量可获得更好的性能。

参数

handle

输入。已创建的mcDNN上下文的句柄。

dropoutDesc

输入。已创建的丢弃描述符对象。

dyDesc

输入。已初始化的张量描述符的句柄。

dy

输入。指针，指向dyDesc描述符描述的张量数据。

dxDesc

输入。已初始化的张量描述符的句柄。

dx

输出。指针，指向dxDesc描述符描述的张量数据。

reserveSpace

输入。指针，指向此函数使用的用户分配的GPU内存。在调用mcdnnDropoutForward时填充的reserveSpace，且未更改。

reserveSpaceSizeInBytes

输入。指定为预留空间提供的内存大小（以字节为单位）。

返回值

MCDNN_STATUS_SUCCESS

调用成功。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• 输入张量和输出张量的元素数不同。

• 输入张量和输出张量的数据类型不同。

• 输入张量和输出张量的步幅不同，并使用就地操作（即x和y指针相等）。

• 提供的reserveSpaceSizeInBytes小于mcdnnDropoutGetReserveSpaceSize()返回的值。

• 没有在带有非NULL状态参数的dropoutDesc上调用mcdnnSetDropoutDescriptor()。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。

3.1.1.8. mcdnnGetBatchNormalizationBackwardExWorkspaceSize()

此函数返回用户应分配的工作空间GPU内存量，以便能够为指定的bnOps输入设置来调用mcdnnGetBatchNormalizationBackwardExWorkspaceSize()函数。然后，分配的workspace将传入mcdnnGetBatchNormalizationBackwardExWorkspaceSize()函数。

mcdnnStatus_t mcdnnGetBatchNormalizationBackwardExWorkspaceSize(
mcdnnHandle_t                       handle,
mcdnnBatchNormMode_t                mode,
mcdnnBatchNormOps_t                 bnOps,
const mcdnnTensorDescriptor_t       xDesc,
const mcdnnTensorDescriptor_t       yDesc,
const mcdnnTensorDescriptor_t       dyDesc,
const mcdnnTensorDescriptor_t       dzDesc,
const mcdnnTensorDescriptor_t       dxDesc,
const mcdnnTensorDescriptor_t       dBnScaleBiasDesc,
const mcdnnActivationDescriptor_t   activationDesc,
size_t                              *sizeInBytes)

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

bnOps

输入。快速NHWC内核的操作模式。更多信息，参见mcdnnBatchNormOps_t。此输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

xDesc, yDesc, dyDesc, dzDesc, dxDesc

设备内存中的张量描述符和指针，用于层的x数据，反向传播差分dy（输入），可选y输入数据，可选dz输出和dx输出（关于x的结果差分）。更多信息，参见mcdnnTensorDescriptor_t。

dBnScaleBiasDesc

输入。以下6个张量的共享张量描述符：bnScaleData、bnBiasData、dBnScaleData、dBnBiasData、savedMean和savedInvVariance。共享张量描述符，用于通过mcdnnDeriveBNTensorDescriptor()获取的辅助张量。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

activationDesc

输入。激活操作的描述符。

当bnOps输入设置为MCDNN_BATCHNORM_OPS_BN_ACTIVATION或MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

sizeInBytes

输出。工作空间所需的GPU内存量，由该函数确定，以便能够使用指定的bnOps输入设置来执行mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize()函数。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中dBnScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• 任意一对xDesc、dyDesc或dxDesc的维度或数据类型不匹配。

3.1.1.9. mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize()

此函数返回用户应分配的工作空间GPU内存量，以便能够为指定的bnOps输入设置来调用mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize()函数。然后，分配的workspace应由用户传入该函数。

mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize().
mcdnnStatus_t mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize(
mcdnnHandle_t                       handle,
mcdnnBatchNormMode_t                mode,
mcdnnBatchNormOps_t                 bnOps,
const mcdnnTensorDescriptor_t       xDesc,
const mcdnnTensorDescriptor_t       zDesc,
const mcdnnTensorDescriptor_t       yDesc,
const mcdnnTensorDescriptor_t       bnScaleBiasMeanVarDesc,
const mcdnnActivationDescriptor_t   activationDesc,
size_t                              *sizeInBytes);

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

bnOps

输入。快速NHWC内核的操作模式。更多信息，参见mcdnnBatchNormOps_t。此输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

xDesc, zDesc, yDesc

设备内存中的张量描述符和指针，用于层的x数据，可选z输入数据和y输出。仅当bnOps为MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时才需要zDesc，否则用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

bnScaleBiasMeanVarDesc

输入。以下6个张量的共享张量描述符：bnScaleData、bnBiasData、dBnScaleData、dBnBiasData、savedMean和savedInvVariance。 共享张量描述符，用于通过mcdnnDeriveBNTensorDescriptor()获取的辅助张量。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

activationDesc

输入。激活操作的描述符。

当bnOps输入设置为MCDNN_BATCHNORM_OPS_BN_ACTIVATION或MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

sizeInBytes

输出。工作空间所需的GPU内存量，由该函数确定，以便能够使用指定的bnOps输入设置来执行mcdnnGetBatchNormalizationForwardTrainingExWorkspaceSize()函数。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• spatial模式下，4D张量中dBnScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• xDesc或yDesc的维度或数据类型不匹配。

3.1.1.10. mcdnnGetBatchNormalizationTrainingExReserveSpaceSize()

此函数返回用户应分配的预留工作空间GPU内存量，以用于为指定的bnOps输入设置执行BN操作。 与工作空间不同，预留空间应保留在正向和反向调用之间，并且不应更改数据。

mcdnnStatus_t mcdnnGetBatchNormalizationTrainingExReserveSpaceSize(
mcdnnHandle_t                       handle,
mcdnnBatchNormMode_t                mode,
mcdnnBatchNormOps_t                 bnOps,
const mcdnnActivationDescriptor_t   activationDesc,
const mcdnnTensorDescriptor_t       xDesc,
size_t                              *sizeInBytes);

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（spatial或per-activation）。更多信息，参见mcdnnBatchNormMode_t。

bnOps

输入。快速NHWC内核的操作模式。更多信息，参见mcdnnBatchNormOps_t。此输入可用于将此函数设置为仅执行BN，或先执行BN再执行激活，或先执行BN再执行元素级加法，然后执行激活。

xDesc

用于层的x数据的张量描述符。更多信息，参见mcdnnTensorDescriptor_t。

activationDesc

输入。激活操作的描述符。

当bnOps输入设置为MCDNN_BATCHNORM_OPS_BN_ACTIVATION或MCDNN_BATCHNORM_OPS_BN_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

sizeInBytes

输出。预留的GPU内存量。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

3.1.1.11. mcdnnGetNormalizationBackwardWorkspaceSize()

此函数返回用户应分配的工作空间GPU内存量，以便能够为指定的normOps和algo输入设置来调用mcdnnNormalizationBackward()函数。然后，分配的workspace将传入mcdnnNormalizationBackward()函数。

mcdnnStatus_t
mcdnnGetNormalizationBackwardWorkspaceSize(mcdnnHandle_t handle,
mcdnnNormMode_t                 mode,
mcdnnNormOps_t                  normOps,
mcdnnNormAlgo_t                 algo,
const mcdnnTensorDescriptor_t   xDesc,
const mcdnnTensorDescriptor_t   yDesc,
const mcdnnTensorDescriptor_t   dyDesc,
const mcdnnTensorDescriptor_t   dzDesc,
const mcdnnTensorDescriptor_t   dxDesc,
const mcdnnTensorDescriptor_t
                                dNormScaleBiasDesc,
const mcdnnActivationDescriptor_t
                                activationDesc,
const mcdnnTensorDescriptor_t
                                normMeanVarDesc,
size_t                          *sizeInBytes,
int                             groupCnt);

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnNormMode_t。

normOps

输入。post-operative模式。目前，仅在NHWC布局中支持MCDNN_NORM_OPS_NORM_ACTIVATION和MCDNN_NORM_OPS_NORM_ADD_ACTIVATION。更多信息，参见mcdnnNormOps_t。此输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

algo

输入。要执行的算法。更多信息，参见mcdnnNormAlgo_t。

xDesc, yDesc, dyDesc, dzDesc, dxDesc

输入。设备内存中的张量描述符和指针，用于层的x数据，反向传播差分dy（输入），可选y输入数据，可选dz输出和dx输出（关于x的结果差分）。更多信息，参见mcdnnTensorDescriptor_t。

dNormScaleBiasDesc

输入。以下4个张量的共享张量描述符：normScaleData、normBiasData、dNormScaleData、dNormBiasData。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

activationDesc

输入。激活操作的描述符。

当normOps输入设置为MCDNN_NORM_OPS_NORM_ACTIVATION或MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

normMeanVarDesc

输入。以下张量的共享张量描述符：savedMean和savedInvVariance。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

sizeInBytes

输出。工作空间所需的GPU内存量，由该函数确定，以便能够使用指定的normOps输入设置来执行mcdnnGetNormalizationForwardTrainingWorkspaceSize()函数。

groupCnt

输入。分组卷积数。当前仅支持1。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• per-channel模式下，4D张量中dNormScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• 任意一对xDesc、dyDesc或dxDesc的维度或数据类型不匹配。

3.1.1.12. mcdnnGetNormalizationForwardTrainingWorkspaceSize()

此函数返回用户应分配的工作空间GPU内存量，以便能够为指定的normOps和algo输入设置来调用mcdnnNormalizationForwardTraining()函数。 The workspace allocated should t

mcdnnStatus_t
mcdnnGetNormalizationForwardTrainingWorkspaceSize(mcdnnHandle_t handle,
mcdnnNormMode_t                 mode,
mcdnnNormOps_t                  normOps,
mcdnnNormAlgo_t                 algo,
const mcdnnTensorDescriptor_t   xDesc,
const mcdnnTensorDescriptor_t
                                zDesc,
const mcdnnTensorDescriptor_t
                                yDesc,
const mcdnnTensorDescriptor_t
                                normScaleBiasDesc,
const mcdnnActivationDescriptor_t
                                activationDesc,
const mcdnnTensorDescriptor_t
                                normMeanVarDesc,
size_t                          *sizeInBytes,
int                             groupCnt);

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnNormMode_t。

normOps

输入。post-operative模式。目前，仅在NHWC布局中支持MCDNN_NORM_OPS_NORM_ACTIVATION和MCDNN_NORM_OPS_NORM_ADD_ACTIVATION。更多信息，参见mcdnnNormOps_t。此输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

algo

输入。要执行的算法。更多信息，参见mcdnnNormAlgo_t。

xDesc, zDesc, yDesc

设备内存中的张量描述符和指针，用于层的x数据，可选z输入数据和y输出。仅当normOps为MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时才需要zDesc，否则用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

normScaleBiasDesc

输入。以下张量的共享张量描述符：normScaleData和normBiasData。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

activationDesc

输入。激活操作的描述符。

当normOps输入设置为MCDNN_NORM_OPS_NORM_ACTIVATION或MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

normMeanVarDesc

输入。以下张量的共享张量描述符：savedMean和savedInvVariance。此张量描述符的维度取决于归一化模式。请注意，对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，此张量描述符的数据类型必须为double。

sizeInBytes

输出。工作空间所需的GPU内存量，由该函数确定，以便能够使用指定的normOps输入设置来执行mcdnnGetNormalizationForwardTrainingWorkspaceSize()函数。

groupCnt

输入。分组卷积数。当前仅支持1。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc、yDesc或zDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• per-channel模式下，4D张量中normScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• xDesc或yDesc的维度或数据类型不匹配。

3.1.1.13. mcdnnGetNormalizationTrainingReserveSpaceSize()

此函数返回用户应分配的预留工作空间GPU内存量，以用于为指定的normOps输入设置执行归一化操作。与工作空间不同，预留空间应保留在正向和反向调用之间，并且不应更改数据。

mcdnnStatus_t
mcdnnGetNormalizationTrainingReserveSpaceSize(mcdnnHandle_t handle,
mcdnnNormMode_t                 mode,
mcdnnNormOps_t                  normOps,
mcdnnNormAlgo_t                 algo,
const mcdnnActivationDescriptor_t
                                activationDesc,
const mcdnnTensorDescriptor_t   xDesc,
size_t                          *sizeInBytes,
int                             groupCnt);

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnNormMode_t。

normOps

输入。post-operative模式。目前，仅在NHWC布局中支持MCDNN_NORM_OPS_NORM_ACTIVATION和MCDNN_NORM_OPS_NORM_ADD_ACTIVATION。更多信息，参见mcdnnNormOps_t。此输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

algo

输入。要执行的算法。更多信息，参见mcdnnNormAlgo_t。

xDesc

用于层的x数据的张量描述符。更多信息，参见mcdnnTensorDescriptor_t。

activationDesc

输入。激活操作的描述符。

当normOps输入设置为MCDNN_NORM_OPS_NORM_ACTIVATION或MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

sizeInBytes

输出。预留的GPU内存量。

groupCnt

输入。分组卷积数。当前仅支持1。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• xDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

3.1.1.14. mcdnnLRNCrossChannelBackward()

该函数执行反向LRN层计算。

mcdnnStatus_t mcdnnLRNCrossChannelBackward(
mcdnnHandle_t                   handle,
mcdnnLRNDescriptor_t            normDesc,
mcdnnLRNMode_t                  lrnMode,
const void                      *alpha,
const mcdnnTensorDescriptor_t   yDesc,
const void                      *y,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dy,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *x,
const void                      *beta,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx)

支持的格式包括：positive-strided，NCHW和NHWC（适用于4D x和y），以及5D中仅支持NCDHW DHW-packed（适用于x和y）。仅支持非重叠4D和5D张量。使用NCHW布局，性能更优。

参数

handle

输入。已创建的mcDNN库描述符的句柄。

normDesc

输入。已初始化的LRN参数描述符的句柄。

lrnMode

输入。LRN层操作模式。目前仅支持实现MCDNN_LRN_CROSS_CHANNEL_DIM1。归一化在张量的dimA[1]维中执行。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将层输出值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

yDesc, y

输入。设备内存中用于层的y数据的张量描述符和指针。

dyDesc, dy

输入。设备内存中的张量描述符和指针，用于层的dy输入累积损失差分数据（包括错误反向传播）。

xDesc, x

输入。设备内存中用于层的x数据的张量描述符和指针。请注意，在反向传播过程中不会修改这些值。

dxDesc, dx

输出。设备内存中的张量描述符和指针，用于层的dx累积损失差分数据结果（包括错误反向传播）。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• x和y中任一张量指针为NULL。

• 输入张量维数小于或等于2。

• LRN描述符参数超出其有效范围。

• 任一张量参数为5D，但不是NCDHW DHW-packed格式。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。不受支持的配置示例如下：

• 任意输入张量数据类型都与输出张量数据类型不同。

• x，y，dx或dy的任何成对（pairwise）张量维度不匹配。

• 任意张量参数步幅均为负的。

3.1.1.15. mcdnnNormalizationBackward()

此函数执行模式指定的反向归一化层计算。对于per-channel归一化层，可参见Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift。

mcdnnStatus_t
mcdnnNormalizationBackward(mcdnnHandle_t handle,
mcdnnNormMode_t                 mode,
mcdnnNormOps_t                  normOps,
mcdnnNormAlgo_t                 algo,
const void                      *alphaDataDiff,
const void                      *betaDataDiff,
const void                      *alphaParamDiff,
const void                      *betaParamDiff,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *xData,
const mcdnnTensorDescriptor_t   yDesc,
const void                      *yData,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dyData,
const mcdnnTensorDescriptor_t   dzDesc,
void                            *dzData,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dxData,
const mcdnnTensorDescriptor_t   dNormScaleBiasDesc,
const void                      *normScaleData,
const void                      *normBiasData,
void                            *dNormScaleData,
void                            *dNormBiasData,
double                          epsilon,
const mcdnnTensorDescriptor_t   normMeanVarDesc,
const void                      *savedMean,
const void                      *savedInvVariance,
mcdnnActivationDescriptor_t     activationDesc,
void                            *workSpace,
size_t                          workSpaceSizeInBytes,
void                            *reserveSpace,
size_t                          reserveSpaceSizeInBytes,
int                             groupCnt)

仅支持4D和5D张量。

在训练，反向传播和推理过程中的epsilon值必须相同。 此workspace不需要清理。此外，workspace不必在正向和反向传递之间保持不变，因为它不用于传递任何信息。

此函数可以接受指向GPU workspace的workspace指针，以及来自用户的workSpaceSizeInBytes（workspace大小）。

normOps输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

张量布局为NCHW时，若x、dy和dx都使用HW-packed张量时，可以获得更高的性能。

当满足以下条件时，可以获得MCDNN_NORM_PER_CHANNEL模式的更高性能：

• 所有张量，即x、y、dz、dy和dx，必须是NHWC完全压缩，并且类型必须是MCDNN_DATA_HALF。

• C张量维度应为4的倍数。

• 输入参数模式必须设置为MCDNN_NORM_PER_CHANNEL。

• 输入参数算法必须设置为MCDNN_NORM_ALGO_PERSIST。

• workspace不是NULL。

• WorkSpaceSizeInBytes等于或大于mcdnnGetNormalizationBackwardWorkspaceSize()所需的量。

• ReserveSpaceSizeInBytes等于或大于mcdnnGetNormalizationTrainingReserveSpaceSize()所需的量。

• 必须保留使用mcdnnNormalizationForwardTraining()存储在reserveSpace中的内容。

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnNormMode_t。

normOps

输入。post-operative模式。目前，仅在NHWC布局中支持MCDNN_NORM_OPS_NORM_ACTIVATION和MCDNN_NORM_OPS_NORM_ADD_ACTIVATION。更多信息，参见mcdnnNormOps_t。此输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

algo

输入。要执行的算法。更多信息，参见mcdnnNormAlgo_t。

alphaDataDiff, betaDataDiff

输入。指向缩放系数（主机内存中）的指针，用于将dx梯度输出与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

alphaParamDiff, betaParamDiff

输入。指向缩放系数（主机内存中）的指针，用于将dNormScaleData和dNormBiasData梯度输出与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, xData, yDesc, yData, dyDesc, dyData

输入。用于层的x数据，反向传播梯度输入dy，原始正向输出y数据的张量描述符和指针，位于设备内存中。如果normOps设置为MCDNN_NORM_OPS_NORM，则不需要yDesc和yData，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dzDesc, dxDesc

输入。用于计算梯度输出dz和dx的张量描述符和指针，位于设备内存中。 当normOps为MCDNN_NORM_OPS_NORM或MCDNN_NORM_OPS_NORM_ACTIVATION时，不需要dzDesc，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dzData, dxData

输出。用于计算梯度输出dz和dx的张量描述符和指针，位于设备内存中。 当normOps为MCDNN_NORM_OPS_NORM或MCDNN_NORM_OPS_NORM_ACTIVATION时，不需要dzData，用户可以传入NULL。更多信息，参见mcdnnTensorDescriptor_t。

dNormScaleBiasDesc

输入。以下4个张量的共享张量描述符：normScaleData、normBiasData、dNormScaleData、dNormBiasData。此张量描述符的维度取决于归一化模式。

备注

• 对于FP16和FP32输入张量，此张量描述符的数据类型必须为float。

• 对于FP64输入张量，必须为double。

normScaleData

输入。设备内存中指向归一化scale参数的指针。(在 Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift中，数量scale称为gamma)。

normBiasData

输入。设备内存中指向归一化bias参数的指针。(在 Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift中，bias称为beta)。 此参数仅在执行激活时使用。

dNormScaleData, dNormBiasData

输出。设备内存中分别指向normScaleData和normBiasData梯度的指针。

epsilon

输入。归一化公式中使用的Epsilon值。其值应等于或大于零。在正向和反向函数中应使用相同的Epsilon值。

normMeanVarDesc

输入。以下张量的共享张量描述符：savedMean和savedInvVariance。此张量描述符的维度取决于归一化模式。

备注

对于FP16和FP32输入张量，此张量描述符的数据类型必须为float；对于FP64输入张量，必须为double。

savedMean, savedInvVariance

输入。可选的cache参数，包含在正向传递过程中计算并保存的中间结果。为保证工作正常，在调用此反向函数之前，层的x和normScaleData、normBiasData数据必须保持不变。 请注意这两个参数可以为NULL，但只能同时为NULL。建议使用此cache，因为内存开销相对较小。

activationDesc

输入。激活操作的描述符。

当normOps输入设置为MCDNN_NORM_OPS_NORM_ACTIVATION或MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

workspace

输入。指向GPU工作空间的指针。

workSpaceSizeInBytes

输入。workspace的大小。它必须足够大，才能通过此函数触发快速NHWC半持久内核。

reserveSpace

输入。指针，指向用作reserveSpace的GPU工作空间。

reserveSpaceSizeInBytes

输入。reserveSpace的大小。它必须等于或大于mcdnnGetNormalizationTrainingReserveSpaceSize()所需的量。

groupCnt

输入。分组卷积的数量。当前仅支持1。

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alphaDataDiff、betaDataDiff、alphaParamDiff、betaParamDiff、xData、dyData、dxData、normScaleData、dNormScaleData和dNormBiasData中任意指针为NULL。

• xDesc、yDesc或dxDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• per-channel模式下，4D张量中dNormScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• savedMean和savedInvVariance指针中只有一个为NULL。

• epsilon的值小于0。

• 任意一对xDesc、dyDesc、dxDesc、dNormScaleBiasDesc或normMeanVarDesc的维度或数据类型不匹配。

3.1.1.16. mcdnnNormalizationForwardTraining()

此函数在训练阶段执行正向归一化层计算。根据模式，将执行不同的归一化操作。对于Per-channel层，可参见Batch Normalization: Accelerating Deep Network Training by Reducing Internal Covariate Shift。

mcdnnStatus_t
mcdnnNormalizationForwardTraining(mcdnnHandle_t handle,
mcdnnNormMode_t                 mode,
mcdnnNormOps_t                  normOps,
mcdnnNormAlgo_t                 algo,
const void                      *alpha,
const void                      *beta,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *xData,
const mcdnnTensorDescriptor_t   normScaleBiasDesc,
const void                      *normScale,
const void                      *normBias,
double                          exponentialAverageFactor,
const mcdnnTensorDescriptor_t   normMeanVarDesc,
void                            *resultRunningMean,
void                            *resultRunningVariance,
double                          epsilon,
void                            *resultSaveMean,
void                            *resultSaveInvVariance,
mcdnnActivationDescriptor_t     activationDesc,
const mcdnnTensorDescriptor_t   zDesc,
const void                      *zData,
const mcdnnTensorDescriptor_t   yDesc,
void                            *yData,
void                            *workspace,
size_t                          workSpaceSizeInBytes,
void                            *reserveSpace,
size_t                          reserveSpaceSizeInBytes,
int                             groupCnt);

仅支持4D和5D张量。

在训练，反向传播和推理过程中的epsilon值必须相同。

有关推理阶段的信息，请参见mcdnnNormalizationForwardInference()。

当x和y都使用HW-packed张量时，可以获得更高的性能。

当满足以下条件时，此API将触发新的半持久NHWC内核：

• 所有张量，即xData和yData，必须是NHWC完全压缩，并且类型必须是MCDNN_DATA_HALF。

• C张量维度应为4的倍数。

• 输入参数模式必须设置为MCDNN_NORM_PER_CHANNEL。

• 输入参数算法必须设置为MCDNN_NORM_ALGO_PERSIST。

• workspace不是NULL。

• WorkSpaceSizeInBytes等于或大于mcdnnGetNormalizationForwardTrainingWorkspaceSize()所需的量。

• ReserveSpaceSizeInBytes等于或大于mcdnnGetNormalizationTrainingReserveSpaceSize()所需的量。

• 必须保留使用mcdnnNormalizationForwardTraining()存储在reserveSpace中的内容。

此workspace不需要清理。此外，workspace不必在正向和反向传递之间保持不变，因为它不用于传递任何信息。此扩展函数可以接受指向GPU workspace的workspace指针，以及来自用户的workSpaceSizeInBytes（workspace大小）。

normOps输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

仅支持4D和5D张量。在训练，反向传播和推理过程中的epsilon值必须相同。

张量布局为NCHW时，若xData和yData都使用HW-packed张量时，可以获得更高的性能。

参数

handle

输入。已创建的mcDNN库描述符的句柄。更多信息，参见mcdnnHandle_t。

mode

输入。操作模式（per-channel或per-activation）。更多信息，参见mcdnnNormMode_t。

normOps

输入。 post-operative模式。目前，仅在NHWC布局中支持MCDNN_NORM_OPS_NORM_ACTIVATION和MCDNN_NORM_OPS_NORM_ADD_ACTIVATION。更多信息，参见mcdnnNormOps_t。此输入可用于将此函数设置为仅执行归一化，或先执行归一化再执行激活，或先执行归一化再执行元素级加法，然后执行激活。

algo

输入。要执行的算法。更多信息，参见mcdnnNormAlgo_t。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将层输出值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

xDesc, yDesc

输入。已初始化的张量描述符的句柄。

xData

输入。数据指针，指向与张量描述符xDesc关联的GPU内存，用于层的x输入数据。

yData

输出。数据指针，指向与张量描述符yDesc关联的GPU内存，用于归一化层的y输出。

zDesc, zData

输入。在激活之前，设备内存中用于归一化运算结果残差相加的张量描述符和指针。zDesc和zData是可选的，仅当normOps为MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时使用，否则用户可以传入NULL。使用时，z的维度应与xData和最终输出y的维度完全相同。更多信息，参见mcdnnTensorDescriptor_t。

normScaleBiasDesc, normScale, normBias

输入。设备内存中用于归一化scale和bias参数的张量描述符和指针。 此张量描述符的维度取决于归一化模式。

exponentialAverageFactor

输入。移动平均（Moving Average，MA）计算中使用的系数如下：

runningMean = runningMean*(1-factor) + newMean*factor

在对函数的第N次调用中使用factor=1/(1+n)可进行累积移动平均（Cumulative Moving Average，CMA）计算，例如：

CMA[n] = (x[1]+…+x[n])/n

例如：

CMA[n+1] = (n*CMA[n]+x[n+1])/(n+1)

= ((n+1)*CMA[n]-CMA[n])/(n+1) + x[n+1]/(n+1)

= CMA[n]*(1-1/(n+1))+x[n+1]*1/(n+1)

= CMA[n]*(1-factor) + x(n+1)*factor

normMeanVarDesc

输入。用于以下张量的张量描述符：resultRunningMean, resultRunningVariance, resultSaveMean, resultSaveInvVariance。

resultRunningMean, resultRunningVariance

输入/输出。指向移动均值和移动方差数据的指针。这两个指针可以为NULL，但只能同时为NULL。存储在resultRunningVariance中（或作为推理模式中的输入被传入）的值是样本方差，是方差[x]的移动平均值，其中方差是根据模式在batch或spatial+batch维度上进行计算的。如果这些指针不为NULL，则张量应初始化为一些合理的值或0。

epsilon

输入。归一化公式中使用的Epsilon值。其值应等于或大于零。

resultSaveMean, resultSaveInvVariance

输出。可选的cache参数，包含在正向传递过程中计算并保存的中间结果。为保证工作正常，在调用此反向函数之前，层的x和normScale、normBias数据必须保持不变。请注意这两个参数可以为NULL，但只能同时为NULL。建议使用此cache，因为内存开销相对较小。

activationDesc

输入。激活操作的张量描述符。

当normOps输入设置为MCDNN_NORM_OPS_NORM_ACTIVATION或MCDNN_NORM_OPS_NORM_ADD_ACTIVATION时，将使用此激活，否则用户可以传入NULL。

workspace, workSpaceSizeInBytes

输入。workspace是指向GPU工作空间的指针，workSpaceSizeInBytes是workspace的大小。当workspace不为NULL且workSpaceSizeInBytes足够大，张量布局为NHWC且数据类型配置受支持时，此函数将触发一个半持久NHWC内核以进行归一化操作。此workspace不需要清理。此外，workspace不需要在正向和反向传递之间保持不变。

reserveSpace

输入。指针，指向用作reserveSpace的GPU工作空间。

reserveSpaceSizeInBytes

输入。reserveSpace的大小。必须等于或大于mcdnnGetNormalizationTrainingReserveSpaceSize()所需的量。

groupCnt

输入。分组卷积数。当前仅支持1。

支持的mcdnnNormalizationForwardTraining()配置

数据类型 配置	wDesc， dyDesc， zDesc 数据类型	normScaleBiasDesc， normMeanVarDesc 数据类型
PSEUDO _HALF_CONFIG	MCDNN_DATA_HALF	MCDNN_DATA_FLOAT
PSEUDO _BFLOAT16_CONFIG	MCDNN_DATA_BFLOAT16	MCDNN_DATA_FLOAT
FLOAT_CONFIG	MCDNN_DATA_FLOAT	MCDNN_DATA_FLOAT
DOUBLE_CONFIG	MCDNN_DATA_DOUBLE	MCDNN_DATA_DOUBLE

返回值

MCDNN_STATUS_SUCCESS

计算已成功执行。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• alpha、beta、xData、yData、normScale和normBias中任一指针为NULL。

• xDesc或yDesc张量描述符维数不在[4,5]范围内（仅支持4D和5D张量）。

• per-channel模式下，4D张量中normScaleBiasDesc的维度不是1xCx1x1，5D张量中不是1xCx1x1x1；per-activation模式下，4D张量中不是1xCxHxW，5D张量中不是1xCxDxHxW。

• resultSaveMean和resultSaveInvVariance指针中只有一个为NULL。

• resultRunningMean和resultRunningInvVariance指针中只有一个为NULL。

• epsilon的值小于0。

• xDesc或yDesc的维度或数据类型不匹配。

3.1.1.17. mcdnnOpsTrainVersionCheck()

此函数检查库的OpsTrain子集的版本是否与其他子库一致。

mcdnnStatus_t mcdnnOpsTrainVersionCheck(void)

返回值

MCDNN_STATUS_SUCCESS

版本与其他子库一致。

MCDNN_STATUS_VERSION_MISMATCH

OpsTrain的版本与其他子库不一致。用户应检查并确保所有子组件安装版本一致。

3.1.1.18. mcdnnPoolingBackward()

该函数计算池化操作的梯度。

mcdnnStatus_t mcdnnPoolingBackward(
mcdnnHandle_t                   handle,
const mcdnnPoolingDescriptor_t  poolingDesc,
const void                      *alpha,
const mcdnnTensorDescriptor_t   yDesc,
const void                      *y,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dy,
const mcdnnTensorDescriptor_t   xDesc,
const void                      *xData,
const void                      *beta,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx)

备注

此函数中的任意张量描述符参数都不支持张量向量化。使用HW-packed张量，性能会最佳。只支持2个和3个空间维度。

mcdnnPoolingBackward()允许平均池化的x和y数据指针（以及相关的张量描述符句柄）为NULL。这可以节省内存空间和带宽。

参数

handle

输入。已创建的mcDNN上下文的句柄。

poolingDesc

输入。已初始化的池化描述符的句柄。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将计算结果与输出层中的先验值混合，如下所示： dstValue = alpha[0]*resultValue + beta[0]*priorDstValue。

yDesc

输入。已初始化的输入张量描述符的句柄。平均池化中可以为NULL。

y

输入。数据指针，指向与张量描述符yDesc关联的GPU内存。平均池化中可以为NULL。

dyDesc

输入。已初始化的输入差分张量描述符的句柄。 类型必须为FLOAT、DOUBLE、HALF或BFLOAT16。更多信息，参见mcdnnDataType_t。

dy

输入。数据指针，指向与张量描述符dyDesc关联的GPU内存。

xDesc

输入。已初始化的输出张量描述符的句柄。平均池化中可以为NULL。

x

输入。数据指针，指向与输出张量描述符xDesc关联的GPU内存。平均池化中可以为NULL。

dxDesc

输入。已初始化的输出差分张量描述符的句柄。 类型必须为FLOAT、DOUBLE、HALF或BFLOAT16。更多信息，参见mcdnnDataType_t。

dx

输出。数据指针，指向与输出张量描述符dxDesc关联的GPU内存。

返回值

MCDNN_STATUS_SUCCESS

此函数启用成功。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• yDesc和dyDesc张量的n，c，h，w维度不同。

• yDesc和dyDesc张量的nStride、cStride、hStride和wStride步幅不同。

• xDesc和dxDesc张量的n，c，h，w维度不同。

• xDesc和dxDesc张量的nStride、cStride、hStride和wStride步幅不同。

• 4个张量的datatype不一样。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。不受支持的配置示例如下：

• 输入张量或输出张量的wStride不是1。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。

3.1.1.19. mcdnnSoftmaxBackward()

此函数计算softmax函数的梯度。

mcdnnStatus_t mcdnnSoftmaxBackward(
mcdnnHandle_t                   handle,
mcdnnSoftmaxAlgorithm_t         algorithm,
mcdnnSoftmaxMode_t              mode,
const void                      *alpha,
const mcdnnTensorDescriptor_t   yDesc,
const void                      *yData,
const mcdnnTensorDescriptor_t   dyDesc,
const void                      *dy,
const void                      *beta,
const mcdnnTensorDescriptor_t   dxDesc,
void                            *dx)

该函数支持就地操作（In-place Operation）；这意味着，dy和dx指针可以一样。 但是，这要求dyDesc描述符和dxDesc描述符必须相同（特别是输入和输出的步幅必须匹配，才能支持就地操作）。 所有张量格式都支持4D和5D张量的所有模式和算法。 NCHW完全压缩格式（fully packed）张量的性能最佳。超过5个维度的张量，必须在其空间维度中进行压缩。

数据类型

此函数支持以下数据类型：

• MCDNN_DATA_FLOAT

• MCDNN_DATA_DOUBLE

• MCDNN_DATA_HALF

• MCDNN_DATA_BFLOAT16

参数

handle

输入。已创建的mcDNN上下文的句柄。

algorithm

输入。指定softmax算法的枚举。

mode

输入。指定softmax模式的枚举。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将计算结果与输出层中的先验值混合，如下所示： dstValue = alpha[0]*result + beta[0]*priorDstValue。

yDesc

输入。已初始化的输入张量描述符的句柄。

y

输入。数据指针，指向与张量描述符yDesc关联的GPU内存。

dyDesc

输入。已初始化的输入差分张量描述符的句柄。

dy

输入。数据指针，指向与张量描述符dyDesc关联的GPU内存。

dxDesc

输入。已初始化的输出差分张量描述符的句柄。

dx

输出。数据指针，指向与输出张量描述符dxDesc关联的GPU内存。

返回值

MCDNN_STATUS_SUCCESS

此函数启用成功。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• yDesc、dyDesc和dxDesc张量的n，c，h，w维度不同。

• yDesc和dyDesc张量的nStride、cStride、hStride和wStride步幅不同。

• 3个张量的datatype不一样。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。

3.1.1.20. mcdnnSpatialTfGridGeneratorBackward()

该函数计算网格生成（Grid Generation）操作的梯度。

mcdnnStatus_t mcdnnSpatialTfGridGeneratorBackward(
mcdnnHandle_t                               handle,
const mcdnnSpatialTransformerDescriptor_t   stDesc,
const void                                  *dgrid,
void                                        *dtheta)

仅支持2D转换。

参数

handle

输入。已创建的mcDNN上下文的句柄。

stDesc

输入。已创建的空间转换描述符对象。

dgrid

输入。数据指针,指向包含输入差分数据的GPU内存。

dtheta

输出。数据指针,指向包含输出差分数据的GPU内存。

返回值

MCDNN_STATUS_SUCCESS

调用成功。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• handle为NULL。

• dgrid和dtheta中任一参数为NULL。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。不受支持的配置示例如下：

• stDesc中指定的转换张量的维度> 4。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。

3.1.1.21. mcdnnSpatialTfSamplerBackward()

该函数计算采样（Sampling）操作的梯度。

mcdnnStatus_t mcdnnSpatialTfSamplerBackward(
mcdnnHandle_t                               handle,
const mcdnnSpatialTransformerDescriptor_t   stDesc,
const void                                  *alpha,
const mcdnnTensorDescriptor_t               xDesc,
const void                                  *x,
const void                                  *beta,
const mcdnnTensorDescriptor_t               dxDesc,
void                                        *dx,
const void                                  *alphaDgrid,
const mcdnnTensorDescriptor_t               dyDesc,
const void                                  *dy,
const void                                  *grid,
const void                                  *betaDgrid,
void                                        *dgrid)

仅支持2d转换。

参数

handle

输入。已创建的mcDNN上下文的句柄。

stDesc

输入。已创建的空间转换描述符对象。

alpha, beta

输入。指向缩放系数（主机内存中）的指针，用于将源数值与目标张量中的先验值混合，如下所示： dstValue = alpha[0]*srcValue + beta[0]*priorDstValue。

xDesc

输入。已初始化的输入张量描述符的句柄。

x

输入。数据指针，指向与张量描述符xDesc关联的GPU内存。

dxDesc

输入。已初始化的输出差分张量描述符的句柄。

dx

输出。数据指针，指向与输出张量描述符dxDesc关联的GPU内存。

alphaDgrid, betaDgrid

输入。指向缩放系数（主机内存中）的指针，用于将dgrid梯度输出与目标指针中的先验值混合，如下所示： dstValue = alpha[0]*srcValue + beta[0]*priorDstValue。

dyDesc

输入。已初始化的输入差分张量描述符的句柄。

dy

输入。数据指针，指向与张量描述符dyDesc关联的GPU内存。

grid

输入。由mcdnnSpatialTfGridGeneratorForward()生成的坐标网格。

dgrid

输出。数据指针,指向包含输出差分数据的GPU内存。

返回值

MCDNN_STATUS_SUCCESS

调用成功。

MCDNN_STATUS_BAD_PARAM

需至少满足以下任一条件：

• handle为NULL。

• x、dx、y、dy、grid、dgrid中任一参数为NULL。

• dy的维度与stDesc中指定的维度不同。

MCDNN_STATUS_NOT_SUPPORTED

此函数不支持已提供的配置。不受支持的配置示例如下：

• 转换张量的维度> 4。

MCDNN_STATUS_EXECUTION_FAILED

此函数在GPU上启用失败。