1  /**********************************************************************
2  * Copyright (C) 2011-2015 Cadence Design Systems, Inc.- http://www.cadence.com
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  ***********************************************************************
17  * cps_v2.h
18  * Interface for Cadence Platform Services (CPS), version 2
19  *
20  * This is the "hardware abstraction layer" upon which all drivers are built.
21  * It must be implemented for each platform.
22  ***********************************************************************/
23 #ifndef _CPS_H_
24 #define _CPS_H_
25 
26 #include "cdn_stdint.h"
27 
28 /****************************************************************************
29  * Types
30  ***************************************************************************/
31 
32 /** A lock handle */
33 typedef void* CPS_LockHandle;
34 
35 /****************************************************************************
36  * Prototypes
37  ***************************************************************************/
38 
39 /**
40  * Check that sufficient locks are available
41  * @param[in] lockCount number of locks requested
42  * @return 0 on success (locks available)
43  * @return ENOENT if insufficient locks are available
44  */
45 extern uint32_t CPS_ProbeLocks(uint32_t lockCount);
46 
47 /**
48  * Initialize a lock
49  * @param[out] lock where to store the allocated, initialized lock
50  * @return 0 on success (lock is allocated and initialized)
51  * @return ENOENT if insufficient locks are available
52  */
53 extern uint32_t CPS_InitLock(CPS_LockHandle* lock);
54 
55 /**
56  * Free a lock
57  * @param[in] lock the lock
58  */
59 extern void CPS_FreeLock(CPS_LockHandle lock);
60 
61 /**
62  * Lock a lock, pending the current thread/task if necessary until the lock is available
63  * @param[in] lock the lock
64  */
65 extern uint32_t CPS_Lock(CPS_LockHandle lock);
66 
67 /**
68  * Unlock a lock, readying the next highest-priority thread/task pended on it if any
69  * @param[in] lock the lock
70  */
71 extern uint32_t CPS_Unlock(CPS_LockHandle lock);
72 
73 /**
74  * Read a byte, bypassing the cache
75  * @param[in] address the address
76  * @return the byte at the given address
77  */
78 extern uint8_t CPS_UncachedRead8(volatile uint8_t* address);
79 
80 /**
81  * Read a short, bypassing the cache
82  * @param[in] address the address
83  * @return the short at the given address
84  */
85 extern uint16_t CPS_UncachedRead16(volatile uint16_t* address);
86 
87 /**
88  * Read a (32-bit) word, bypassing the cache
89  * @param[in] address the address
90  * @return the word at the given address
91  */
92 extern uint32_t CPS_UncachedRead32(volatile uint32_t* address);
93 
94 /**
95  * Read a (32-bit) address value, bypassing the cache.
96  * This function is for reading an address value, i.e. something that
97  * is seen as an address by hardware, and therefore might need to be
98  * translated from a physical bus address to a CPU address.
99  * @param[in] location
100  * @return the CPU address of the physical bus address at the given (CPU) location
101  */
102 extern uint32_t CPS_ReadPhysAddress32(volatile uint32_t* location);
103 
104 /**
105  * Write a byte to memory, bypassing the cache
106  * @param[in] address the address
107  * @param[in] value the byte to write
108  */
109 extern void CPS_UncachedWrite8(volatile uint8_t* address, uint8_t value);
110 
111 /**
112  * Write a short to memory, bypassing the cache
113  * @param[in] address the address
114  * @param[in] value the short to write
115  */
116 extern void CPS_UncachedWrite16(volatile uint16_t* address, uint16_t value);
117 
118 /**
119  * Write a (32-bit) word to memory, bypassing the cache
120  * @param[in] address the address
121  * @param[in] value the word to write
122  */
123 extern void CPS_UncachedWrite32(volatile uint32_t* address, uint32_t value);
124 
125 /**
126  * Write a (32-bit) address value to memory, bypassing the cache.
127  * This function is for writing an address value, i.e. something that
128  * will be treated as an address by hardware, and therefore might need
129  * to be translated to a physical bus address.
130  * @param[in] location the (CPU) location where to write the address value
131  * @param[in] addrValue the address value to write
132  */
133 extern void CPS_WritePhysAddress32(volatile uint32_t* location, uint32_t addrValue);
134 
135 /**
136  * Hardware specific memcpy.
137  * @param[in] src  src address
138  * @param[in] dst  destination address
139  * @param[in] size size of the copy
140  */
141 extern void CPS_BufferCopy(volatile uint8_t *dst, volatile uint8_t *src, uint32_t size);
142 
143 #endif /* multiple inclusion protection */
144