diff --git a/contrib/mock_main.cc b/contrib/mock_main.cc index 03798ce..46f43fd 100644 --- a/contrib/mock_main.cc +++ b/contrib/mock_main.cc @@ -2,6 +2,14 @@ #include #include +int CheckFlags(DLManagedTensorVersioned *data) { + if (data->flags & DLPACK_FLAG_BITMASK_READ_ONLY) { + return 0; + } else { + return 1; + } +} + int main() { dlpack::DLTContainer c; return 0; diff --git a/docs/source/c_api.rst b/docs/source/c_api.rst index 9ef9f64..87516ba 100644 --- a/docs/source/c_api.rst +++ b/docs/source/c_api.rst @@ -8,7 +8,9 @@ Macros .. doxygendefine:: DLPACK_EXTERN_C -.. doxygendefine:: DLPACK_VERSION +.. doxygendefine:: DLPACK_MAJOR_VERSION + +.. doxygendefine:: DLPACK_MINOR_VERSION .. doxygendefine:: DLPACK_DLL @@ -22,6 +24,9 @@ Enumerations Structs ~~~~~~~ +.. doxygenstruct:: DLPackVersion + :members: + .. doxygenstruct:: DLDevice :members: @@ -33,3 +38,6 @@ Structs .. doxygenstruct:: DLManagedTensor :members: + +.. doxygenstruct:: DLManagedTensorVersioned + :members: diff --git a/include/dlpack/dlpack.h b/include/dlpack/dlpack.h index 6d51801..0bdc1fe 100644 --- a/include/dlpack/dlpack.h +++ b/include/dlpack/dlpack.h @@ -15,11 +15,11 @@ #define DLPACK_EXTERN_C #endif -/*! \brief The current version of dlpack */ -#define DLPACK_VERSION 80 +/*! \brief The current major version of dlpack */ +#define DLPACK_MAJOR_VERSION 1 -/*! \brief The current ABI version of dlpack */ -#define DLPACK_ABI_VERSION 1 +/*! \brief The current minor version of dlpack */ +#define DLPACK_MINOR_VERSION 0 /*! \brief DLPACK_DLL prefix for windows */ #ifdef _WIN32 @@ -38,6 +38,33 @@ #ifdef __cplusplus extern "C" { #endif + +/*! + * \brief The DLPack version. + * + * A change in major version indicates that we have changed the + * data layout of the ABI - DLManagedTensorVersioned. + * + * A change in minor version indicates that we have added new + * code, such as a new device type, but the ABI is kept the same. + * + * If an obtained DLPack tensor has a major version that disagrees + * with the version number specified in this header file + * (i.e. major != DLPACK_MAJOR_VERSION), the consumer must call the deleter + * (and it is safe to do so). It is not safe to access any other fields + * as the memory layout will have changed. + * + * In the case of a minor version mismatch, the tensor can be safely used as + * long as the consumer knows how to interpret all fields. Minor version + * updates indicate the addition of enumeration values. + */ +typedef struct { + /*! \brief DLPack major version. */ + uint32_t major; + /*! \brief DLPack minor version. */ + uint32_t minor; +} DLPackVersion; + /*! * \brief The device type in DLDevice. */ @@ -211,6 +238,13 @@ typedef struct { * not meant to transfer the tensor. When the borrowing framework doesn't need * the tensor, it should call the deleter to notify the host that the resource * is no longer needed. + * + * \note This data structure is used as Legacy DLManagedTensor + * in DLPack exchange and is deprecated after DLPack v0.8 + * Use DLManagedTensorVersioned instead. + * This data structure may get renamed or deleted in future versions. + * + * \sa DLManagedTensorVersioned */ typedef struct DLManagedTensor { /*! \brief DLTensor which is being memory managed */ @@ -219,13 +253,65 @@ typedef struct DLManagedTensor { * which DLManagedTensor is used in the framework. It can also be NULL. */ void * manager_ctx; - /*! \brief Destructor signature void (*)(void*) - this should be called - * to destruct manager_ctx which holds the DLManagedTensor. It can be NULL - * if there is no way for the caller to provide a reasonable destructor. - * The destructors deletes the argument self as well. + /*! + * \brief Destructor - this should be called + * to destruct the manager_ctx which backs the DLManagedTensor. It can be + * NULL if there is no way for the caller to provide a reasonable destructor. + * The destructors deletes the argument self as well. */ void (*deleter)(struct DLManagedTensor * self); } DLManagedTensor; + +// bit masks used in in the DLManagedTensorVersioned + +/*! \brief bit mask to indicate that the tensor is read only. */ +#define DLPACK_FLAG_BITMASK_READ_ONLY (1UL << 0UL) + +/*! + * \brief A versioned and managed C Tensor object, manage memory of DLTensor. + * + * This data structure is intended to facilitate the borrowing of DLTensor by + * another framework. It is not meant to transfer the tensor. When the borrowing + * framework doesn't need the tensor, it should call the deleter to notify the + * host that the resource is no longer needed. + * + * \note This is the current standard DLPack exchange data structure. + */ +struct DLManagedTensorVersioned { + /*! + * \brief The API and ABI version of the current managed Tensor + */ + DLPackVersion version; + /*! + * \brief the context of the original host framework. + * + * Stores DLManagedTensorVersioned is used in the + * framework. It can also be NULL. + */ + void *manager_ctx; + /*! + * \brief Destructor. + * + * This should be called to destruct manager_ctx which holds the DLManagedTensorVersioned. + * It can be NULL if there is no way for the caller to provide a reasonable + * destructor. The destructors deletes the argument self as well. + */ + void (*deleter)(struct DLManagedTensorVersioned *self); + /*! + * \brief Additional bitmask flags information about the tensor. + * + * By default the flags should be set to 0. + * + * \note Future ABI changes should keep everything until this field + * stable, to ensure that deleter can be correctly called. + * + * \sa DLPACK_FLAG_BITMASK_READ_ONLY + */ + uint64_t flags; + /*! \brief DLTensor which is being memory managed */ + DLTensor dl_tensor; +}; + #ifdef __cplusplus } // DLPACK_EXTERN_C #endif