bzr branch
http://suren.me/webbzr/alps/pcitool
277.1.1
by zilio nicolas
clean version for locks |
1 |
/**
|
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
2 |
* @file locking.h
|
277.1.1
by zilio nicolas
clean version for locks |
3 |
* @brief this file is the header file for functions that touch all locks allocated for software registers.
|
4 |
* @details for more details about implementation choice, please read the file lock.h
|
|
5 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
6 |
#ifndef _PCILIB_LOCKING_H
|
7 |
#define _PCILIB_LOCKING_H
|
|
8 |
||
9 |
#define PCILIB_MAX_LOCKS 64 /**< number of maximum locks*/ |
|
10 |
#define PCILIB_LOCKS_PER_PAGE (PCILIB_KMEM_PAGE_SIZE/PCILIB_LOCK_SIZE) /**< number of locks per page of kernel memory */ |
|
11 |
#define PCILIB_LOCK_PAGES ((PCILIB_MAX_LOCKS * PCILIB_LOCK_SIZE)/PCILIB_KMEM_PAGE_SIZE) /**< number of pages allocated for locks in kernel memory */ |
|
12 |
||
13 |
||
14 |
#include <pcilib/kmem.h> |
|
15 |
#include <pcilib/lock.h> |
|
16 |
||
307
by Suren A. Chilingaryan
Finalyze XML support and provide initial support for views (only descriptions so far) |
17 |
typedef uint32_t pcilib_lock_id_t; /**< type to represent the index of a lock in the table of locks in the kernel space*/ |
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
18 |
|
19 |
typedef struct pcilib_locking_s pcilib_locking_t; |
|
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
20 |
|
21 |
/**
|
|
22 |
* structure defining the kernel space used for locks
|
|
23 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
24 |
struct pcilib_locking_s { |
307
by Suren A. Chilingaryan
Finalyze XML support and provide initial support for views (only descriptions so far) |
25 |
pcilib_kmem_handle_t *kmem; /**< kmem used to store mutexes */ |
26 |
pcilib_lock_t *locking; /**< lock used while intializing kernel space */ |
|
27 |
// pcilib_lock_t *mmap; /**< lock used to protect mmap operation */
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
28 |
};
|
29 |
||
30 |
#ifdef __cplusplus
|
|
31 |
extern "C" { |
|
32 |
#endif
|
|
33 |
||
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
34 |
/**
|
35 |
*this function gets the kernel space for the locks : if this space have been already initialized, then the previous space is returned. If not, the space is created. this function has to be protected, in order to avoid the simultaneous creation of 2 kernel spaces. For that, we use pcilib_lock_global.
|
|
36 |
*@param[in,out] ctx - the pcilib_t structure running, getting filled with a ref to locks' kernel space
|
|
37 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
38 |
int pcilib_init_locking(pcilib_t *ctx); |
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
39 |
|
40 |
/**
|
|
41 |
*this function cleans the memory from all locks : the kernel space is freed, and locks references in pcilib_t are destroyed by setting memory to 0
|
|
42 |
*@param[in,out] ctx - the pcilib_t structure running
|
|
43 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
44 |
void pcilib_free_locking(pcilib_t *ctx); |
45 |
||
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
46 |
/**
|
47 |
* this function use flock locking mechanism on the ALPS platform device file, to make sure to not create two kernel spaces for locks
|
|
48 |
*@param[in,out] ctx - the pcilib_t structure running
|
|
49 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
50 |
int pcilib_lock_global(pcilib_t *ctx); |
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
51 |
|
52 |
/**
|
|
53 |
*function to remove the lock created by flock on the ALPS platform device file
|
|
54 |
*@param[in,out] ctx - the pcilib_t structure running
|
|
55 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
56 |
void pcilib_unlock_global(pcilib_t *ctx); |
57 |
||
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
58 |
/**
|
59 |
* this function returns the lock at the index in the kernel space equal to id
|
|
60 |
*@param[in] ctx - the pcilib_t structure running
|
|
61 |
*@param[in] id - the index of the lock
|
|
62 |
*@return the lock structure corresponding
|
|
63 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
64 |
pcilib_lock_t *pcilib_get_lock_by_id(pcilib_t *ctx, pcilib_lock_id_t id); |
65 |
||
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
66 |
/**
|
67 |
*this function verify if the lock requested exists in the kernel space. If yes, then nothing is done, else we create the lock in the kernel space. This function also gives the number of processes that may request the lock afterwards, including the one that just created it.
|
|
68 |
*@param[in] ctx - the pcilib_t structure running
|
|
69 |
*@param[in] flags - the flag defining the property of the lock
|
|
324
by Suren A. Chilingaryan
Documentation update |
70 |
*@param[in] lock_id - the identifier name for the lock
|
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
71 |
*@return the corresponding lock, or a new one if it did not exist before
|
72 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
73 |
pcilib_lock_t *pcilib_get_lock(pcilib_t *ctx, pcilib_lock_flags_t flags, const char *lock_id, ...); |
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
74 |
|
75 |
/**
|
|
76 |
*this function is to decrement the variable in a lock containing the number of processes that may access to this lock(refs)
|
|
77 |
*@param[in] ctx - the pcilib_t structure running
|
|
78 |
*@param[in] flags - the flag defining the property of the lock
|
|
79 |
*@param[in] lock - pointer to the lock we want to modify
|
|
80 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
81 |
void pcilib_return_lock(pcilib_t *ctx, pcilib_lock_flags_t flags, pcilib_lock_t *lock); |
82 |
||
305.1.5
by zilio nicolas
reviewd old tasks comments for doxygen and update |
83 |
/**
|
84 |
* this function destroy all the locks that have been created(unref the locks + set memory to 0), and so is used when we want to clean properly the kernel space. If force is set to 1, then we don't care about other processes that may request locks. If not, if there is locks that may be requested by other processes, then the operation is stopped. Of course, destroying locks that may be requested by other processes results in an undefined behaviour. Thus, it is user responsibility to issue this command with force set to 1
|
|
85 |
*@param[in,out] ctx - the pcilib_t structure running
|
|
86 |
*@param[in] force - should the operation be forced or not
|
|
87 |
* @return error code : 0 if everything was ok
|
|
88 |
*/
|
|
280
by Suren A. Chilingaryan
Integrate locking subsystem from Nicolas Zilio |
89 |
int pcilib_destroy_all_locks(pcilib_t *ctx, int force); |
90 |
||
91 |
||
92 |
#ifdef __cplusplus
|
|
93 |
}
|
|
94 |
#endif
|
|
95 |
||
96 |
#endif /* _PCILIB_LOCKING_H */ |