1/*
2 * Copyright (c) 2013, ETH Zurich.
3 * All rights reserved.
4 *
5 * This file is distributed under the terms in the attached LICENSE file.
6 * If you do not find this file, copies can be found by writing to:
7 * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
8 */
9
10#ifndef BULK_TRANSFER_POOL_H
11#define BULK_TRANSFER_POOL_H
12
13#include <bulk_transfer/bulk_transfer.h>
14
15/**
16 * internal representation of a bulk pool
17 *
18 */
19struct bulk_pool_internal {
20    struct bulk_pool pool;      ///< pointer to the public interface
21    /* internal fields */
22    struct vregion *vregion;    ///< pointer to the vregion of the pool
23    struct capref   cnode_cap;  ///< capability of the buffers cnode
24    uint32_t        refcnt;     ///< ref count for pool to channel assignments
25    void           *impl_data;  ///< pointer to impl specific data
26};
27
28
29/**
30 * returns a pointer to the pool with the given id
31 *
32 * @param   id  the id of the pool to look up
33 *
34 * @return  NULL if the pool is not present in the domain
35 */
36struct bulk_pool *bulk_pool_domain_list_get(struct bulk_pool_id *id);
37
38/**
39 * inserts a pool into the domain global bulk pool list
40 *
41 * @param   pool    the pool to insert
42 */
43errval_t bulk_pool_domain_list_insert(struct bulk_pool *pool);
44
45errval_t bulk_pool_domain_list_remove(struct bulk_pool *pool);
46
47/**
48 * compares two bulk pool ids
49 *
50 * @return  -1  if id1 is less than id2
51 *           0  if both ids are equal
52 *           1  if id1 is bigger than id2
53 */
54int8_t bulk_pool_cmp_id(struct bulk_pool_id *id1,
55                        struct bulk_pool_id *id2);
56
57/**
58 * checks if a pool already has been assigned to that channel
59 *
60 * @param pool      the bulk pool to check for assignment
61 * @param channel   the channel to check for assignment
62 *
63 * @return true:    the pool is assigned to this channel
64 *         false:   the pools has not been assigned to the channel
65 */
66uint8_t bulk_pool_is_assigned(struct bulk_pool      *pool,
67                              struct bulk_channel   *channel);
68
69/**
70 * adds a pool to a channel's pool list
71 *
72 * @param pool      the pool to assing to the channel
73 * @param channel   the channel to assign the the pool to
74 */
75errval_t bulk_pool_assign(struct bulk_pool          *pool,
76                         struct bulk_channel        *channel);
77
78/**
79 * removes the pool from the channel's pool list
80 *
81 * @param pool      the poo to remove
82 * @param channel   the channel to remove the pool from
83 */
84errval_t bulk_pool_remove(struct bulk_pool          *pool,
85                          struct bulk_channel       *channel);
86
87
88/**
89 * gets a pointer to the pool on this channel
90 *
91 * @param id        the poolid we want the pool
92 * @param channel   the channel to look for the pools
93 */
94struct bulk_pool *bulk_pool_get(struct bulk_pool_id *id,
95                                struct bulk_channel *channel);
96
97/**
98 * Does the mapping of a pool depending on the trust level. If it is not trusted,
99 * only the memory range is allocated and the vregions for the buffers created,
100 * In the trusted case, the pool is backed with the pool cap and mapped.
101 *
102 * @param pool  the pool to map
103 */
104errval_t bulk_pool_map(struct bulk_pool *pool);
105
106
107/**
108 * unmaps the entire pool and frees up the entire memory region of the pool.
109 *
110 * @param pool  the pool to unmap
111 */
112errval_t bulk_pool_unmap(struct bulk_pool *pool);
113
114
115/**
116 * initializes the buffers for a pool given the struct pool is allocated and
117 * filled with the basic information about the number of buffers in the pool.
118 *
119 * @param pool  pointer to a pool with the information
120 */
121errval_t bulk_pool_init_bufs(struct bulk_pool *pool);
122
123/**
124 * allocates the data structures for the pool.
125 *
126 * @param   pool            storage for pointer to newly allocated pool
127 * @param   buffer_count    the number of buffers in the pool
128 * @param   buffer_size     the size of a single buffer
129 * @param   id              pool id
130 */
131errval_t bulk_pool_alloc_with_id(struct bulk_pool     **pool,
132                                 size_t               buffer_count,
133                                 size_t               buffer_size,
134                                 struct bulk_pool_id id);
135
136/**
137 * allocates the data structures for the pool with new id.
138 *
139 * @param   pool            storage for pointer to newly allocated pool
140 * @param   buffer_count    the number of buffers in the pool
141 * @param   buffer_size     the size of a single buffer
142 */
143errval_t bulk_pool_alloc(struct bulk_pool     **pool,
144                         size_t               buffer_count,
145                         size_t               buffer_size);
146
147
148/**
149 * frees up the resources needed by the pool and does the
150 * deletion of the caps (if any)
151 *
152 * @param pool  the pool to dealloc
153 */
154errval_t bulk_pool_dealloc(struct bulk_pool *pool);
155
156#endif // BULK_TRANSFER_POOL_H
157
158