I've revised the buffer doc again to incorporate the latest discussion regarding persistent vs. non-persistent user meta data long with proposals for how to deal with some of the issues discussed last wee. They are highlighted as comments in the doc and are summarized here for discussion.
Recall that the issue raised by Ola and others is what happens to persistent user meta data across possible buffer replacement as part of API calls. For example, odp_crypto_op() may consume the input buffer and return its results in a new buffer upon return. The suggested rule is summarized in this rev of the doc as follows: In addition to system meta data associated with each buffer in a pool, ODP enables the application to reserve a number of bytes of user meta data for its own use. While ODP implementations MUST support user meta data, this data MAY or MAY NOT be persistent. Persistent means that it has a fixed implementation-assigned address that remains addressable to the application and retains its contents across allocates and frees of the buffer it is associated with. In this context persistence means that whatever was in the user meta data at the time the buffer was freed is still there when it is subsequently reallocated. By contrast, user meta data that is not persistent cannot be relied upon to survive a buffer free operation. In this case it is an application responsibility to ensure that if the user meta data itself contains pointers to other storage areas that they are appropriately freed or reference-counted prior to freeing the buffer and that the user meta data is re-initialized whenever a buffer is allocated from its containing buffer pool. The ODP_BUFFER_OPTS_UDATA_PERSIST option is used to request that user meta data be persistent. Note that implementations MAY provide persistent user meta data by default if they choose. This option is used by the application to indicate that it requires persistence. ... User meta data management is an application responsibility with the following provision. If as part of an ODP API call an ODP implementation replaces a buffer with an equivalent output buffer as part of its processing, then any non-persistent user meta data associated with the input buffer MUST be copied to the new buffer as part of the operation of the API. If the user meta data is persistent, then any such copy operation required is the responsibility of the application. For example, if an application queues a buffer to a crypto engine that returns a different buffer from the one supplied to it, then as part of the processing of that call, the underlying ODP implementation MUST copy the input buffer user meta data to the output buffer as part of its processing if the user meta data is non-persistent. The reason for this provision is that the application always has addressability to persistent user meta data even if a buffer is freed and so can perform whatever copying it needs from the original buffer upon receiving the replacement buffer. Applications can use the odp_buffer_is_same() routine to determine if two odp_buffer_t objects refer to the same buffer. I believe adoption of this rule should enable determinate application and implementation behavior with regard to user meta data in all cases. To aid in this expanded definition, two new APIs are introduced: First, the existing API odp_buffer_udata() is expanded to return a persist indicator: void *odp_buffer_udata(odp_buffer_t but, size_t *size, int *persist); This is so implementations can easily determine if the buffer contains non-persistent user meta data that it might need to copy to a returned buffer. Since this "full form" of the routine is getting a bit "bushy" for performance paths, a fast-path routine is introduced: void *odp_buffer_udata_addr(odp_buffer_t buf); That simply returns the address of the user meta data to the caller. In this case it is assumed the caller already knows its size and persistence attribute. Second, to enable applications to know if they've been given a replacement buffer upon return from calls that might do this, an explicit buffer comparison call is introduced: int odp_buffer_is_same(odp_buffer_t buf1, odp_buffer_t buf2); that allows the caller to compare two buffer handles to determine if they are the same. For most implementations this is expected to be a simple inlined test for equality (==) but is encapsulated in an API call because odp_buffer_t is an opaque type. I hope to wrap up final discussions relating to this during tomorrow's call. We'll also be covering what's planned for ODP during LCU next week. Bill ODP v1.0 Buffer Management API Design - Final <https://docs.google.com/a/linaro.org/document/d/1sleFBhG2E-TorClpaBHxOhRu0pA5e2l-JNAE732SRto/edit?usp=drive_web>
_______________________________________________ lng-odp mailing list [email protected] http://lists.linaro.org/mailman/listinfo/lng-odp
