/alps/pcitool

To get this branch, use:
bzr branch http://suren.me/webbzr/alps/pcitool

« back to all changes in this revision

Viewing changes to pcilib/kmem.h

  • Committer: Suren A. Chilingaryan
  • Date: 2016-03-02 04:47:04 UTC
  • Revision ID: csa@suren.me-20160302044704-wncsxtf6sx0r0tps
Documentation update

Show diffs side-by-side

added added

removed removed

Lines of Context:
pcilib/kmem.h
106
106
 * This function either allocates new buffers in the kernel space or just re-uses existing buffers.
107
107
 *
108
108
 * Sometimes kernel memory is allocated for the specific use-case, for example to provide buffers for DMA engine.
109
 
 * It is possible to specify intended use using \a use parameter. 
110
 
 * The kernel memory with the specified use (i.e. \a use != 0) can be declared persistent (\a flags include 
111
 
 * PCILIB_KMEM_FLAG_PERSISTENT). Such memory will not be de-allocated on clean-up and will be maintained by 
 
109
 * It is possible to specify intended use using \p use parameter. 
 
110
 * The kernel memory with the specified use (i.e. \p use != 0) can be declared persistent (\p flags include 
 
111
 * ::PCILIB_KMEM_FLAG_PERSISTENT). Such memory will not be de-allocated on clean-up and will be maintained by 
112
112
 * the kernel module across the runs of various pcilib applications. To re-use persistent kernel memory,
113
 
 * PCILIB_KMEM_FLAG_REUSE should be set. In this case, the pcilib will either allocate new kernel memory 
114
 
 * or re-use the already allocated kernel buffers with the specified \a use. If PCILIB_KMEM_FLAG_REUSE
 
113
 * ::PCILIB_KMEM_FLAG_REUSE should be set. In this case, the pcilib will either allocate new kernel memory 
 
114
 * or re-use the already allocated kernel buffers with the specified \p use. If ::PCILIB_KMEM_FLAG_REUSE
115
115
 * is not set, but the kernel memory with the specified use is already allocated, an error will be returned.
116
116
 *
117
117
 * It is also possible to allocate persistent kernel memory which can be execlusively used by a single process.
118
 
 * The PCILIB_KMEM_FLAG_EXCLUSIVE flag have to be provided to pcilib_alloc_kernel_memory() function in this
 
118
 * The ::PCILIB_KMEM_FLAG_EXCLUSIVE flag have to be provided to pcilib_alloc_kernel_memory() function in this
119
119
 * case. Only a single process may call hold a reference to kernel memory. Before next process would be able
120
120
 * to obtain it, the process holding the reference should return it using pcilib_free_kernel_memory()
121
121
 * call. For example, DMA engine uses exclusive kernel memory to guarantee that exactly one process is 
122
122
 * controlling DMA operations.
123
123
 *
124
124
 * To clean up allocated persistent kernel memory, pcilib_free_kernel_memory() have to be called with
125
 
 * PCILIB_KMEM_FLAG_PERSISTENT flag set.
 
125
 * ::PCILIB_KMEM_FLAG_PERSISTENT flag set.
126
126
 *
127
127
 * @param[in,out] ctx           - pcilib context
128
128
 * @param[in] type              - specifies type of allocation (simple pages, DMA pages, consistent memory, etc.)
138
138
/**
139
139
 * This function either frees the allocated kernel memory or just releases some of the references.
140
140
 *
141
 
 * Only reference tracking is performed If the PCILIB_KMEM_FLAG_REUSE flag is passed to the 
 
141
 * Only reference tracking is performed If the ::PCILIB_KMEM_FLAG_REUSE flag is passed to the 
142
142
 * function. Otherwise, non-persistent memory is released when pcilib_free_kernel_memory() called. 
143
 
 * The persistent memory is released if PCILIB_KMEM_FLAG_PERSISTENT is passed in \a flags parameter 
 
143
 * The persistent memory is released if ::PCILIB_KMEM_FLAG_PERSISTENT is passed in \p flags parameter 
144
144
 * unless the hold references are preventing us from releasing this memory. The error is reported
145
 
 * in this case. The kernel memory can be freed irrespective of hold references if PCILIB_KMEM_FLAG_FORCE 
 
145
 * in this case. The kernel memory can be freed irrespective of hold references if ::PCILIB_KMEM_FLAG_FORCE 
146
146
 * flag is specified.
147
147
 *
148
148
 * There are several types of references:
149
149
 * - The hardware reference - indicates that the memory may be used by DMA engine of the device. It is set
150
 
 * if pcilib_alloc_kernel_memory() is executed with PCILIB_KMEM_FLAG_HARDWARE flag. The reference can 
 
150
 * if pcilib_alloc_kernel_memory() is executed with ::PCILIB_KMEM_FLAG_HARDWARE flag. The reference can 
151
151
 * be released if the same flag is passed to pcilib_free_kernel_memory()
152
152
 * - The software references - are obtained when the memory is reused with pcilib_alloc_kernel_memory(). 
153
153
 * They are released when corresponding pcilib_free_kernel_memory() is called. 
160
160
 * used to keep track of non-persistent memory allocated and re-used within the same application (which is
161
161
 * actually discouraged). In this case the number of pcilib_alloc_kernel_memory() should be matched by 
162
162
 * number of pcilib_free_kernel_memory() calls and only on a last call the memory will be really released.
163
 
 * Normally, all but last calls have to be accompanied by PCILIB_KMEM_FLAG_REUSE flag or the error 
 
163
 * Normally, all but last calls have to be accompanied by ::PCILIB_KMEM_FLAG_REUSE flag or the error 
164
164
 * is reported. But to keep code simpler, the pcilib will not complain until there are software references 
165
165
 * on hold. When the last software reference is released, we try actually clean up the memory and the
166
166
 * error is reported if other types of references are still present.
167
167
 * The software references may stuck if application crashes before calling pcilib_free_kernel_memory(). 
168
168
 * pcilib will prevent us from releasing the kernel memory with stuck references. Such memory can 
169
 
 * be cleaned only with PCILIB_KMEM_FLAG_FORCE flag or using  pcilib_clean_kernel_memory() call.
 
169
 * be cleaned only with ::PCILIB_KMEM_FLAG_FORCE flag or using  pcilib_clean_kernel_memory() call.
170
170
 *
171
171
 * @param[in,out] ctx           - pcilib context
172
172
 * @param[in,out] k             - kernel memory handle returned from pcilib_alloc_kernel_memory() call
176
176
 
177
177
 
178
178
/**
179
 
 * Free / dereference all kernel memory buffers associated with the specified \a use
 
179
 * Free / dereference all kernel memory buffers associated with the specified \p use
180
180
 *
181
181
 * @param[in,out] ctx           - pcilib context
182
182
 * @param[in] use               - use-number to clean