1*14b24e2bSVaishali KulkarniEcore Operating System Abstraction Layer (osal) documentation
2*14b24e2bSVaishali Kulkarni=============================================================
3*14b24e2bSVaishali Kulkarni
4*14b24e2bSVaishali KulkarniIntroduction
5*14b24e2bSVaishali Kulkarni============
6*14b24e2bSVaishali KulkarniThis document contains the osal information - functions utilized by the ecore
7*14b24e2bSVaishali Kulkarniwhich the various parties incorporating the ecore into their own sourcecode
8*14b24e2bSVaishali Kulkarnineed to implement in order for the ecore to function.
9*14b24e2bSVaishali Kulkarni
10*14b24e2bSVaishali KulkarniEverything osal should be prefixed with osal*. Structures should be prefixed by
11*14b24e2bSVaishali Kulkarnilowercase `osal_' and be lowercase themselves, while functions should be
12*14b24e2bSVaishali Kulkarniprefixed with upper case letters `OSAL_' and be uppercased.
13*14b24e2bSVaishali Kulkarni
14*14b24e2bSVaishali KulkarniNotice that some are very trivial, and can be easily replaced by a single
15*14b24e2bSVaishali Kulkarnifunction call or preprocessor macro. Also notice some are weakly-typed, or
16*14b24e2bSVaishali Kulkarniinclude values [e.g., struct types] that should probably be implemented
17*14b24e2bSVaishali Kulkarnias preprocessor macros.
18*14b24e2bSVaishali Kulkarni
19*14b24e2bSVaishali Kulkarni* - as always, there are a couple of exceptions.
20*14b24e2bSVaishali Kulkarni
21*14b24e2bSVaishali KulkarniTime related osals
22*14b24e2bSVaishali Kulkarni==================
23*14b24e2bSVaishali Kulkarni- OSAL_UDELAY(int)
24*14b24e2bSVaishali Kulkarni	The function should delay for said amount of micro-seconds.
25*14b24e2bSVaishali Kulkarni
26*14b24e2bSVaishali Kulkarni- OSAL_MSLEEP(int)
27*14b24e2bSVaishali Kulkarni	The function should sleep for said amount of mili-seconds, releasing the CPU.
28*14b24e2bSVaishali Kulkarni	(The existing of such a call in a flow demands the flow to be run from a
29*14b24e2bSVaishali Kulkarni	context supporting sleep).
30*14b24e2bSVaishali Kulkarni
31*14b24e2bSVaishali KulkarniMemory related osals
32*14b24e2bSVaishali Kulkarni====================
33*14b24e2bSVaishali Kulkarni- void* OSAL_ALLOC(struct *ecore_dev, u32 mode, u32 size)
34*14b24e2bSVaishali Kulkarni	Allocate `size' memory for said device. The mode comes from linux's GFP_*
35*14b24e2bSVaishali Kulkarni	defines [Notice this means you need to define those values, at least
36*14b24e2bSVaishali Kulkarni	KERNEL & ATOMIC even if you don't need them on your OS].
37*14b24e2bSVaishali Kulkarni	Return value should be NULL if allocation fails, and otherwise return the
38*14b24e2bSVaishali Kulkarni	pointer to allocated memory.
39*14b24e2bSVaishali Kulkarni
40*14b24e2bSVaishali Kulkarni- void* OSAL_ZALLOC(struct *ecore_dev, u32 mode, u32 size)
41*14b24e2bSVaishali Kulkarni	Like OSAL_ALLOC, only the memory [if succesfully allocated] should be set
42*14b24e2bSVaishali Kulkarni	to 0s.
43*14b24e2bSVaishali Kulkarni
44*14b24e2bSVaishali Kulkarni- void* OSAL_CALLOC(struct *ecore_dev, u32 mode, u32 num, u32 elem_size)
45*14b24e2bSVaishali Kulkarni	Like OSAL_ALLOC, only this allocates memory sufficient for `num' elements,
46*14b24e2bSVaishali Kulkarni	each of size `elem_size'.
47*14b24e2bSVaishali Kulkarni
48*14b24e2bSVaishali Kulkarni- void* OSAL_VZALLOC(struct *ecore_dev, u32 size)
49*14b24e2bSVaishali Kulkarni	Allocate `size' memory for said device, but as opposed to OSAL_ALLOC,
50*14b24e2bSVaishali Kulkarni	the allocated memory is only virtually contiguous and not necessarily
51*14b24e2bSVaishali Kulkarni	physically contiguous. Content of memory should be zeroed.
52*14b24e2bSVaishali Kulkarni	Return value should be NULL if allocation fails, and otherwise return the
53*14b24e2bSVaishali Kulkarni	pointer to allocated memory.
54*14b24e2bSVaishali Kulkarni
55*14b24e2bSVaishali Kulkarni- void OSAL_FREE(struct *ecore_dev, void* memory)
56*14b24e2bSVaishali Kulkarni	frees a memory previously dynamically allocated by OSAL_([Z|C]?)ALLOC.
57*14b24e2bSVaishali Kulkarni	Notice this should succeed even if the pointer is NULL.
58*14b24e2bSVaishali Kulkarni
59*14b24e2bSVaishali Kulkarni- void OSAL_VFREE(struct *ecore_dev, void* memory)
60*14b24e2bSVaishali Kulkarni	frees a memory previously dynamically allocated by OSAL_VZALLOC.
61*14b24e2bSVaishali Kulkarni	Notice this should succeed even if the pointer is NULL.
62*14b24e2bSVaishali Kulkarni
63*14b24e2bSVaishali Kulkarni- void OSAL_MEM_ZERO(void* memory, u32 size)
64*14b24e2bSVaishali Kulkarni	Set `size' bytes starting at the address pointed by `memory' with 0s.
65*14b24e2bSVaishali Kulkarni
66*14b24e2bSVaishali Kulkarni- void OSAL_MEMCPY(void* dst, void* src, u32 size)
67*14b24e2bSVaishali Kulkarni	Copy `size' bytes from address pointed by `src' to address pointed by `dst'.
68*14b24e2bSVaishali Kulkarni
69*14b24e2bSVaishali Kulkarni- void OSAL_MEMSET(void *s, int c, u32  size)
70*14b24e2bSVaishali Kulkarni	Set `size' bytes starting at the address pointed to by s with c.
71*14b24e2bSVaishali Kulkarni
72*14b24e2bSVaishali Kulkarni- int OSAL_MEMCMP(void *s1, void *s2, u32 n)
73*14b24e2bSVaishali Kulkarni	Comapre the first n bytes of memory areas s1 and s2.
74*14b24e2bSVaishali Kulkarni	The function returns an integer less than, equal to, or
75*14b24e2bSVaishali Kulkarni	greater than zero if the first n bytes of s1 is found, respectively,
76*14b24e2bSVaishali Kulkarni	to be less than, to match, or be greater than the first n bytes of
77*14b24e2bSVaishali Kulkarni	s2.
78*14b24e2bSVaishali Kulkarni
79*14b24e2bSVaishali Kulkarnidma_addr_t - this variable type should be defined as a variable that can contain
80*14b24e2bSVaishali Kulkarni	physical addresses. It's utilized in OSAL_DMA_* functions.
81*14b24e2bSVaishali Kulkarni
82*14b24e2bSVaishali Kulkarni- void* OSAL_DMA_ALLOC_COHERENT(struct *ecore_dev, dma_addr_t *phys, u32 size)
83*14b24e2bSVaishali Kulkarni	Allocate `size' bytes of DMA-able memory [which will later be accessed by
84*14b24e2bSVaishali Kulkarni	our HW]. The physical address will by filled in `phys' [NULL if allocation
85*14b24e2bSVaishali Kulkarni	fails], and the virtual address will return [NULL if allocation fails].
86*14b24e2bSVaishali Kulkarni
87*14b24e2bSVaishali Kulkarni- void OSAL_DMA_FREE_COHERENT(struct *ecore_dev, void* virt, dma_addr_t *phys, u32 size)
88*14b24e2bSVaishali Kulkarni	Frees previously allocated memory [via OSAL_DMA_ALLOC_COHERENT].
89*14b24e2bSVaishali Kulkarni
90*14b24e2bSVaishali KulkarniMemory Access related osals
91*14b24e2bSVaishali Kulkarni===========================
92*14b24e2bSVaishali KulkarniNotice - these do not begin with the OSAL convention.
93*14b24e2bSVaishali Kulkarni
94*14b24e2bSVaishali Kulkarni- void REG_WR(struct *ecore_hwfn, u32 addr, u32 value)
95*14b24e2bSVaishali Kulkarni- void REG_WR16(struct *ecore_hwfn, u32 addr, u16 value)
96*14b24e2bSVaishali Kulkarni	These should perform the memory write toward chip. Address is an offset
97*14b24e2bSVaishali Kulkarni	inside the Bar.
98*14b24e2bSVaishali Kulkarni
99*14b24e2bSVaishali Kulkarni- void DOORBELL(struct *ecore_hwfn, u32 addr, u32 value)
100*14b24e2bSVaishali Kulkarni	This should perform memory write toward chip. Addrees is an offset
101*14b24e2bSVaishali Kulkarni	inside the doorbell bar.
102*14b24e2bSVaishali Kulkarni
103*14b24e2bSVaishali Kulkarni- void DIRECT_REG_WR(struct *ecore_hwfn, u32 addr, u32 value)
104*14b24e2bSVaishali Kulkarni	Perform a memory write toward chip. Address is absolute [i.e., includes
105*14b24e2bSVaishali Kulkarni	bar offset in memory].
106*14b24e2bSVaishali Kulkarni	Notice most ecore clients don't need the ecore_hwfn; Notice that unless
107*14b24e2bSVaishali Kulkarni	ECORE_CONFIG_DIRECT_HWFN is set during compilation, this function will
108*14b24e2bSVaishali Kulkarni	be called sometimes when the ecore_hwfn is set to be OSAL_NULL.
109*14b24e2bSVaishali Kulkarni
110*14b24e2bSVaishali Kulkarni- void DIRECT_REG_RD(struct *ecore_hwfn, u32 addr)
111*14b24e2bSVaishali Kulkarni	Perform a memory read from chip. Address is absolute.
112*14b24e2bSVaishali Kulkarni	[Same comment as for DIRECT_REG_WR]
113*14b24e2bSVaishali Kulkarni
114*14b24e2bSVaishali Kulkarni- u32 REG_RD(struct *ecore_hwfn, u32 addr)
115*14b24e2bSVaishali Kulkarni	This should perform the memory read from chip. Address is an offset
116*14b24e2bSVaishali Kulkarni	inside the Bar.
117*14b24e2bSVaishali Kulkarni
118*14b24e2bSVaishali KulkarniSynchronization related osals
119*14b24e2bSVaishali Kulkarni=============================
120*14b24e2bSVaishali KulkarniFor most upper-layer driver there's no need to allocate memory for lock primitives -
121*14b24e2bSVaishali Kulkarnifor such upper-layer drivers, it should suffice to give an empty implementations
122*14b24e2bSVaishali Kulkarnito - MUTEX_ALLOC(), MUTEX_DEALLOC(), SPIN_LOCK_ALLOC(), SPIN_LOCK_DEALLOC().
123*14b24e2bSVaishali KulkarniIn case this is actually needed, the ecore should also be compile with the
124*14b24e2bSVaishali KulkarniCONFIG_ECORE_LOCK_ALLOC flag [since sometimes flows diverge a bit].
125*14b24e2bSVaishali Kulkarni
126*14b24e2bSVaishali Kulkarniosal_spinlock_t - a type of variable [struct] which is used as a spinlock in the
127*14b24e2bSVaishali Kulkarni		  various OSAL_SPIN_* calls. Spinlock assumes locking is blocking
128*14b24e2bSVaishali Kulkarni		  and interrupt disabling on all CPUs, protecting an exclusive
129*14b24e2bSVaishali Kulkarni		  critical section.
130*14b24e2bSVaishali Kulkarni
131*14b24e2bSVaishali Kulkarniosal_mutex_t - a type of variable [struct] which is used as a mutex in the
132*14b24e2bSVaishali Kulkarni	       various OSAL_MUTEX_* calls. Mutices assume locking is sleeping,
133*14b24e2bSVaishali Kulkarni	       protecting an exclusive critical section.
134*14b24e2bSVaishali Kulkarni
135*14b24e2bSVaishali Kulkarni- void OSAL_MUTEX_ALLOC(struct ecore_hwfn*, osal_mutex*)
136*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_LOCK_ALLOC(struct ecore_hwfn*, osal_spinlock_t*)
137*14b24e2bSVaishali Kulkarni	Used to allocate [if upper-layer needs to] the spinlock/mutex.
138*14b24e2bSVaishali Kulkarni	NOTICE - counter-intuitively ecore assuumes this always succeeds.
139*14b24e2bSVaishali Kulkarni	But upper-layer can assume this will only be called by rescource alloc &
140*14b24e2bSVaishali Kulkarni	init schemes [and not dynamically], and thus prepare the memory before-hand.
141*14b24e2bSVaishali Kulkarni
142*14b24e2bSVaishali Kulkarni- void OSAL_MUTEX_DEALLOC(osal_mutex*)
143*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_LOCK_DEALLOC(osal_spinlock_t*)
144*14b24e2bSVaishali Kulkarni	Used to free any previously allocated memory of the spinlock/mutex.
145*14b24e2bSVaishali Kulkarni
146*14b24e2bSVaishali Kulkarni- void OSAL_MUTEX_INIT(osal_mutex_t*)
147*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_LOCK_INIT(osal_spinlock_t*)
148*14b24e2bSVaishali Kulkarni	Initializes the given spinlock/mutex.
149*14b24e2bSVaishali Kulkarni
150*14b24e2bSVaishali Kulkarni- void OSAL_MUTEX_ACQUIRE(osal_mutex_t*)
151*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_LOCK(osal_spinlock_t*)
152*14b24e2bSVaishali Kulkarni	Wait until spinlock/mutex is exclusively held - blocking for spinlocks,
153*14b24e2bSVaishali Kulkarni	sleeping for mutices.
154*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_LOCK_IRQSAVE(osal_spinlock_t*, flags)
155*14b24e2bSVaishali Kulkarni	Wait until spinlock/mutex is exclusively held - blocking for spinlocks,
156*14b24e2bSVaishali Kulkarni	sleeping for mutices. Use the type of spinlock that also syncronizes
157*14b24e2bSVaishali Kulkarni	with irqs. Relevant only for some OSs, in most cases an implementation
158*14b24e2bSVaishali Kulkarni	that is identical to OSAL_SPIN_LOCK will suffice.
159*14b24e2bSVaishali Kulkarni
160*14b24e2bSVaishali Kulkarni- OSAL_MUTEX_RELEASE(osal_mutex_t*)
161*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_UNLOCK(osal_spinlock_t*)
162*14b24e2bSVaishali Kulkarni	Release a held spinlock/mutex [no logic necessary for checking whether
163*14b24e2bSVaishali Kulkarni	it's already locked; that's the caller's responsibility].
164*14b24e2bSVaishali Kulkarni- void OSAL_SPIN_UNLOCK_IRQSAVE(osal_spinlock_t*, flags)
165*14b24e2bSVaishali Kulkarni	Release a held spinlock/mutex [no logic necessary for checking whether
166*14b24e2bSVaishali Kulkarni	it's already locked; that's the caller's responsibility]. Should be
167*14b24e2bSVaishali Kulkarni	called on a lock that was taken using OSAL_SPIN_LOCK_IRQSAVE.
168*14b24e2bSVaishali Kulkarni	Relevant only for some OSs, in most cases an implementation
169*14b24e2bSVaishali Kulkarni	that is identical to OSAL_SPIN_LOCK will suffice.
170*14b24e2bSVaishali Kulkarni
171*14b24e2bSVaishali Kulkarniosal_dpc_t - a variable representing a non-sleepable context, used by
172*14b24e2bSVaishali Kulkarni	     bcm_osal_dpc_* calls.
173*14b24e2bSVaishali Kulkarni
174*14b24e2bSVaishali Kulkarni- osal_dpc_t OSAL_DPC_ALLOC(struct ecore_hwfn)
175*14b24e2bSVaishali Kulkarni	Allocates the dpc.
176*14b24e2bSVaishali Kulkarni
177*14b24e2bSVaishali Kulkarni- void OSAL_DPC_INIT(osal_dpc_t dpc, struct ecore_hwfn)
178*14b24e2bSVaishali Kulkarni	Initializes the dpc.
179*14b24e2bSVaishali Kulkarni
180*14b24e2bSVaishali Kulkarni- void OSAL_DPC_SYNC(struct ecore_hwfn *p_hwfn)
181*14b24e2bSVaishali Kulkarni	Make sure all slowpath OS dpc's are synced/flushed.
182*14b24e2bSVaishali Kulkarni
183*14b24e2bSVaishali Kulkarni- void OSAL_POLL_MODE_DPC(struct ecore_hnfn*)
184*14b24e2bSVaishali Kulkarni	Polls ecore_int_sp_dpc during blocking ramrods if needed.  Used when
185*14b24e2bSVaishali Kulkarni	no other thread will service the sp dpc, such as with single threaded
186*14b24e2bSVaishali Kulkarni	systems.
187*14b24e2bSVaishali Kulkarni
188*14b24e2bSVaishali KulkarniNotice that the DPC interface from ecore is probably the worst [or at least
189*14b24e2bSVaishali Kulkarnione-of the worst] implementation in the API - this API does not determine
190*14b24e2bSVaishali Kulkarniwhen the DPC will run and what will run in its context.
191*14b24e2bSVaishali KulkarniAt the moment, the only DPC used by the ecore is sp_dpc in ecore_int.c, and
192*14b24e2bSVaishali Kulkarnithe missing logic here is that it should somehow be connected by the upper
193*14b24e2bSVaishali Kulkarnilayer to the slowpath interrupt ISR [either directly or indirectly], and that
194*14b24e2bSVaishali Kulkarniit should run [or call in some manner] `ecore_int_sp_dpc'.
195*14b24e2bSVaishali Kulkarni
196*14b24e2bSVaishali KulkarniLinked List osals
197*14b24e2bSVaishali Kulkarni=================
198*14b24e2bSVaishali Kulkarniosal_list_t - this struct is the linked-list root, i.e., from it the linked
199*14b24e2bSVaishali Kulkarni	      list can be travelled; Most OSAL_LIST_* functions will require
200*14b24e2bSVaishali Kulkarni	      such an anchor to be passed.
201*14b24e2bSVaishali Kulkarniosal_list_entry_t - each struct which will be added to a list should contain
202*14b24e2bSVaishali Kulkarni		    such a field.
203*14b24e2bSVaishali Kulkarni
204*14b24e2bSVaishali Kulkarni- void OSAL_LIST_INIT(osal_list_t*)
205*14b24e2bSVaishali Kulkarni	Initializes the list passed to the function [so it can be utilized
206*14b24e2bSVaishali Kulkarni	later on by other OSAL_LIST_* calls].
207*14b24e2bSVaishali Kulkarni
208*14b24e2bSVaishali Kulkarni- void OSAL_LIST_PUSH_HEAD(osal_list_entry_t *entry, osal_list_t *list)
209*14b24e2bSVaishali Kulkarni- void OSAL_LIST_PUSH_TAIL(osal_list_entry_t *entry, osal_list_t *list)
210*14b24e2bSVaishali Kulkarni	Add `entry' to the beginning/end of a list anchored by `list'.
211*14b24e2bSVaishali Kulkarni
212*14b24e2bSVaishali Kulkarni- type* OSAL_LIST_FIRST_ENTRY(osal_list_t*, type, name_of_list_field)
213*14b24e2bSVaishali Kulkarni	[Notice - this is weakly typed and should probably only be
214*14b24e2bSVaishali Kulkarni	implemented as a macro]
215*14b24e2bSVaishali Kulkarni	Assume the first entry in the list is of type `type', and that
216*14b24e2bSVaishali Kulkarni	the osal_list_t entry inside it is named `name_of_list_field'.
217*14b24e2bSVaishali Kulkarni	Return a pointer to that entry.
218*14b24e2bSVaishali Kulkarni
219*14b24e2bSVaishali Kulkarni	E.g., a short example of list functions uses:
220*14b24e2bSVaishali Kulkarni
221*14b24e2bSVaishali Kulkarni	struct foo {
222*14b24e2bSVaishali Kulkarni		osal_struct_t list_head;
223*14b24e2bSVaishali Kulkarni		int x;
224*14b24e2bSVaishali Kulkarni	};
225*14b24e2bSVaishali Kulkarni	osal_struct_list_t root;
226*14b24e2bSVaishali Kulkarni	struct foo foo1, *tmp_foo;
227*14b24e2bSVaishali Kulkarni
228*14b24e2bSVaishali Kulkarni	OSAL_LIST_INIT(&root)
229*14b24e2bSVaishali Kulkarni	foo1.x = 10;
230*14b24e2bSVaishali Kulkarni	OSAL_LIST_PUSH_HEAD(&foo1.head, &root);
231*14b24e2bSVaishali Kulkarni	tmp_foo = OSAL_LIST_FIRST_ENTRY(&root, struct foo, list_head)
232*14b24e2bSVaishali Kulkarni	/* tmp_foo now points to foo1 */
233*14b24e2bSVaishali Kulkarni
234*14b24e2bSVaishali Kulkarni- void OSAL_LIST_REMOVE_ENTRY(osal_list_entry_t *entry, osal_list_t *list)
235*14b24e2bSVaishali Kulkarni	Removes `entry' from `list' [Notice no need to check that entry is
236*14b24e2bSVaishali Kulkarni	part of list; That's the caller's responsiblity]
237*14b24e2bSVaishali Kulkarni
238*14b24e2bSVaishali Kulkarni- bool OSAL_LIST_IS_EMPTY(osal_list_t*)
239*14b24e2bSVaishali Kulkarni	return true iff the list passed to the function contains at least one
240*14b24e2bSVaishali Kulkarni	element.
241*14b24e2bSVaishali Kulkarni
242*14b24e2bSVaishali Kulkarni- void OSAL_LIST_FOR_EACH_ENTRY(type *entry, osal_list_t* list,
243*14b24e2bSVaishali Kulkarni				type, name_of_list_field)
244*14b24e2bSVaishali Kulkarni- void OSAL_LIST_FOR_EACH_ENTRY_SAFE(type *entry, type *tmp_entry,
245*14b24e2bSVaishali Kulkarni				     osal_list_t* list,
246*14b24e2bSVaishali Kulkarni				     type, name_of_list_field)
247*14b24e2bSVaishali Kulkarni	[This is a loop macro, which opens a new statement block and should
248*14b24e2bSVaishali Kulkarni	 probably be implemented as a preprocessor macro]
249*14b24e2bSVaishali Kulkarni	In every iteration of this for-loop `entry' will be filled with the
250*14b24e2bSVaishali Kulkarni	subsequent entry from the list anchored at `list'. The type of the
251*14b24e2bSVaishali Kulkarni	elements of the list and the name of the osal_list_entry_t fields
252*14b24e2bSVaishali Kulkarni	they contain should be explicitly stated [as is the case in
253*14b24e2bSVaishali Kulkarni	OSAL_LIST_FIRST_ENTRY].
254*14b24e2bSVaishali Kulkarni	The 'SAFE' variant requires an additional temporary variable which
255*14b24e2bSVaishali Kulkarni	points to the same type as `entry' (`tmp_entry'), and is safe in the
256*14b24e2bSVaishali Kulkarni	sense that `entry' can be removed from the list and the iteration
257*14b24e2bSVaishali Kulkarni	logic should not break.
258*14b24e2bSVaishali Kulkarni	If breaking from the loop one can assume `tmp_entry' would point to
259*14b24e2bSVaishali Kulkarni	the element it pointed to while breaking. But no assumption can be
260*14b24e2bSVaishali Kulkarni	made on its value assuming the iteration runs on all list elements.
261*14b24e2bSVaishali Kulkarni
262*14b24e2bSVaishali Kulkarni - void OSAL_LIST_INSERT_ENTRY_BEFORE(type *new_entry, type *entry,
263*14b24e2bSVaishali Kulkarni                                                            osal_list_t* list)
264*14b24e2bSVaishali Kulkarni   Insert a new entry before the specified entry in the list,
265*14b24e2bSVaishali Kulkarni   or insert at head of list if specified entry is 0.
266*14b24e2bSVaishali Kulkarni
267*14b24e2bSVaishali Kulkarni- void OSAL_LIST_INSERT_ENTRY_AFTER(type *new_entry, type *entry,
268*14b24e2bSVaishali Kulkarni                                                            osal_list_t* list)
269*14b24e2bSVaishali Kulkarni   Insert a new entry after the specified entry in the list,
270*14b24e2bSVaishali Kulkarni   or insert at tail of list if specified entry is 0.
271*14b24e2bSVaishali Kulkarni
272*14b24e2bSVaishali Kulkarni- void OSAL_LIST_SPLICE_INIT(osal_list_t* new_list, osal_list_t* list)
273*14b24e2bSVaishali Kulkarni   Update new_list by splicing list to the head of new_list.
274*14b24e2bSVaishali Kulkarni
275*14b24e2bSVaishali Kulkarni- void OSAL_LIST_SPLICE_TAIL_INIT(osal_list_t* new_list, osal_list_t* list)
276*14b24e2bSVaishali Kulkarni   Update new_list by splicing list to the tail of new_list.
277*14b24e2bSVaishali Kulkarni
278*14b24e2bSVaishali KulkarniPCI access osals
279*14b24e2bSVaishali Kulkarni================
280*14b24e2bSVaishali Kulkarni- void OSAL_PCI_READ_CONFIG_BYTE(struct *ecore_dev, u32 address, u8 *dst)
281*14b24e2bSVaishali Kulkarni- void OSAL_PCI_READ_CONFIG_WORD(struct *ecore_dev, u32 address, u16 *dst)
282*14b24e2bSVaishali Kulkarni- void OSAL_PCI_READ_CONFIG_DWORD(struct *ecore_dev, u32 address, u32 *dst)
283*14b24e2bSVaishali Kulkarni	Read the appropraite data size and fill in `dst' from offset
284*14b24e2bSVaishali Kulkarni	`address' in the device's configuration space.
285*14b24e2bSVaishali Kulkarni- void OSAL_PCI_WRITE_CONFIG_WORD(struct *ecore_dev, u32 address, u16 val)
286*14b24e2bSVaishali Kulkarni	Write the given value at the offset `address' in the device's
287*14b24e2bSVaishali Kulkarni	configuration space.
288*14b24e2bSVaishali Kulkarni- int OSAL_PCI_FIND_CAPABILITY(struct *ecore_dev, u16 pcie_id)
289*14b24e2bSVaishali Kulkarni	Returns the offset in the PCI configuration space of the PCIe capability
290*14b24e2bSVaishali Kulkarni	`pcie_id', or 0 if no such if capability is found.
291*14b24e2bSVaishali Kulkarni- int OSAL_PCI_FIND_EXT_CAPABILITY(struct *ecore_dev, u16 pcie_id)
292*14b24e2bSVaishali Kulkarni	Returns the offset in the PCI configuration space of the PCIe extended
293*14b24e2bSVaishali Kulkarni	capability `pcie_id', or 0 if no such if capability is found.
294*14b24e2bSVaishali Kulkarni- u32 OSAL_BAR_SIZE(struct *ecore_dev, u8 bar_id)
295*14b24e2bSVaishali Kulkarni	Returns the PCI bar size of the bar specified by `bar_id' - id 0 refers
296*14b24e2bSVaishali Kulkarni	to the regview bar and id 1 to the doorbell bar.
297*14b24e2bSVaishali Kulkarni
298*14b24e2bSVaishali KulkarniMemory Barriers
299*14b24e2bSVaishali Kulkarni===============
300*14b24e2bSVaishali Kulkarni- void OSAL_MMIOWB(strcut *ecore_dev)
301*14b24e2bSVaishali Kulkarni- void OSAL_BARRIER(struct *ecore_dev)
302*14b24e2bSVaishali Kulkarni- void OSAL_SMP_RMB(struct *ecore_dev)
303*14b24e2bSVaishali Kulkarni- void OSAL_SMP_WMB(struct *ecore_dev)
304*14b24e2bSVaishali Kulkarni- void OSAL_RMB(struct *ecore_dev)
305*14b24e2bSVaishali Kulkarni- void OSAL_WMB(struct *ecore_dev)
306*14b24e2bSVaishali Kulkarni
307*14b24e2bSVaishali KulkarniMemory barriers mostly follow the linux's definition of memory barriers,
308*14b24e2bSVaishali Kulkarnias can be found in the linux kernel under `Documentation/memory-barriers.txt'.
309*14b24e2bSVaishali KulkarniIt's possible that certain Operating systems will not require all of said
310*14b24e2bSVaishali Kulkarnimemory barriers, e.g., if there's no need to support weak-memory ordered
311*14b24e2bSVaishali Kulkarnisystem with the OS; In such a case, they should implement the barriers as
312*14b24e2bSVaishali Kulkarniempty functions.
313*14b24e2bSVaishali KulkarniAlso notice that on most implementations the ecore_dev pointer isn't needed for
314*14b24e2bSVaishali Kulkarnithe barrier implementation.
315*14b24e2bSVaishali Kulkarni
316*14b24e2bSVaishali Kulkarni- void OSAL_DMA_SYNC(struct *ecore_dev, void* addr, u32 size, bool is_post)
317*14b24e2bSVaishali Kulkarni	Used in upper-layer drivers that need to sync memory and caches
318*14b24e2bSVaishali Kulkarni	surrounding a dma transaction; This will be called with
319*14b24e2bSVaishali Kulkarni	'is_post == false' prior to the DMA transaction, and 'is_post == true'
320*14b24e2bSVaishali Kulkarni	following it.
321*14b24e2bSVaishali Kulkarni	`addr' will be the physical address of the source buffer.
322*14b24e2bSVaishali Kulkarni
323*14b24e2bSVaishali KulkarniBit operations
324*14b24e2bSVaishali Kulkarni==============
325*14b24e2bSVaishali Kulkarni- void OSAL_SET_BIT(u8 bit, unsigned long *bitmap)
326*14b24e2bSVaishali Kulkarni	Set a bit in a bitmap; Logically *bitmap |= (1ULL << bit)
327*14b24e2bSVaishali Kulkarni
328*14b24e2bSVaishali Kulkarni- void OSAL_CLEAR_BIT(u8 bit, unsigned long *bitmap)
329*14b24e2bSVaishali Kulkarni	Clears a bit in a bitmap; Logically *bitmap &= ~(1ULL << bit)
330*14b24e2bSVaishali Kulkarni
331*14b24e2bSVaishali Kulkarni- bool OSAL_TEST_BIT(u8 bit, unsigned long *bitmap)
332*14b24e2bSVaishali Kulkarni	Tests whether a bit is set in a bitmap.
333*14b24e2bSVaishali Kulkarni	Logically !!(*bitmap & (1ULL << bit))
334*14b24e2bSVaishali Kulkarni
335*14b24e2bSVaishali Kulkarni- bool OSAL_TEST_AND_CLEAR_BIT(u8 bit, unsigned long *bitmap)
336*14b24e2bSVaishali Kulkarni	Tests whether a bit is set in a bitmap and clears it.
337*14b24e2bSVaishali Kulkarni	Logically returns !!(*bitmap & (1ULL << bit)) and then performs
338*14b24e2bSVaishali Kulkarni	*bitmap &= ~(1ULL << bit)
339*14b24e2bSVaishali Kulkarni
340*14b24e2bSVaishali Kulkarni- bool OSAL_TEST_AND_FLIP_BIT(u8 bit, unsigned long *bitmap)
341*14b24e2bSVaishali Kulkarni	Tests whether a bit is set in a bitmap and flips it.
342*14b24e2bSVaishali Kulkarni	Logically returns !!(*bitmap & (1ULL << bit)) and then performs
343*14b24e2bSVaishali Kulkarni	*bitmap ^= (1ULL << bit)
344*14b24e2bSVaishali Kulkarni
345*14b24e2bSVaishali Kulkarni- u8 OSAL_FIND_FIRST_ZERO_BIT(unsigned long *bitmap, u8 length)
346*14b24e2bSVaishali Kulkarni	Returns the bit-index of the first non-set bit in a bitmap of
347*14b24e2bSVaishali Kulkarni	length `length'. Logically, returns min bit s.t.
348*14b24e2bSVaishali Kulkarni	(bit < length) && !(*bitmap & (1ULL << bit))
349*14b24e2bSVaishali Kulkarni
350*14b24e2bSVaishali Kulkarni- u8 OSAL_FIND_FIRST_BIT(unsigned long *bitmap, u8 length)
351*14b24e2bSVaishali Kulkarni        Returns the bit-index of the first non-set bit in a bitmap of
352*14b24e2bSVaishali Kulkarni        length `length'. Logically, returns min bit s.t.
353*14b24e2bSVaishali Kulkarni        (bit < length) && (*bitmap & (1ULL << bit)).
354*14b24e2bSVaishali Kulkarni	In case no bit is set, should return length.
355*14b24e2bSVaishali Kulkarni
356*14b24e2bSVaishali Kulkarni- int OSAL_BITMAP_WEIGHT(u32 *bitmap, u32 nbits)
357*14b24e2bSVaishali Kulkarni	Returns the Hamming weight (number of set bits) in the bitmap.
358*14b24e2bSVaishali Kulkarni
359*14b24e2bSVaishali KulkarniEndianess
360*14b24e2bSVaishali Kulkarni=========
361*14b24e2bSVaishali KulkarniOSAL_BE32 - a variable representing a 32-bit data in BE format.
362*14b24e2bSVaishali Kulkarni- __be32 OSAL_CPU_TO_BE32(u32 val)
363*14b24e2bSVaishali Kulkarni	convert a u32 val into big-endian format.
364*14b24e2bSVaishali Kulkarni
365*14b24e2bSVaishali Kulkarni- __be64 OSAL_CPU_TO_BE64(u64 val)
366*14b24e2bSVaishali Kulkarni	convert a u64 val into big-endian format
367*14b24e2bSVaishali Kulkarni
368*14b24e2bSVaishali Kulkarni- u32 OSAL_BE32_TO_CPU(u32 val)
369*14b24e2bSVaishali Kulkarni	convert a 32-bit value in big-endian format into current architecture.
370*14b24e2bSVaishali Kulkarni
371*14b24e2bSVaishali Kulkarni- __be16 OSAL_CPU_TO_BE16(u16 val)
372*14b24e2bSVaishali Kulkarni	convert a u16 val into big-endian format.
373*14b24e2bSVaishali Kulkarni
374*14b24e2bSVaishali Kulkarni- u16 OSAL_BE16_TO_CPU(u16 val)
375*14b24e2bSVaishali Kulkarni	convert a 16-bit value in big-endian format into current architecture.
376*14b24e2bSVaishali Kulkarni
377*14b24e2bSVaishali Kulkarni- u32 OSAL_CPU_TO_LE32(u32 val)
378*14b24e2bSVaishali Kulkarni	convert a 32-bit value from native byte ordering to little endian format.
379*14b24e2bSVaishali Kulkarni
380*14b24e2bSVaishali Kulkarni- u16 OSAL_CPU_TO_LE16(u16 val)
381*14b24e2bSVaishali Kulkarni	convert a 16-bit value from native byte ordering to little endian format.
382*14b24e2bSVaishali Kulkarni
383*14b24e2bSVaishali Kulkarni- u32 OSAL_LE32_TO_CPU(u32 val)
384*14b24e2bSVaishali Kulkarni	convert a 32-bit little endian value to native byte ordering.
385*14b24e2bSVaishali Kulkarni
386*14b24e2bSVaishali Kulkarni- u16 OSAL_LE16_TO_CPU(u32 val)
387*14b24e2bSVaishali Kulkarni	convert a 16-bit little endian value to native byte ordering.
388*14b24e2bSVaishali Kulkarni
389*14b24e2bSVaishali KulkarniPhysical link
390*14b24e2bSVaishali Kulkarni=============
391*14b24e2bSVaishali Kulkarni- void OSAL_LINK_UPDATE(struct ecore_hwfn*)
392*14b24e2bSVaishali Kulkarni	ecore uses this callback to inform upper-layer driver that a link
393*14b24e2bSVaishali Kulkarni	change has been informed by the MFW, and the link state is parsed
394*14b24e2bSVaishali Kulkarni	inside the hwfn->mcp_info->link_output.
395*14b24e2bSVaishali Kulkarni	Notice this is called from non-sleepable context, so it's possible
396*14b24e2bSVaishali Kulkarni	upper layer driver will have to schedule in its implementation to
397*14b24e2bSVaishali Kulkarni	process the change in some other context.
398*14b24e2bSVaishali Kulkarni
399*14b24e2bSVaishali KulkarniSingle Root IOV
400*14b24e2bSVaishali Kulkarni===============
401*14b24e2bSVaishali Kulkarni- ? OSAL_VF_SEND_MSG2PF(struct *ecore_dev, u8* done, union vfpf_tlvs *msg,
402*14b24e2bSVaishali Kulkarni			union pfvf_tlvs *reply_addr, u32 msg_size,
403*14b24e2bSVaishali Kulkarni			u32 reply_size)
404*14b24e2bSVaishali Kulkarni	This should be implemented by drivers utilizing a SW channel
405*14b24e2bSVaishali Kulkarni	[as opposed to the ecore hw_channel] for sending messages from VF
406*14b24e2bSVaishali Kulkarni	to PF. This should send a buffer pointed by `msg' of length `msg_size'
407*14b24e2bSVaishali Kulkarni	to the PF, where the PF's answer should be written to `reply_addr'
408*14b24e2bSVaishali Kulkarni	of maximum size `reply_size'. Writing to `done' should signal the
409*14b24e2bSVaishali Kulkarni	transaction is complete.
410*14b24e2bSVaishali Kulkarni
411*14b24e2bSVaishali Kulkarni- int OSAL_PF_VF_MSG(struct ecore_hwfn*, u8 relative_vfid)
412*14b24e2bSVaishali Kulkarni	This should be implemented by drivers utilizing the HW channel
413*14b24e2bSVaishali Kulkarni	for sending messages from VF to PF. This is called on the PF by
414*14b24e2bSVaishali Kulkarni	ecore on the EQ-handling context to signal to upper-layer that
415*14b24e2bSVaishali Kulkarni	the vf with the relative vfid has sent a message, and allow the
416*14b24e2bSVaishali Kulkarni	upper-layer to handle the request. Should return 0 on success,
417*14b24e2bSVaishali Kulkarni	non-zero otherwise.
418*14b24e2bSVaishali Kulkarni
419*14b24e2bSVaishali Kulkarni- void OSAL_PF_VF_MALICIOUS(struct ecore_hwfn*, u8 relative_vfid)
420*14b24e2bSVaishali Kulkarni	This indicates to ecore-client that the specific VF is now considered
421*14b24e2bSVaishali Kulkarni	malicious by FW. Exact implication may vary [I.e., it's possible that
422*14b24e2bSVaishali Kulkarni	the hw-channel is still operational or it might be disabled, depending
423*14b24e2bSVaishali Kulkarni	on the exact nature of the vf maliciousness].
424*14b24e2bSVaishali Kulkarni
425*14b24e2bSVaishali Kulkarni- enum _ecore_status OSAL_IOV_CHK_UCAST(struct *ecore_hwfn,
426*14b24e2bSVaishali Kulkarni					int vfid,
427*14b24e2bSVaishali Kulkarni					struct ecore_filter_ucast *params)
428*14b24e2bSVaishali Kulkarni	Called on the PF whenever the VF requests to configure a unicast
429*14b24e2bSVaishali Kulkarni	filter, to allow the upper layer to decide whether to allow the
430*14b24e2bSVaishali Kulkarni	unicast configuration or not. Should return ECORE_SUCCESS if
431*14b24e2bSVaishali Kulkarni	configuration is allowed, ECORE_EXISTS if it's already configured
432*14b24e2bSVaishali Kulkarni	and ECORE_INVAL if its forbidden.
433*14b24e2bSVaishali Kulkarni
434*14b24e2bSVaishali Kulkarni- enum _ecore_status
435*14b24e2bSVaishali Kulkarni  OSAL_IOV_PRE_START_VPORT(struct *ecore_hwfn,
436*14b24e2bSVaishali Kulkarni			   int relative_vf_id,
437*14b24e2bSVaishali Kulkarni			   struct ecore_sp_vport_start_params *params)
438*14b24e2bSVaishali Kulkarni	Called on the PF before starting a VF's vport, to check the
439*14b24e2bSVaishali Kulkarni	OS-specific setting for that vport.
440*14b24e2bSVaishali Kulkarni
441*14b24e2bSVaishali Kulkarni- void OSAL_IOV_POST_START_VPORT(struct *ecore_hwfn,
442*14b24e2bSVaishali Kulkarni				 int relative_vf_id,
443*14b24e2bSVaishali Kulkarni				 u8 vport_id,
444*14b24e2bSVaishali Kulkarni				 u16 opaque_fid)
445*14b24e2bSVaishali Kulkarni	Called on the PF after succesfully starting a VF's vport,
446*14b24e2bSVaishali Kulkarni	to allow the upper layer the chance of doing some additional
447*14b24e2bSVaishali Kulkarni	OS-specific work.
448*14b24e2bSVaishali Kulkarni
449*14b24e2bSVaishali Kulkarni- enum _ecore_status_t
450*14b24e2bSVaishali Kulkarni  OSAL_IOV_VF_VPORT_UPDATE(struct *ecore_hwfn, u8 relative_vfid,
451*14b24e2bSVaishali Kulkarni			   struct *ecore_sp_vport_update_params,
452*14b24e2bSVaishali Kulkarni			   u16 *p_tlvs_mask)
453*14b24e2bSVaishali Kulkarni 	Called on PF side to allow upper-client to manipulate the configuration
454*14b24e2bSVaishali Kulkarni        of a vport update request by VF.
455*14b24e2bSVaishali Kulkarni        `p_tlv_mask' is a bit mask of ECORE_IOV_VP_UPDATE_* values, and it's
456*14b24e2bSVaishali Kulkarni        the ecore-client responsibility to clear bits which are NOT to be
457*14b24e2bSVaishali Kulkarni	configured.
458*14b24e2bSVaishali Kulkarni	If the ecore-client wants to fail the configuaration altogether, it
459*14b24e2bSVaishali Kulkarni	should return a value other than ECORE_SUCCESS.
460*14b24e2bSVaishali Kulkarni
461*14b24e2bSVaishali Kulkarni- void OSAL_IOV_VF_VPORT_STOP(struct ecore_hwfn *p_hwfn,
462*14b24e2bSVaishali Kulkarni			       struct ecore_vf_info *vf)
463*14b24e2bSVaishali Kulkarni 	Called on PF side to allow upper-client to to execute required operations
464*14b24e2bSVaishali Kulkarni        before closing vport.
465*14b24e2bSVaishali Kulkarni
466*14b24e2bSVaishali Kulkarni- void OSAL_VF_FLR_UPDATE(struct *ecore_hwfn)
467*14b24e2bSVaishali Kulkarni	Called on PF side to indicate MFW signaled some of the PF's
468*14b24e2bSVaishali Kulkarni	vfs were Function Level Resetted. When this is called,
469*14b24e2bSVaishali Kulkarni	pending_flr field in the PF's iov information should be set
470*14b24e2bSVaishali Kulkarni	to be a bitmask of all relative VFIDs that need FLR.
471*14b24e2bSVaishali Kulkarni
472*14b24e2bSVaishali Kulkarni- void OSAL_IOV_VF_CLEANUP(struct *ecore_hwfn, u8 relative_vfid)
473*14b24e2bSVaishali Kulkarni	Called on PF side to indicate that VF has been cleaned, to allow
474*14b24e2bSVaishali Kulkarni	ecore-client the change of cleaning any database it had for that vf.
475*14b24e2bSVaishali Kulkarni
476*14b24e2bSVaishali Kulkarni- void OSAL_VF_FILL_ACQUIRE_RESC_REQ(struct ecore_hwfn *p_hwfn,
477*14b24e2bSVaishali Kulkarni                                     struct vf_pf_resc_request *p_resc_req,
478*14b24e2bSVaishali Kulkarni				     struct ecore_vf_acquire_sw_info *p_sw_info)
479*14b24e2bSVaishali Kulkarni        Called on the VF before sending acquire messgae to the PF,
480*14b24e2bSVaishali Kulkarni        to allow the upper layer to fill the num of requested resources.
481*14b24e2bSVaishali Kulkarni
482*14b24e2bSVaishali Kulkarni- enum _ecore_status_t
483*14b24e2bSVaishali Kulkarni  OSAL_VF_UPDATE_ACQUIRE_RESC_RESP(struct ecore_hwfn *p_hwfn,
484*14b24e2bSVaishali Kulkarni                                   struct pf_vf_resc *p_resc_resp)
485*14b24e2bSVaishali Kulkarni        Called on the VF after acquire response has recieved to update
486*14b24e2bSVaishali Kulkarni        upper layer with the acquired resources. The upper layer should
487*14b24e2bSVaishali Kulkarni        return error in case there is a problem with the amount of acquired
488*14b24e2bSVaishali Kulkarni        resources, otherwise success.
489*14b24e2bSVaishali Kulkarni
490*14b24e2bSVaishali Kulkarni- enum _ecore_status_t
491*14b24e2bSVaishali Kulkarni  OSAL_IOV_VF_ACQUIRE(struct ecore_hwfn *p_hwfn, u8 relative_vfid)
492*14b24e2bSVaishali Kulkarni	Called on PF side while processing a VF acquisition message, to allow
493*14b24e2bSVaishali Kulkarni        the ecore-client to prevent the acquisition if required.
494*14b24e2bSVaishali Kulkarni
495*14b24e2bSVaishali Kulkarni- enum _ecore_status_t
496*14b24e2bSVaishali Kulkarni  OSAL_VF_CQE_COMPLETION(struct ecore_hwfn *p_hwfn,
497*14b24e2bSVaishali Kulkarni                         struct eth_slow_path_rx_cqe *cqe,
498*14b24e2bSVaishali Kulkarni                         enum protocol_type protocol)
499*14b24e2bSVaishali Kulkarni        Called on the VF to let the upper layer chance to handle the cqe.
500*14b24e2bSVaishali Kulkarni
501*14b24e2bSVaishali Kulkarni- u8 OSAL_IOV_GET_OS_TYPE()
502*14b24e2bSVaishali Kulkarni	Called on PF side - should return a VFPF_ACQUIRE_OS_* value matching
503*14b24e2bSVaishali Kulkarni	the OS hypervisor type.
504*14b24e2bSVaishali Kulkarni
505*14b24e2bSVaishali Kulkarni- void OSAL_IOV_VF_MSG_TYPE(struct ecore_hwfn *p_hwfn,
506*14b24e2bSVaishali Kulkarni                            u8 vf_id,
507*14b24e2bSVaishali Kulkarni                            int vf_msg_type)
508*14b24e2bSVaishali Kulkarni	Called on PF side to indicate  the VF to PF TLV Request type send by VF in
509*14b24e2bSVaishali Kulkarni	the MailBox request through HW Channel.
510*14b24e2bSVaishali Kulkarni
511*14b24e2bSVaishali Kulkarni- void OSAL_IOV_PF_RESP_TYPE(struct ecore_hwfn *p_hwfn,
512*14b24e2bSVaishali Kulkarni                             u8 vf_id,
513*14b24e2bSVaishali Kulkarni                             enum ecore_iov_pf_to_vf_status pf_resp_type)
514*14b24e2bSVaishali Kulkarni	Called on PF side to indicate the PF to VF Response type after the processing
515*14b24e2bSVaishali Kulkarni        of VF Mailbox request through HW Channel.
516*14b24e2bSVaishali Kulkarni
517*14b24e2bSVaishali Kulkarni- int OSAL_PF_VALIDATE_MODIFY_TUNN_CONFIG(struct ecore_hwfn *p_hwfn,
518*14b24e2bSVaishali Kulkarni					  u16 *feature_mask, bool *update,
519*14b24e2bSVaishali Kulkarni					  struct ecore_tunnel_info *p_tun)
520*14b24e2bSVaishali Kulkarni	Called on PF side to validate and modify VF's requested tunnel mode,
521*14b24e2bSVaishali Kulkarni	classes and udp ports based on update masks/flags. In case PF modifies
522*14b24e2bSVaishali Kulkarni	VF requested data then it should still return an error
523*14b24e2bSVaishali Kulkarni	to indicate to VF flow. Finally, If any tunnel configuration update
524*14b24e2bSVaishali Kulkarni	is required then they must set "true" in "update" address.
525*14b24e2bSVaishali Kulkarni	PF should also set the features in "feature_mask" which are enabled
526*14b24e2bSVaishali Kulkarni	or requested from VF to be enabled and can be kept intact
527*14b24e2bSVaishali Kulkarni	[i.e they can no longer be modified further by PF in terms of tunn
528*14b24e2bSVaishali Kulkarni	mode or tun classes].
529*14b24e2bSVaishali Kulkarni
530*14b24e2bSVaishali KulkarniHW errors & Recovery
531*14b24e2bSVaishali Kulkarni====================
532*14b24e2bSVaishali Kulkarni- void OSAL_SCHEDULE_RECOVERY_HANDLER(struct ecore_hwfn* p_hwfn)
533*14b24e2bSVaishali Kulkarni	ecore uses this callback to inform the upper-layer driver that a process
534*14b24e2bSVaishali Kulkarni	kill indication has been received from the MFW, and that a recovery
535*14b24e2bSVaishali Kulkarni	handler should be scheduled to handle the recovery flow.
536*14b24e2bSVaishali Kulkarni
537*14b24e2bSVaishali Kulkarni- void OSAL_HW_ERROR_OCCURRED(struct ecore_hwfn *p_hwfn,
538*14b24e2bSVaishali Kulkarni			      enum ecore_hw_err_type err_type)
539*14b24e2bSVaishali Kulkarni	ecore uses this callback to inform the upper-layer driver about an error
540*14b24e2bSVaishali Kulkarni	in the HW/FW.
541*14b24e2bSVaishali Kulkarni
542*14b24e2bSVaishali KulkarniUnzipping functionality related osal
543*14b24e2bSVaishali Kulkarni====================================
544*14b24e2bSVaishali Kulkarni- u32 OSAL_UNZIP_DATA(struct ecore_hwfn *p_hwfn, u32 input_len, u8 *input_buf,
545*14b24e2bSVaishali Kulkarni		      u32 max_size, u8 *unzip_buf)
546*14b24e2bSVaishali Kulkarni	Unzip zipped data of length "input_len" present in "input_buf" and
547*14b24e2bSVaishali Kulkarni	write unzipped data into "unzip_buf". "max_size" is max length of unzipped
548*14b24e2bSVaishali Kulkarni	data which can be written into "unzip_buf".
549*14b24e2bSVaishali Kulkarni	returns the length of unzipped data in dwords, in case of failure returns 0.
550*14b24e2bSVaishali Kulkarni
551*14b24e2bSVaishali KulkarniNote -	All drivers has to define/set CONFIG_ECORE_ZIPPED_FW to take zipped
552*14b24e2bSVaishali Kulkarni	firmware file and implement their own functionality to unzip data.
553*14b24e2bSVaishali Kulkarni
554*14b24e2bSVaishali KulkarniString handling related osals
555*14b24e2bSVaishali Kulkarni=============================
556*14b24e2bSVaishali Kulkarni- int OSAL_SPRINTF(char *str, const char *format, ...)
557*14b24e2bSVaishali Kulkarni	Write a formatted output to a string pointed to by str.
558*14b24e2bSVaishali Kulkarni
559*14b24e2bSVaishali Kulkarni- int OSAL_SNPRINTF(char *str, osal_size_t n, const char *format, ...)
560*14b24e2bSVaishali Kulkarni	Write a formatted output to a string pointed to by str, taking n as the maximum number of characters to write.
561*14b24e2bSVaishali Kulkarni	The remaining characters are discarded and not stored, but counted for the value returned by the function.
562*14b24e2bSVaishali Kulkarni
563*14b24e2bSVaishali Kulkarni- u32 OSAL_STRLEN(const char *str)
564*14b24e2bSVaishali Kulkarni	Return the length of the string pointed to by str, excluding the terminating null byte ('\0').
565*14b24e2bSVaishali Kulkarni
566*14b24e2bSVaishali Kulkarni- char *OSAL_STRCPY(char *dest, const char *src)
567*14b24e2bSVaishali Kulkarni	Copy the string pointed to by src, including the terminating null byte ('\0'), to the buffer  pointed to by dest.
568*14b24e2bSVaishali Kulkarni
569*14b24e2bSVaishali Kulkarni- char *OSAL_STRNCPY(char *dest, const char *src, osal_size_t n)
570*14b24e2bSVaishali Kulkarni	Copies up to n characters from the string pointed to by src to dest.
571*14b24e2bSVaishali Kulkarni	In the case where the length of src is less than that of n, the remainder of dest will be padded with null bytes.
572*14b24e2bSVaishali Kulkarni
573*14b24e2bSVaishali Kulkarni- int OSAL_STRCMP(const char *str1, const char *str2)
574*14b24e2bSVaishali Kulkarni	Compares the string pointed by str1 to the string pointed by str2.
575*14b24e2bSVaishali Kulkarni
576*14b24e2bSVaishali Kulkarni- int OSAL_STRTOUL(const char *str, unsigned int base, unsigned long *res)
577*14b24e2bSVaishali Kulkarni	Converts a string pointed by str to an unsigned long.
578*14b24e2bSVaishali Kulkarni	The string base can be given explicitly, or "0" can be provided and then it will be automatically detected with the conventional semantics
579*14b24e2bSVaishali Kulkarni	(begins with 0x - the number will be parsed as a hexadecimal, if it otherwise begins with 0 - octal, otherwise - decimal).
580*14b24e2bSVaishali Kulkarni	The the result of the conversion is written to the variable pointed by res.
581*14b24e2bSVaishali Kulkarni
582*14b24e2bSVaishali KulkarniMiscellaneous
583*14b24e2bSVaishali Kulkarni=============
584*14b24e2bSVaishali Kulkarniosal_size_t  - The type is used to store the result of sizeof operator.
585*14b24e2bSVaishali Kulkarni		On certain platfroms it is typedefed to __SIZE_TYPE__, a
586*14b24e2bSVaishali Kulkarni		compiler predefined macro.
587*14b24e2bSVaishali Kulkarni
588*14b24e2bSVaishali Kulkarniosal_int_ptr_t - Integer type large enough to hold a pointer. The data type is
589*14b24e2bSVaishali Kulkarni	          useful for casting pointers when we want to do address
590*14b24e2bSVaishali Kulkarni	          arithmetic.
591*14b24e2bSVaishali Kulkarni
592*14b24e2bSVaishali KulkarniOSAL_NULL -  Null value defintion.
593*14b24e2bSVaishali Kulkarni
594*14b24e2bSVaishali KulkarniOSAL_INLINE - The specifier instructs the compiler to insert a copy of the
595*14b24e2bSVaishali Kulkarni	       function body into each place the function is called.
596*14b24e2bSVaishali Kulkarni
597*14b24e2bSVaishali KulkarniOSAL_BUILD_BUG_ON(condition) - Break compilation if the "condition" is true.
598*14b24e2bSVaishali Kulkarni
599*14b24e2bSVaishali KulkarniOSAL_PAGE_SIZE - Macro for the page size value i.e., number of bytes in a
600*14b24e2bSVaishali Kulkarni	          memory page.
601*14b24e2bSVaishali Kulkarni
602*14b24e2bSVaishali KulkarniOSAL_CACHE_LINE_SIZE - Macro for the cache line size value in bytes.
603*14b24e2bSVaishali Kulkarni
604*14b24e2bSVaishali KulkarniOSAL_IOMEM - Annotation used to mark pointers to I/O memory. It is used by
605*14b24e2bSVaishali Kulkarni	      Sparse, a tool used to find possible coding faults in the
606*14b24e2bSVaishali Kulkarni	      kernel. The annotation is ignored in the normal compilation.
607*14b24e2bSVaishali Kulkarni	      When checking the code with sparse, however, developers will see
608*14b24e2bSVaishali Kulkarni	      a whole new set of warnings caused by code which mixes normal
609*14b24e2bSVaishali Kulkarni	      pointers with OSAL_IOMEM pointers, or which dereferences those
610*14b24e2bSVaishali Kulkarni	      pointers.
611*14b24e2bSVaishali Kulkarni
612*14b24e2bSVaishali KulkarniOSAL_UNLIKELY(condition) -  An instruction to the compiler to emit instructions
613*14b24e2bSVaishali Kulkarni	     in the favor of "condition" value likely to be false (zero).
614*14b24e2bSVaishali Kulkarni
615*14b24e2bSVaishali Kulkarni- type OSAL_MIN_T(type, val1, val2)
616*14b24e2bSVaishali Kulkarni	Returns the minimum of (val1, val2) which are of data type "type".
617*14b24e2bSVaishali Kulkarni
618*14b24e2bSVaishali Kulkarni- type OSAL_MAX_T(type, val1, val2)
619*14b24e2bSVaishali Kulkarni	Returns the maximum of (val1, val2) which are of data type "type".
620*14b24e2bSVaishali Kulkarni
621*14b24e2bSVaishali Kulkarni- u32* OSAL_REG_ADDR(struct *ecore_hwfn, u32 hw_offset)
622*14b24e2bSVaishali Kulkarni	Returns the memory address value of the device at the offset hw_offset.
623*14b24e2bSVaishali Kulkarni
624*14b24e2bSVaishali Kulkarni- u32 OSAL_NUM_ACTIVE_CPU()
625*14b24e2bSVaishali Kulkarni	Returns the number of active CPUs on the machine
626*14b24e2bSVaishali Kulkarni
627*14b24e2bSVaishali Kulkarni- u32 DIV_ROUND_UP(u32 size, u32 divisor_size)
628*14b24e2bSVaishali Kulkarni	Returns number of elements required of `divisor_size' each,
629*14b24e2bSVaishali Kulkarni        required to hold at least `size' data.
630*14b24e2bSVaishali Kulkarni
631*14b24e2bSVaishali Kulkarni- u32 ROUNDUP(u32 size, u32 divisor_size)
632*14b24e2bSVaishali Kulkarni	Returns DIV_ROUND_UP * divisor_size [how much memory will be
633*14b24e2bSVaishali Kulkarni	required for holding `size' data, if we can only allocate
634*14b24e2bSVaishali Kulkarni	in granularity of `divisor_size'].
635*14b24e2bSVaishali Kulkarni
636*14b24e2bSVaishali Kulkarni- u32 OSAL_ROUNDUP_POW_OF_TWO(u32)
637*14b24e2bSVaishali Kulkarni	Return a round-up to closest value which is a power of 2.
638*14b24e2bSVaishali Kulkarni
639*14b24e2bSVaishali Kulkarni- u32 OSAL_LOG2(u32)
640*14b24e2bSVaishali Kulkarni	Returns a log on a 2-basis of the value.
641*14b24e2bSVaishali Kulkarni
642*14b24e2bSVaishali Kulkarni- void OSAL_ASSERT(bool cond)
643*14b24e2bSVaishali Kulkarni	Should perform some sort of panic in case `cond' is false.
644*14b24e2bSVaishali Kulkarni
645*14b24e2bSVaishali Kulkarni- u32 OFFSETOF(struct, field)
646*14b24e2bSVaishali Kulkarni	returns the offset in bytes of field inside struct.
647*14b24e2bSVaishali Kulkarni	TBD - isn't it ANSI-C? If so, can be removed from ecore.
648*14b24e2bSVaishali Kulkarni
649*14b24e2bSVaishali Kulkarni- void PRINT(void *dp_ctx, char *format_string, ...)
650*14b24e2bSVaishali Kulkarni- void PRINT_ERR(void *dp_ctx, char *format_string, ...)
651*14b24e2bSVaishali Kulkarni	Macros used by the ecore debug facilities to print verbose & error logs.
652*14b24e2bSVaishali Kulkarni
653*14b24e2bSVaishali Kulkarni- void OSAL_WARN(bool condition, const char *format, ...)
654*14b24e2bSVaishali Kulkarni	Should cause a warning [at least on debug mode] if hit.
655*14b24e2bSVaishali Kulkarni
656*14b24e2bSVaishali Kulkarni- void OSAL_BEFORE_PF_START(struct file, engine id)
657*14b24e2bSVaishali Kulkarni	Perform some action just before first interaction with FW.
658*14b24e2bSVaishali Kulkarni
659*14b24e2bSVaishali Kulkarni- void OSAL_AFTER_PF_STOP(struct file, engine id)
660*14b24e2bSVaishali Kulkarni	Perform some action just aftter last interaction with FW.
661*14b24e2bSVaishali Kulkarni
662*14b24e2bSVaishali Kulkarni- u32 ARRAY_SIZE(array[])
663*14b24e2bSVaishali Kulkarni	Returns the number of elements in an array.
664*14b24e2bSVaishali Kulkarni
665*14b24e2bSVaishali Kulkarni- osal_uintptr_t - Used for casting pointer to integer value.
666*14b24e2bSVaishali Kulkarni	Some 32 bit OS complains about "cast from pointer to integer of different size". As on those platform
667*14b24e2bSVaishali Kulkarni	integers and pointers are of different sizes. Due to this fact we couldn't use any generic data type in
668*14b24e2bSVaishali Kulkarni	ecore to cast pointer to integer data type which can be appropriate for both 32 bit and 64 bit platform
669*14b24e2bSVaishali Kulkarni	for all OS distributions, as a data type size on each OS distribution may vary. So this osal serves the
670*14b24e2bSVaishali Kulkarni	purpose of to define OS specific data type cast which can be used on both 32 bit and 64 bit platform.
671*14b24e2bSVaishali Kulkarni
672*14b24e2bSVaishali Kulkarni- void OSAL_GET_PROTOCOL_STATS(struct *ecore_dev, enum ecore_mcp_protocol_type type,
673*14b24e2bSVaishali Kulkarni			       union ecore_mcp_protocol_stats *stats);
674*14b24e2bSVaishali Kulkarni	Call from the ecore to get the statististics of a protocol driver. Ecore client
675*14b24e2bSVaishali Kulkarni	need to populate the requested statistics. If the PF has more than one function,
676*14b24e2bSVaishali Kulkarni	driver should return the statistics sum of all the interfaces under the PF.
677*14b24e2bSVaishali Kulkarni
678*14b24e2bSVaishali Kulkarni- int OSAL_SLOWPATH_IRQ_REQ(struct ecore_hwfn *p_hwfn)
679*14b24e2bSVaishali Kulkarni	Call from ecore to the upper layer driver to request IRQs for the slowpath
680*14b24e2bSVaishali Kulkarni	interrupts handling.
681*14b24e2bSVaishali Kulkarni
682*14b24e2bSVaishali Kulkarni- u32 OSAL_GET_RDMA_SB_ID(struct ecore_hwfn *p_hwfn, u32 relative_sb_id)
683*14b24e2bSVaishali Kulkarni	Call from ecore to obtain real SB ID from upper layer.
684*14b24e2bSVaishali Kulkarni
685*14b24e2bSVaishali Kulkarni- void OSAL_DCBX_AEN(struct ecore_hwfn *p_hwfn, enum ecore_mib_read_type mib_type)
686*14b24e2bSVaishali Kulkarni	Call from ecore to notify the dcbx related asynchronous events from the MFW.
687*14b24e2bSVaishali Kulkarni
688*14b24e2bSVaishali Kulkarni- u32 OSAL_CRC32(u32 crc, u8 *buf, osal_size_t length)
689*14b24e2bSVaishali Kulkarni	Compute a CRC-32 value using a Castagnoli polynomial.
690*14b24e2bSVaishali Kulkarni	`crc' is the previous value for the checksum, and `buf' shall point to
691*14b24e2bSVaishali Kulkarni	an array of `length' bytes of data to be added to this checksum.
692*14b24e2bSVaishali Kulkarni
693*14b24e2bSVaishali Kulkarni- void OSAL_CRC8_POPULATE(u8 table[CRC8_TABLE_SIZE], u8 polynomial)
694*14b24e2bSVaishali Kulkarni	Fill the provided crc table for given polynomial in reverse bit order (msb first).
695*14b24e2bSVaishali Kulkarni	The table size is 256 ('CRC8_TABLE_SIZE').
696*14b24e2bSVaishali Kulkarni
697*14b24e2bSVaishali Kulkarni- u8 OSAL_CRC8(const u8 table[CRC8_TABLE_SIZE], u8 *pdata, osal_size_t nbytes, u8 crc)
698*14b24e2bSVaishali Kulkarni	Calculate a crc8 over the given input data.
699*14b24e2bSVaishali Kulkarni	`table' is the crc table used for calculation, `pdata' is a pointer to data buffer,
700*14b24e2bSVaishali Kulkarni	`nbytes' is the size of the data buffer, and `crc' is the previous returned crc8 value.
701*14b24e2bSVaishali Kulkarni
702*14b24e2bSVaishali Kulkarni- s64 OSAL_DIV_S64(s64 value, s64 base)
703*14b24e2bSVaishali Kulkarni	Some distros [32-bit] are having problems with direct division of 64-bit variables.
704*14b24e2bSVaishali Kulkarni	This should logically return (value / base), and for distros that don't care about this
705*14b24e2bSVaishali Kulkarni	sort of issues it can be defined to be exactly that.
706*14b24e2bSVaishali Kulkarni
707*14b24e2bSVaishali KulkarniNVRAM related osals
708*14b24e2bSVaishali Kulkarni===================
709*14b24e2bSVaishali Kulkarni- bool OSAL_NVM_IS_ACCESS_ENABLED(struct ecore_hwfn *p_hwfn)
710*14b24e2bSVaishali Kulkarni        This osal allows to upper layer decide if it is allowed to access
711*14b24e2bSVaishali Kulkarni        the NVRAM.
712*14b24e2bSVaishali Kulkarni
713*14b24e2bSVaishali KulkarniManagement changes related osals
714*14b24e2bSVaishali Kulkarni================================
715*14b24e2bSVaishali Kulkarni- int OSAL_MFW_TLV_REQ(struct ecore_hwfn *p_hwfn)
716*14b24e2bSVaishali Kulkarni	Called to inform that MFW has requested for TLVs. We are in the interrupt
717*14b24e2bSVaishali Kulkarni	context here, ecore client need to schedule a thread/bottom-half context
718*14b24e2bSVaishali Kulkarni	to handle this task, and return the control immediately.
719*14b24e2bSVaishali Kulkarni	The bottom-half thread will need to invoke ecore_mfw_process_tlv_req()
720*14b24e2bSVaishali Kulkarni	for further processing of the TLV request.
721*14b24e2bSVaishali Kulkarni
722*14b24e2bSVaishali Kulkarni- int OSAL_MFW_FILL_TLV_DATA(struct ecore_hwfn *p_hwfn, enum ecore_mfw_tlv_type type,
723*14b24e2bSVaishali Kulkarni                             union ecore_mfw_tlv_data *data)
724*14b24e2bSVaishali Kulkarni	Called from ecore to get the TLV values of a given type. Ecore client
725*14b24e2bSVaishali Kulkarni	need to fill in the values for all the fields that it's aware of, and
726*14b24e2bSVaishali Kulkarni	also need to set the flags associated with the respective fields. For instance,
727*14b24e2bSVaishali Kulkarni	if client sets value for 'npi_enabled' field, it needs to set the flag
728*14b24e2bSVaishali Kulkarni	'npiv_enabled_set' to true.
729*14b24e2bSVaishali Kulkarni
730*14b24e2bSVaishali Kulkarni- void OSAL_HW_INFO_CHANGE(struct ecore_hwfn *p_hwfn, enum ecore_hw_info_change)
731*14b24e2bSVaishali Kulkarni	Called after management has changed some property of a hw_info field.
732*14b24e2bSVaishali Kulkarni	The enum value indicates which field has changed. This is a FYI kind of
733*14b24e2bSVaishali Kulkarni	notification - direct HW/FW changes [if applicable] were already done.