1 /*****************************************************************************
3 (c) Cambridge Silicon Radio Limited 2011
4 All rights reserved and confidential information of CSR
6 Refer to LICENSE.txt included with this source for details
9 *****************************************************************************/
11 #ifndef CSR_WIFI_HIP_CHIPHELPER_H__
12 #define CSR_WIFI_HIP_CHIPHELPER_H__
15 #include <linux/types.h>
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
21 chip_helper_bluecore_pre_bc7,
22 chip_helper_bluecore_bc7_or_later
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
29 CHIP_HELPER_WINDOW_1 = 0,
30 CHIP_HELPER_WINDOW_2 = 1,
31 CHIP_HELPER_WINDOW_3 = 2,
32 CHIP_HELPER_WINDOW_COUNT = 3
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
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
47 /* Commands to stop and start the XAP */
48 enum chip_helper_dbg_emu_cmd_enum
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
56 /* Bitmasks for Stop and sleep status: DBG_SPI_STOP_STATUS & DBG_HOST_STOP_STATUS */
57 enum chip_helper_dbg_stop_status_enum
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
75 /* Codes to disable the watchdog */
76 enum chip_helper_watchdog_disable_enum
78 CHIP_HELPER_WATCHDOG_DISABLE_CODE1 = 0x6734,
79 CHIP_HELPER_WATCHDOG_DISABLE_CODE2 = 0xD6BF,
80 CHIP_HELPER_WATCHDOG_DISABLE_CODE3 = 0xC31E
83 /* Other bits have changed between versions */
84 enum chip_helper_gbl_misc_enum
86 CHIP_HELPER_GBL_MISC_SPI_STOP_OUT_EN_MASK = 0x0001,
87 CHIP_HELPER_GBL_MISC_MMU_INIT_DONE_MASK = 0x0004
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
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
103 /* How to select the different CPUs */
104 enum chip_helper_dbg_proc_sel_enum
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
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
117 /* This is the address of GBL_CHIP_VERISON on BC7,
119 anything later than that. */
120 CHIP_HELPER_UNIFI_GBL_CHIP_VERSION = 0xFE81,
122 CHIP_HELPER_OLD_BLUECORE_GBL_CHIP_VERSION = 0xFF9A
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 */
129 /* Address-value pairs for defining initialisation values */
130 struct chip_helper_init_values
136 /* A block of data that should be written to the device */
137 struct chip_helper_reset_values
149 typedef const struct chip_device_desc_t ChipDescript;
151 /* Return a NULL descriptor */
152 ChipDescript* ChipHelper_Null(void);
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.
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);
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);
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);
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,
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.
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).
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))
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
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);
258 CHIP_HELPER_LIST(C_DEC)
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.
275 These registers are used to control the XAPs.
277 /* DBG_HOST_PROC_SELECT DBG_HOST_STOP_STATUS
278 HOST_WINDOW1_PAGE HOST_WINDOW2_PAGE HOST_WINDOW3_PAGE
280 DBG_SPI_PROC_SELECT DBG_SPI_STOP_STATUS
281 SPI_WINDOW1_PAGE SPI_WINDOW2_PAGE SPI_WINDOW3_PAGE
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.
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
305 This register controls some special chip features. It
306 should be used with care is it changes quite a lot between
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.
318 /* SDIO_HIP_HANDSHAKE
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.
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.
333 Coex status register, contains interrupt status and reset
334 pullup status. The latter is used to detect WAPI.
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
342 These are constants that describe the offset of the different
343 memory types in the two different address spaces.
345 /* HasFlash HasExtSram HasRom
348 These are a set of bools describing the chip.
350 /* WINDOW_ADDRESS WINDOW_SIZE
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
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.
362 /* MapAddress_SPI2HOST
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.
370 /* ClockStartupSequence
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).
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).
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'.
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,
405 u16 *page, u16 *addr, u32 *len);