Ignore:
Timestamp:
Nov 19, 2020, 11:47:00 PM (3 years ago)
Author:
alain
Message:

Cosmetic.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/kernel/libk/remote_buf.h

    r666 r671  
    3232 * This structure and the associated access functions define a remotely accessible,
    3333 * kernel buffer, handled as a single-reader & single-writer FIFO.
    34  * This kernel buffer is implementes as an array of bytes, whose size is
    35  * dynamically defined by an argument of the "remote_buf_init()" function.
     34 * This kernel buffer is implementes as an array of bytes. The size must be a power
     35 * of 2, dynamically defined by an argument of the "remote_buf_init()" function.
    3636 * The "put()" and "get()" functions defined below move the content of another
    3737 * buffer (can be in kernel or in user space) to/from this circular kernel buffer.
    3838 * This structure is NOT protected by a lock, as the only shared variable is the
    3939 * "sts" variable, that is updated by the hal_remote_atomic_add() primitive.
    40  * It is used to implement the three socket buffers (rx_buf / r2tq / crqq).
    41  * - the "ptw" field defines the first empty slot (for write).
    42  * - the "ptr" field defines the first non empty slot (for read).
    43  * - the "sts" field defines the total number of non empty slots.
     40 *
     41 * - It is used to implement the three socket buffers (rx_buf / r2tq / crqq).
     42 * - It is also used to implement the inter-process communications channels
     43 *   based on named "fifos", or unamed "pipes".
    4444 ***********************************************************************************/
    4545
    4646typedef struct remote_buf_s
    4747{
    48     uint32_t   size;    /*! number of slots in data buffer                         */
    49         uint32_t   ptw;     /*! first empty slot index                                 */
    50         uint32_t   ptr;     /*! first non-empty slot index                             */
     48    uint32_t   order;   /*! ln2( size of data buffer in bytes)                     */
     49        uint32_t   rid;     /*! first empty slot index                                 */
     50        uint32_t   wid;     /*! first non-empty slot index                             */
    5151    uint32_t   sts;     /*! current number of non empty slots                      */
    5252        uint8_t  * data;    /*! local pointer on local data buffer                     */
    … …  
    5555
    5656/************************************************************************************
     57 * This function allocates memory for a remote_buf descriptor in cluster
     58 * defined by the <cxy> argument, and return a local pointer on this descriptor.
     59 ************************************************************************************
     60 * @ cxy    : target cluster identifier.
     61 * @ return local pointer on remote_buf descriptor.
     62 ***********************************************************************************/
     63remote_buf_t * remote_buf_alloc( cxy_t  cxy );
     64
     65/************************************************************************************
    5766 * This function initializes a remote_buf descriptor identified by the <buf_xp>
    58  * argument. It allocates memory for the data, as defined by the <size> argument,
     67 * argument. It allocates memory for the data, as defined by the <order> argument,
    5968 * and initializes the buffer as empty. It must be called by a local thread.
    60  * No memory is allocated if <size> value is 0.
     69 * The <order> value cannot be larger than 31.
    6170 ************************************************************************************
    6271 * @ buf_xp    : [in] extended pointer on buffer descriptor.
    63  * @ size      : [in] number of bytes in buffer / no memory allocated when null.
    64  * @ return  0 if success / return -1 if memory failure.
     72 * @ order     : [in] ln2( number of bytes in buffer) / must be in [0,31].
     73 * @ return  0 if success / return -1 if memory failure or illegal order.
    6574 ***********************************************************************************/
    6675error_t remote_buf_init( xptr_t   buf_xp,
    67                          uint32_t size );
     76                         uint32_t order );
    6877
    6978/************************************************************************************
    70  * This function releases memory allocated for the data buffer of a remote-buf
    71  * descriptor identified by the <buf_xp> argument.
    72  * It must be called by a local thread.
     79 * This function releases memory allocated for the data buffer of an embedded
     80 * remote-buf descriptor identified by the <buf_xp> argument, when the "data"
     81 * pointer is not NULL. It does nothing if the data buffer was not allocated.
     82 * WARNING : do NOT use this function for a dynamically allocated remote_buf.
     83 ************************************************************************************
     84 * @ buf_xp      : [in] extended pointer on buffer descriptor.
     85 ***********************************************************************************/
     86void remote_buf_release_data( xptr_t buf_xp );
     87
     88/************************************************************************************
     89 * This function releases both the memory allocated for the data buffer, and the
     90 * memory allocated for the remote_buf descriptor, for a remote-buf identified
     91 * by the <buf_xp> argument.
     92 * WARNING : do NOT use this function an embedded remote_buf.
    7393 ************************************************************************************
    7494 * @ buf_xp      : [in] extended pointer on buffer descriptor.
Note: See TracChangeset for help on using the changeset viewer.