gc/ogc/exi.h

   1 /*-------------------------------------------------------------
   2
   3 exi.h -- EXI subsystem
   4
   5 Copyright (C) 2004
   6 Michael Wiedenbauer (shagkur)
   7 Dave Murphy (WinterMute)
   8
   9 This software is provided 'as-is', without any express or implied
  10 warranty.  In no event will the authors be held liable for any
  11 damages arising from the use of this software.
  12
  13 Permission is granted to anyone to use this software for any
  14 purpose, including commercial applications, and to alter it and
  15 redistribute it freely, subject to the following restrictions:
  16
  17 1.      The origin of this software must not be misrepresented; you
  18 must not claim that you wrote the original software. If you use
  19 this software in a product, an acknowledgment in the product
  20 documentation would be appreciated but is not required.
  21
  22 2.      Altered source versions must be plainly marked as such, and
  23 must not be misrepresented as being the original software.
  24
  25 3.      This notice may not be removed or altered from any source
  26 distribution.
  27
  28 -------------------------------------------------------------*/
  29
  30
  31 #ifndef __EXI_H__
  32 #define __EXI_H__
  33
  34 /*!
  35 \file exi.h
  36 \brief EXI subsystem
  37
  38 */
  39
  40
  41 #include "gctypes.h"
  42
  43 /*!
  44  * \addtogroup exi_tx_mode EXI tranfer types
  45  * @{
  46  */
  47
  48 #define EXI_READ                                        0                       /*!< EXI transfer type read */
  49 #define EXI_WRITE                                       1                       /*!< EXI transfer type write */
  50 #define EXI_READWRITE                           2                       /*!< EXI transfer type read-write */
  51
  52 /*!
  53  * @}
  54  */
  55
  56
  57 /*!
  58  * \addtogroup exi_channels EXI channels
  59  * @{
  60  */
  61
  62 #define EXI_CHANNEL_0                           0                       /*!< EXI channel 0 (memory card slot A) */
  63 #define EXI_CHANNEL_1                           1                       /*!< EXI channel 1 (memory card slot B) */
  64 #define EXI_CHANNEL_2                           2                       /*!< EXI channel 2 (other EXI devices connected, e.g. BBA) */
  65 #define EXI_CHANNEL_MAX                         3                       /*!< _Termination */
  66
  67 /*!
  68  * @}
  69  */
  70
  71
  72 /*!
  73  * \addtogroup exi_devices EXI devices
  74  * @{
  75  */
  76
  77 #define EXI_DEVICE_0                            0                       /*!< EXI device 0 */
  78 #define EXI_DEVICE_1                            1                       /*!< EXI device 1 */
  79 #define EXI_DEVICE_2                            2                       /*!< EXI device 2 */
  80 #define EXI_DEVICE_MAX                          3                       /*!< _Termination */
  81
  82 /*!
  83  * @}
  84  */
  85
  86
  87 /*!
  88  * \addtogroup exi_speed EXI device frequencies
  89  * @{
  90  */
  91
  92 #define EXI_SPEED1MHZ                           0                       /*!< EXI device frequency 1MHz */
  93 #define EXI_SPEED2MHZ                           1                       /*!< EXI device frequency 2MHz */
  94 #define EXI_SPEED4MHZ                           2                       /*!< EXI device frequency 4MHz */
  95 #define EXI_SPEED8MHZ                           3                       /*!< EXI device frequency 8MHz */
  96 #define EXI_SPEED16MHZ                          4                       /*!< EXI device frequency 16MHz */
  97 #define EXI_SPEED32MHZ                          5                       /*!< EXI device frequency 32MHz */
  98
  99 /*!
 100  * @}
 101  */
 102
 103
 104 /*!
 105  * \addtogroup exi_flags EXI device operation flags
 106  * @{
 107  */
 108
 109 #define EXI_FLAG_DMA                            0x0001          /*!< EXI DMA mode transfer in progress */
 110 #define EXI_FLAG_IMM                            0x0002          /*!< EXI immediate mode transfer in progress */
 111 #define EXI_FLAG_SELECT                         0x0004          /*!< EXI channel and device selected */
 112 #define EXI_FLAG_ATTACH                         0x0008          /*!< EXI device on selected channel and device attached */
 113 #define EXI_FLAG_LOCKED                         0x0010          /*!< EXI channel and device locked for device operations */
 114
 115 /*!
 116  * @}
 117  */
 118
 119
 120 /*!
 121  * \addtogroup exi_mcident EXI memory card identifier
 122  * @{
 123  */
 124
 125 #define EXI_MEMCARD59                           0x00000004      /*!< Nintendo memory card:   64/  4/ 0.5 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 126 #define EXI_MEMCARD123                          0x00000008      /*!< Nintendo memory card:  128/  8/ 1.0 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 127 #define EXI_MEMCARD251                          0x00000010      /*!< Nintendo memory card:  256/ 16/ 2.0 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 128 #define EXI_MEMCARD507                          0x00000020      /*!< Nintendo memory card:  512/ 32/ 4.0 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 129 #define EXI_MEMCARD1019                         0x00000040      /*!< Nintendo memory card: 1024/ 64/ 8.0 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 130 #define EXI_MEMCARD2043                         0x00000080      /*!< Nintendo memory card: 2048/128/16.0 (blocks/Mbits/MB). 3rd party vendors do have the same identification */
 131
 132 /*!
 133  * @}
 134  */
 135
 136
 137 #ifdef __cplusplus
 138    extern "C" {
 139 #endif /* __cplusplus */
 140
 141 /*! \typedef s32 (*EXICallback)(s32 chn,s32 dev)
 142 \brief function pointer typedef for the user's EXI callback
 143 \param chn EXI channel
 144 \param dev EXI device
 145 */
 146 typedef s32 (*EXICallback)(s32 chn,s32 dev);
 147
 148
 149 /*! \fn s32 EXI_ProbeEx(s32 nChn)
 150 \brief Performs an extended probe of the EXI channel
 151 \param[in] nChn EXI channel to probe
 152
 153 \return 1 on success, <=0 on error
 154 */
 155 s32 EXI_ProbeEx(s32 nChn);
 156
 157
 158 /*! \fn s32 EXI_Probe(s32 nChn)
 159 \brief Probes the EXI channel
 160 \param[in] nChn EXI channel to probe
 161
 162 \return 1 on success, <=0 on error
 163 */
 164 s32 EXI_Probe(s32 nChn);
 165
 166
 167 /*! \fn s32 EXI_Lock(s32 nChn,s32 nDev,EXICallback unlockCB)
 168 \brief Try to lock the desired EXI channel on the given device.
 169 \param[in] nChn EXI channel to lock
 170 \param[in] nDev EXI device to lock
 171 \param[in] unlockCB pointer to callback to call when EXI_Unlock() is called. Thus allowing us a small way of mutual exclusion.
 172
 173 \return 1 on success, <=0 on error
 174 */
 175 s32 EXI_Lock(s32 nChn,s32 nDev,EXICallback unlockCB);
 176
 177
 178 /*! \fn s32 EXI_Unlock(s32 nChn)
 179 \brief Unlock the desired EXI channel.
 180 \param[in] nChn EXI channel to unlock
 181
 182 \return 1 on success, <=0 on error
 183 */
 184 s32 EXI_Unlock(s32 nChn);
 185
 186
 187 /*! \fn s32 EXI_Select(s32 nChn,s32 nDev,s32 nFrq)
 188 \brief Selects the spedified EXI channel on the given device with the given frequency
 189 \param[in] nChn EXI channel to select
 190 \param[in] nDev EXI device to select
 191 \param[in] nFrq EXI frequency to select
 192
 193 \return 1 on success, <=0 on error
 194 */
 195 s32 EXI_Select(s32 nChn,s32 nDev,s32 nFrq);
 196
 197
 198 /*! \fn s32 EXI_SelectSD(s32 nChn,s32 nDev,s32 nFrq)
 199 \brief Performs a special select, for SD cards or adapters respectively, on the given device with the given frequence
 200 \param[in] nChn EXI channel to select
 201 \param[in] nDev EXI device to select
 202 \param[in] nFrq EXI frequency to select
 203
 204 \return 1 on success, <=0 on error
 205 */
 206 s32 EXI_SelectSD(s32 nChn,s32 nDev,s32 nFrq);
 207
 208
 209 /*! \fn s32 EXI_Deselect(s32 nChn)
 210 \brief Deselects the EXI channel.
 211 \param[in] nChn EXI channel to deselect
 212
 213 \return 1 on success, <=0 on error
 214 */
 215 s32 EXI_Deselect(s32 nChn);
 216
 217
 218 /*! \fn s32 EXI_Sync(s32 nChn)
 219 \brief Synchronize or finish respectively the last EXI transfer.
 220 \param[in] nChn EXI channel to select
 221
 222 \return 1 on success, <=0 on error
 223 */
 224 s32 EXI_Sync(s32 nChn);
 225
 226
 227 /*! \fn s32 EXI_Imm(s32 nChn,void *pData,u32 nLen,u32 nMode,EXICallback tc_cb)
 228 \brief Initializes an immediate mode EXI transfer.
 229 \param[in] nChn EXI channel to select
 230 \param[in,out] pData pointer to a buffer to read/copy from/to data.
 231 \param[in] nLen lenght of data to transfer <=4.
 232 \param[in] nMode direction of transferoperation(EXI_READ,EXI_WRITE,EXI_READWRITE)
 233 \param[in] tc_cb pointer to a callback to call when transfer has completed. May be NULL.
 234
 235 \return 1 on success, <=0 on error
 236 */
 237 s32 EXI_Imm(s32 nChn,void *pData,u32 nLen,u32 nMode,EXICallback tc_cb);
 238
 239
 240 /*! \fn s32 EXI_ImmEx(s32 nChn,void *pData,u32 nLen,u32 nMode)
 241 \brief Initializes an extended immediate mode EXI transfer.
 242 \param[in] nChn EXI channel to select
 243 \param[in,out] pData pointer to a buffer to read/copy from/to data.
 244 \param[in] nLen lenght of data to transfer.
 245 \param[in] nMode direction of transferoperation(EXI_READ,EXI_WRITE,EXI_READWRITE)
 246
 247 \return 1 on success, <=0 on error
 248 */
 249 s32 EXI_ImmEx(s32 nChn,void *pData,u32 nLen,u32 nMode);
 250
 251
 252 /*! \fn s32 EXI_Dma(s32 nChn,void *pData,u32 nLen,u32 nMode,EXICallback tc_cb)
 253 \brief Initializes a DMA mode EXI transfer.
 254 \param[in] nChn EXI channel to select
 255 \param[in,out] pData pointer to a buffer to read/copy from/to data.
 256 \param[in] nLen lenght of data to transfer.
 257 \param[in] nMode direction of transferoperation(EXI_READ,EXI_WRITE,EXI_READWRITE)
 258 \param[in] tc_cb pointer to a callback to call when transfer has completed. May be NULL.
 259
 260 \return 1 on success, <=0 on error
 261 */
 262 s32 EXI_Dma(s32 nChn,void *pData,u32 nLen,u32 nMode,EXICallback tc_cb);
 263
 264
 265 /*! \fn s32 EXI_GetState(s32 nChn)
 266 \brief Get the EXI state
 267 \param[in] nChn EXI channel to select
 268
 269 \return EXI channels state flag.
 270 */
 271 s32 EXI_GetState(s32 nChn);
 272
 273
 274 /*! \fn s32 EXI_GetID(s32 nChn,s32 nDev,u32 *nId)
 275 \brief Get the ID of the connected EXI device on the given channel
 276 \param[in] nChn EXI channel to select
 277 \param[in] nDev EXI device to select
 278 \param[out] nId EXI device ID to return.
 279
 280 \return 1 on success, <=0 on error
 281 */
 282 s32 EXI_GetID(s32 nChn,s32 nDev,u32 *nId);
 283
 284
 285 /*! \fn s32 EXI_Attach(s32 nChn,EXICallback ext_cb)
 286 \brief Attach the device on the given channel
 287 \param[in] nChn EXI channel to select
 288 \param[in] ext_cb pointer to callback to call when device is physically removed.
 289
 290 \return 1 on success, <=0 on error
 291 */
 292 s32 EXI_Attach(s32 nChn,EXICallback ext_cb);
 293
 294
 295 /*! \fn s32 EXI_Detach(s32 nChn)
 296 \brief Detach the device on the given channel
 297 \param[in] nChn EXI channel to select
 298
 299 \return 1 on success, <=0 on error
 300 */
 301 s32 EXI_Detach(s32 nChn);
 302
 303
 304 /*! \fn void EXI_ProbeReset()
 305 \brief Resets certain internal flags and counters and performs a probe on all 3 channels.
 306
 307 \return nothing
 308 */
 309 void EXI_ProbeReset();
 310
 311
 312 /*! \fn EXICallback EXI_RegisterEXICallback(s32 nChn,EXICallback exi_cb)
 313 \brief Register a callback function in the EXI driver for the EXI interrupt.
 314 \param[in] nChn EXI channel to select
 315 \param[in] exi_cb pointer to the function which to call when EXI interrupt has triggered.
 316
 317 \return old callback function pointer or NULL
 318 */
 319 EXICallback EXI_RegisterEXICallback(s32 nChn,EXICallback exi_cb);
 320
 321 #ifdef __cplusplus
 322    }
 323 #endif /* __cplusplus */
 324
 325 #endif