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. 734