Pileus Git - ~andy/linux/blob - drivers/staging/csr/csr_wifi_hip_chiphelper.h

   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 thier 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 occured (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