1 /***************************************************************************** 2 3 (c) Cambridge Silicon Radio Limited 2011 4 All rights reserved and confidential information of CSR 5 6 Refer to LICENSE.txt included with this source for details 7 on the license terms. 8 9 *****************************************************************************/ 10 11 #ifndef CSR_WIFI_HIP_CHIPHELPER_H__ 12 #define CSR_WIFI_HIP_CHIPHELPER_H__ 13 14 15 #include <linux/types.h> 16 17 /* The age of the BlueCore chip. This is probably not useful, if 18 you know the age then you can probably work out the version directly. */ 19 enum chip_helper_bluecore_age 20 { 21 chip_helper_bluecore_pre_bc7, 22 chip_helper_bluecore_bc7_or_later 23 }; 24 25 /* We support up to three windowed regions at the moment. 26 Don't reorder these - they're used to index into an array. */ 27 enum chip_helper_window_index 28 { 29 CHIP_HELPER_WINDOW_1 = 0, 30 CHIP_HELPER_WINDOW_2 = 1, 31 CHIP_HELPER_WINDOW_3 = 2, 32 CHIP_HELPER_WINDOW_COUNT = 3 33 }; 34 35 /* These are the things that we can access through a window. 36 Don't reorder these - they're used to index into an array. */ 37 enum chip_helper_window_type 38 { 39 CHIP_HELPER_WT_CODE_RAM = 0, 40 CHIP_HELPER_WT_FLASH = 1, 41 CHIP_HELPER_WT_EXT_SRAM = 2, 42 CHIP_HELPER_WT_ROM = 3, 43 CHIP_HELPER_WT_SHARED = 4, 44 CHIP_HELPER_WT_COUNT = 5 45 }; 46 47 /* Commands to stop and start the XAP */ 48 enum chip_helper_dbg_emu_cmd_enum 49 { 50 CHIP_HELPER_DBG_EMU_CMD_XAP_STEP_MASK = 0x0001, 51 CHIP_HELPER_DBG_EMU_CMD_XAP_RUN_B_MASK = 0x0002, 52 CHIP_HELPER_DBG_EMU_CMD_XAP_BRK_MASK = 0x0004, 53 CHIP_HELPER_DBG_EMU_CMD_XAP_WAKEUP_MASK = 0x0008 54 }; 55 56 /* Bitmasks for Stop and sleep status: DBG_SPI_STOP_STATUS & DBG_HOST_STOP_STATUS */ 57 enum chip_helper_dbg_stop_status_enum 58 { 59 CHIP_HELPER_DBG_STOP_STATUS_NONE_MASK = 0x0000, 60 CHIP_HELPER_DBG_STOP_STATUS_P0_MASK = 0x0001, 61 CHIP_HELPER_DBG_STOP_STATUS_P1_MASK = 0x0002, 62 CHIP_HELPER_DBG_STOP_STATUS_P2_MASK = 0x0004, 63 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_P0_MASK = 0x0008, 64 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_P1_MASK = 0x0010, 65 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_P2_MASK = 0x0020, 66 /* Legacy names/alias */ 67 CHIP_HELPER_DBG_STOP_STATUS_MAC_MASK = 0x0001, 68 CHIP_HELPER_DBG_STOP_STATUS_PHY_MASK = 0x0002, 69 CHIP_HELPER_DBG_STOP_STATUS_BT_MASK = 0x0004, 70 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_MAC_MASK = 0x0008, 71 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_PHY_MASK = 0x0010, 72 CHIP_HELPER_DBG_STOP_STATUS_SLEEP_STATUS_BT_MASK = 0x0020 73 }; 74 75 /* Codes to disable the watchdog */ 76 enum chip_helper_watchdog_disable_enum 77 { 78 CHIP_HELPER_WATCHDOG_DISABLE_CODE1 = 0x6734, 79 CHIP_HELPER_WATCHDOG_DISABLE_CODE2 = 0xD6BF, 80 CHIP_HELPER_WATCHDOG_DISABLE_CODE3 = 0xC31E 81 }; 82 83 /* Other bits have changed between versions */ 84 enum chip_helper_gbl_misc_enum 85 { 86 CHIP_HELPER_GBL_MISC_SPI_STOP_OUT_EN_MASK = 0x0001, 87 CHIP_HELPER_GBL_MISC_MMU_INIT_DONE_MASK = 0x0004 88 }; 89 90 /* Coex status register, contains interrupt status and reset pullup status. 91 * CHIP_HELPER_COEX_STATUS_RST_PULLS_MSB_MASK can be used to check 92 * for WAPI on R03 chips and later. */ 93 enum chip_helper_coex_status_mask_enum 94 { 95 CHIP_HELPER_COEX_STATUS_RST_PULLS_LSB_MASK = 0x0001, 96 CHIP_HELPER_COEX_STATUS_RST_PULLS_MSB_MASK = 0x0008, 97 CHIP_HELPER_COEX_STATUS_WL_FEC_PINS_LSB_MASK = 0x0010, 98 CHIP_HELPER_COEX_STATUS_WL_FEC_PINS_MSB_MASK = 0x0080, 99 CHIP_HELPER_COEX_STATUS_INT_UART_MASK = 0x0100, 100 CHIP_HELPER_COEX_STATUS_INT_BT_LEG_MASK = 0x0200 101 }; 102 103 /* How to select the different CPUs */ 104 enum chip_helper_dbg_proc_sel_enum 105 { 106 CHIP_HELPER_DBG_PROC_SEL_MAC = 0, 107 CHIP_HELPER_DBG_PROC_SEL_PHY = 1, 108 CHIP_HELPER_DBG_PROC_SEL_BT = 2, 109 CHIP_HELPER_DBG_PROC_SEL_NONE = 2, 110 CHIP_HELPER_DBG_PROC_SEL_BOTH = 3 111 }; 112 113 /* These are the only registers that we have to know the 114 address of before we know the chip version. */ 115 enum chip_helper_fixed_registers 116 { 117 /* This is the address of GBL_CHIP_VERISON on BC7, 118 UF105x, UF60xx and 119 anything later than that. */ 120 CHIP_HELPER_UNIFI_GBL_CHIP_VERSION = 0xFE81, 121 122 CHIP_HELPER_OLD_BLUECORE_GBL_CHIP_VERSION = 0xFF9A 123 124 /* This isn't used at the moment (but might be needed 125 to distinguish the BlueCore sub version?) */ 126 /* CHIP_HELPER_OLD_BLUECORE_ANA_VERSION_ID = 0xFF7D */ 127 }; 128 129 /* Address-value pairs for defining initialisation values */ 130 struct chip_helper_init_values 131 { 132 u16 addr; 133 u16 value; 134 }; 135 136 /* A block of data that should be written to the device */ 137 struct chip_helper_reset_values 138 { 139 u32 gp_address; 140 u32 len; 141 const u16 *data; 142 }; 143 144 /* 145 * This is the C API. 146 */ 147 148 /* opaque type */ 149 typedef const struct chip_device_desc_t ChipDescript; 150 151 /* Return a NULL descriptor */ 152 ChipDescript* ChipHelper_Null(void); 153 154 /* This should get the correct version for any CSR chip. 155 The two parameters are what is read from addresses 156 0xFF9A and 0xFE81 (OLD_BLUECORE_GBL_CHIP_VERSION and 157 UNIFI_GBL_CHIP_VERSION). These should give a unique identity 158 for most (all?) chips. 159 160 FF9A is the old GBL_CHIP_VERSION register. If the high 161 eight bits are zero then the chip is a new (BC7 +) one 162 and FE81 is the _new_ GBL_CHIP_VERSION register. */ 163 ChipDescript* ChipHelper_GetVersionAny(u16 from_FF9A, u16 from_FE81); 164 165 /* The chip is a UniFi, but we don't know which type 166 The parameter is the value of UNIFI_GBL_CHIP_VERSION (0xFE81) */ 167 ChipDescript* ChipHelper_GetVersionUniFi(u16 version); 168 169 /* This gets the version from the SDIO device id. This only 170 gives quite a coarse grained version, so we should update once 171 we hav access to the function N registers. */ 172 ChipDescript* ChipHelper_GetVersionSdio(u8 sdio_version); 173 174 /* The chip is some sort of BlueCore. If "age" is "pre_bc7" then 175 "version" is what was read from FF9A. If "age" is bc7_or_later 176 then "version" is read from FE81. If we don't know if we're pre 177 or post BC7 then we should use "GetVersionAny". */ 178 ChipDescript* ChipHelper_GetVersionBlueCore(enum chip_helper_bluecore_age age, 179 u16 version); 180 181 /* The main functions of this class are built with an X macro. This 182 means we can generate the C and C++ versions from the same source 183 without the two diverging. 184 185 The DEF0 functions are simple and take no parameters. The first 186 parameter to the macro is the return type. The second parameter 187 is the function name and the third parameter is where to get the 188 info from (this is hidden from the user). 189 190 The DEF1 functions take one parameter. This time the third macro 191 parameter is the type of this parameter, and the fourth macro 192 parameter is the name of the parameter. The bodies of these 193 functions are hand written. */ 194 #define CHIP_HELPER_LIST(m) \ 195 CHIP_HELPER_DEF0(m, (const char *, FriendlyName, friendly_name)) \ 196 CHIP_HELPER_DEF0(m, (const char *, MarketingName, marketing_name)) \ 197 CHIP_HELPER_DEF0(m, (u16, DBG_EMU_CMD, regs->dbg_emu_cmd)) \ 198 CHIP_HELPER_DEF0(m, (u16, DBG_HOST_PROC_SELECT, regs->host.dbg_proc_select)) \ 199 CHIP_HELPER_DEF0(m, (u16, DBG_HOST_STOP_STATUS, regs->host.dbg_stop_status)) \ 200 CHIP_HELPER_DEF0(m, (u16, HOST_WINDOW1_PAGE, regs->host.window1_page)) \ 201 CHIP_HELPER_DEF0(m, (u16, HOST_WINDOW2_PAGE, regs->host.window2_page)) \ 202 CHIP_HELPER_DEF0(m, (u16, HOST_WINDOW3_PAGE, regs->host.window3_page)) \ 203 CHIP_HELPER_DEF0(m, (u16, HOST_IO_LOG_ADDR, regs->host.io_log_addr)) \ 204 CHIP_HELPER_DEF0(m, (u16, DBG_SPI_PROC_SELECT, regs->spi.dbg_proc_select)) \ 205 CHIP_HELPER_DEF0(m, (u16, DBG_SPI_STOP_STATUS, regs->spi.dbg_stop_status)) \ 206 CHIP_HELPER_DEF0(m, (u16, SPI_WINDOW1_PAGE, regs->spi.window1_page)) \ 207 CHIP_HELPER_DEF0(m, (u16, SPI_WINDOW2_PAGE, regs->spi.window2_page)) \ 208 CHIP_HELPER_DEF0(m, (u16, SPI_WINDOW3_PAGE, regs->spi.window3_page)) \ 209 CHIP_HELPER_DEF0(m, (u16, SPI_IO_LOG_ADDR, regs->spi.io_log_addr)) \ 210 CHIP_HELPER_DEF0(m, (u16, DBG_RESET, regs->dbg_reset)) \ 211 CHIP_HELPER_DEF0(m, (u16, DBG_RESET_VALUE, regs->dbg_reset_value)) \ 212 CHIP_HELPER_DEF0(m, (u16, DBG_RESET_WARN, regs->dbg_reset_warn)) \ 213 CHIP_HELPER_DEF0(m, (u16, DBG_RESET_WARN_VALUE, regs->dbg_reset_warn_value)) \ 214 CHIP_HELPER_DEF0(m, (u16, DBG_RESET_RESULT, regs->dbg_reset_result)) \ 215 CHIP_HELPER_DEF0(m, (u16, WATCHDOG_DISABLE, regs->watchdog_disable)) \ 216 CHIP_HELPER_DEF0(m, (u16, PROC_PC_SNOOP, regs->proc_pc_snoop)) \ 217 CHIP_HELPER_DEF0(m, (u16, GBL_CHIP_VERSION, regs->gbl_chip_version)) \ 218 CHIP_HELPER_DEF0(m, (u16, GBL_MISC_ENABLES, regs->gbl_misc_enables)) \ 219 CHIP_HELPER_DEF0(m, (u16, XAP_PCH, regs->xap_pch)) \ 220 CHIP_HELPER_DEF0(m, (u16, XAP_PCL, regs->xap_pcl)) \ 221 CHIP_HELPER_DEF0(m, (u16, MAILBOX0, regs->mailbox0)) \ 222 CHIP_HELPER_DEF0(m, (u16, MAILBOX1, regs->mailbox1)) \ 223 CHIP_HELPER_DEF0(m, (u16, MAILBOX2, regs->mailbox2)) \ 224 CHIP_HELPER_DEF0(m, (u16, MAILBOX3, regs->mailbox3)) \ 225 CHIP_HELPER_DEF0(m, (u16, SDIO_HIP_HANDSHAKE, regs->sdio_hip_handshake)) \ 226 CHIP_HELPER_DEF0(m, (u16, SDIO_HOST_INT, regs->sdio_host_int)) \ 227 CHIP_HELPER_DEF0(m, (u16, COEX_STATUS, regs->coex_status)) \ 228 CHIP_HELPER_DEF0(m, (u16, SHARED_IO_INTERRUPT, regs->shared_io_interrupt)) \ 229 CHIP_HELPER_DEF0(m, (u32, PROGRAM_MEMORY_RAM_OFFSET, prog_offset.ram)) \ 230 CHIP_HELPER_DEF0(m, (u32, PROGRAM_MEMORY_ROM_OFFSET, prog_offset.rom)) \ 231 CHIP_HELPER_DEF0(m, (u32, PROGRAM_MEMORY_FLASH_OFFSET, prog_offset.flash)) \ 232 CHIP_HELPER_DEF0(m, (u32, PROGRAM_MEMORY_EXT_SRAM_OFFSET, prog_offset.ext_sram)) \ 233 CHIP_HELPER_DEF0(m, (u16, DATA_MEMORY_RAM_OFFSET, data_offset.ram)) \ 234 CHIP_HELPER_DEF0(m, (s32, HasFlash, bools.has_flash)) \ 235 CHIP_HELPER_DEF0(m, (s32, HasExtSram, bools.has_ext_sram)) \ 236 CHIP_HELPER_DEF0(m, (s32, HasRom, bools.has_rom)) \ 237 CHIP_HELPER_DEF0(m, (s32, HasBt, bools.has_bt)) \ 238 CHIP_HELPER_DEF0(m, (s32, HasWLan, bools.has_wlan)) \ 239 CHIP_HELPER_DEF1(m, (u16, WINDOW_ADDRESS, enum chip_helper_window_index, window)) \ 240 CHIP_HELPER_DEF1(m, (u16, WINDOW_SIZE, enum chip_helper_window_index, window)) \ 241 CHIP_HELPER_DEF1(m, (u16, MapAddress_SPI2HOST, u16, addr)) \ 242 CHIP_HELPER_DEF1(m, (u16, MapAddress_HOST2SPI, u16, addr)) \ 243 CHIP_HELPER_DEF1(m, (u32, ClockStartupSequence, const struct chip_helper_init_values **, val)) \ 244 CHIP_HELPER_DEF1(m, (u32, HostResetSequence, const struct chip_helper_reset_values **, val)) 245 246 /* Some magic to help the expansion */ 247 #define CHIP_HELPER_DEF0(a, b) \ 248 CHIP_HELPER_DEF0_ ## a b 249 #define CHIP_HELPER_DEF1(a, b) \ 250 CHIP_HELPER_DEF1_ ## a b 251 252 /* Macros so that when we expand the list we get "C" function prototypes. */ 253 #define CHIP_HELPER_DEF0_C_DEC(ret_type, name, info) \ 254 ret_type ChipHelper_ ## name(ChipDescript * chip_help); 255 #define CHIP_HELPER_DEF1_C_DEC(ret_type, name, type1, name1) \ 256 ret_type ChipHelper_ ## name(ChipDescript * chip_help, type1 name1); 257 258 CHIP_HELPER_LIST(C_DEC) 259 260 /* FriendlyName 261 MarketingName 262 263 These two functions return human readable strings that describe 264 the chip. FriendlyName returns something that a software engineer 265 at CSR might understand. MarketingName returns something more like 266 an external name for a CSR chip. 267 */ 268 /* DBG_EMU_CMD 269 WATCHDOG_DISABLE 270 PROC_PC_SNOOP 271 GBL_CHIP_VERSION 272 XAP_PCH 273 XAP_PCL 274 275 These registers are used to control the XAPs. 276 */ 277 /* DBG_HOST_PROC_SELECT DBG_HOST_STOP_STATUS 278 HOST_WINDOW1_PAGE HOST_WINDOW2_PAGE HOST_WINDOW3_PAGE 279 HOST_IO_LOG_ADDR 280 DBG_SPI_PROC_SELECT DBG_SPI_STOP_STATUS 281 SPI_WINDOW1_PAGE SPI_WINDOW2_PAGE SPI_WINDOW3_PAGE 282 SPI_IO_LOG_ADDR 283 284 These register are used to control the XAPs and the memory 285 windows, normally while debugging the code on chip. There 286 are two versons of these registers, one for access via SPI 287 and another for access via the host interface. 288 */ 289 /* DBG_RESET 290 DBG_RESET_VALUE 291 DBG_RESET_WARN 292 DBG_RESET_WARN_VALUE 293 DBG_RESET_RESULT 294 295 These registers are used to reset the XAP. This can be 296 quite complex for some chips. If DBG_RESET_WARN is non 297 zero the DBG_RESET_WARN_VALUE should be written to address 298 DBG_RESET_WARN before the reset is perfeormed. DBG_RESET_VALUE 299 should then be written to DBG_RESET to make the reset happen. 300 The DBG_RESET_RESULT register should contain 0 if the reset 301 was successful. 302 */ 303 /* GBL_MISC_ENABLES 304 305 This register controls some special chip features. It 306 should be used with care is it changes quite a lot between 307 chip versions. 308 */ 309 /* MAILBOX0 310 MAILBOX1 311 MAILBOX2 312 MAILBOX3 313 314 The mailbox registers are for communication between the host 315 and the firmware. There use is described in part by the host 316 interface protcol specifcation. 317 */ 318 /* SDIO_HIP_HANDSHAKE 319 320 This is one of the more important SDIO HIP registers. On some 321 chips it has the same value as one of the mailbox registers 322 and on other chips it is different. 323 */ 324 /* SDIO_HOST_INT 325 SHARED_IO_INTERRUPT 326 327 These registers are used by some versions of the host interface 328 protocol specification. Their names should probably be changed 329 to hide the registers and to expose the functions more. 330 */ 331 /* COEX_STATUS 332 333 Coex status register, contains interrupt status and reset 334 pullup status. The latter is used to detect WAPI. 335 */ 336 /* PROGRAM_MEMORY_RAM_OFFSET 337 PROGRAM_MEMORY_ROM_OFFSET 338 PROGRAM_MEMORY_FLASH_OFFSET 339 PROGRAM_MEMORY_EXT_SRAM_OFFSET 340 DATA_MEMORY_RAM_OFFSET 341 342 These are constants that describe the offset of the different 343 memory types in the two different address spaces. 344 */ 345 /* HasFlash HasExtSram HasRom 346 HasBt HasWLan 347 348 These are a set of bools describing the chip. 349 */ 350 /* WINDOW_ADDRESS WINDOW_SIZE 351 352 These two functions return the size and address of the windows. 353 The address is the address of the lowest value in the address 354 map that is part of the window and the size is the number of 355 visible words. 356 357 Some of the windows have their lowest portion covered by 358 registers. For these windows address is the first address 359 after the registers and size is the siave excluding the part 360 covered by registers. 361 */ 362 /* MapAddress_SPI2HOST 363 MapAddress_HOST2SPI 364 365 The debugging interface is duplicated on UniFi and later chips 366 so that there are two versions - one over the SPI interaface and 367 the other over the SDIO interface. These functions map the 368 registers between these two interfaces. 369 */ 370 /* ClockStartupSequence 371 372 This function returns the list of register value pairs that 373 should be forced into UniFi to enable SPI communication. This 374 set of registers is not needed if the firmware is running, but 375 will be needed if the device is being booted from cold. These 376 register writes enable the clocks and setup the PLL to a basic 377 working state. SPI access might be unreliable until these writes 378 have occurred (And they may take mulitple goes). 379 */ 380 /* HostResetSequence 381 382 This returns a number of chunks of data and generic pointers. 383 All of the XAPs should be stopped. The data should be written 384 to the generic pointers. The instruction pointer for the MAC 385 should then be set to the start of program memory and then the 386 MAC should be "go"d. This will reset the chip in a reliable 387 and orderly manner without resetting the SDIO interface. It 388 is therefore not needed if the chip is being accessed by the 389 SPI interface (the DBG_RESET_ mechanism can be used instead). 390 */ 391 392 /* The Decode Window function is more complex. For the window 393 'window' it tries to return the address and page register 394 value needed to see offset 'offset' of memory type 'type'. 395 396 It return 1 on success and 0 on failure. 'page' is what 397 should be written to the page register. 'addr' is the 398 address in the XAPs 16 address map to read from. 'len' 399 is the length that we can read without having to change 400 the page registers. */ 401 s32 ChipHelper_DecodeWindow(ChipDescript *chip_help, 402 enum chip_helper_window_index window, 403 enum chip_helper_window_type type, 404 u32 offset, 405 u16 *page, u16 *addr, u32 *len); 406 407 #endif 408