home *** CD-ROM | disk | FTP | other *** search
/ Enigma Amiga Life 109 / EnigmaAmiga109CD.iso / software / sviluppo / mccontrol / modules / modules.doc < prev    next >
Text File  |  2000-02-09  |  15KB  |  408 lines
  1. ;----------------------------------------------------------------------------
  2. ;This is not an documentation how to use the .mcm modules in your own
  3. ;software! Its an documentation about how to write modules for other
  4. ;card reader.
  5. ;----------------------------------------------------------------------------
  6. TABLE OF CONTENTS
  7.  
  8. MCControlModule/General
  9. MCControlModule/Module_Delay
  10. MCControlModule/Module_Open
  11. MCControlModule/Module_FrameOpen
  12. MCControlModule/Module_FrameClose
  13. MCControlModule/Module_ReadCommand
  14. MCControlModule/Module_WriteCommand
  15. MCControlModule/Module_PADOpen
  16. MCControlModule/Module_PADClose
  17. MCControlModule/Module_PADCommand
  18. MCControlModule/Module_DirectFrame
  19. MCControlModule/Module_DirectPage
  20. ;----------------------------------------------------------------------------
  21.  *General*
  22.  
  23. First the main structure:
  24.  
  25.         RSRESET
  26. Module_RTS                   rs.w 1 ;to avoid crash when user is starting module
  27. Module_Version               rs.w 1 ;Currently 1
  28. Module_ID                    rs.l 1 ;must be "MCCM"
  29. Module_Flags                 rs.l 1 ;see below (unused flags must be zero)
  30. Module_Exec_Base             rs.l 1 ;Filled by MCControl
  31. Module_Dos_Base              rs.l 1 ;Filled by MCControl
  32. Module_Intuition_Base        rs.l 1 ;Filled by MCControl
  33. ;--- Card Data
  34. Module_DelayReadByte         rs.l 1 ;Filled by MCControl
  35. Module_DelayReadBit          rs.l 1 ;Filled by MCControl
  36. Module_DelayWriteByte        rs.l 1 ;Filled by MCControl
  37. Module_DelayWriteBit         rs.l 1 ;Filled by MCControl
  38. Module_Reserved1             rs.l 10 ;reserved (must be ZERO)
  39. ;--- Jump Table
  40. Module_Delay                 rs.w 3 ;Filled by MCControl
  41. Module_Open                  rs.w 3
  42. Module_Close                 rs.w 3
  43. Module_FrameOpen             rs.w 3
  44. Module_FrameClose            rs.w 3
  45. Module_ReadCommand           rs.w 3
  46. Module_WriteCommand          rs.w 3
  47. Module_PADOpen               rs.w 3
  48. Module_PADClose              rs.w 3
  49. Module_PADCommand            rs.w 3
  50. Module_DirectFrame           rs.w 3
  51. Module_DirectPage            rs.w 3
  52. Module_Reserved2             rs.w 3*8 ;reserved
  53. Module_SIZEOF                rs.b 0
  54. ;----------------------------------------------------------------------------
  55.  BITDEF Module,Delay,0         ;Tell MCControl you require timing data.
  56.  BITDEF Module,Device,1        ;Tell MCControl you require an Device/Unit
  57.                                ;selector
  58.  BITDEF Module,MultiPage,2     ;Tell MCControl you support MultiPage cards
  59.  BITDEF Module,DirectAccess,3  ;Tell MCControl you support DirectAccess support
  60.  BITDEF Module,MultiSlot,4     ;Tell MCControl you support more than one slot.
  61. ;----------------------------------------------------------------------------
  62. Module_Error_NoError       = 0
  63. Module_Error_OpenDevice    = 1
  64. Module_Error_NotCompatible = 2 ;If hardware supports identification!
  65. Module_Error_NoTimerDevice = 3 ;If you need the timer.device and opening fails
  66. Module_Error_OutOfMemory   = 20
  67. ;----------------------------------------------------------------------------
  68. Module_DirectFrame_Read    = 0
  69. Module_DirectFrame_Write   = 1
  70. ;----------------------------------------------------------------------------
  71. Module_DirectPage_Next     = 0
  72. Module_DirectPage_Prev     = 1
  73. ;----------------------------------------------------------------------------
  74.  
  75.  NOTES 
  76.  
  77.    The exec, dos and intuition  bases  are  for  free  usage.  This  saves
  78.    memory,  time and of cource code size. The card data is for free usage,
  79.    too.
  80.  
  81.    Beside the arguments delivered for  each  function  you´ll  receive  an
  82.    pointer on the module itself in register A4!
  83.  
  84.    Make sure to backup a2-a5 and d2-d7 just like the Amiga-OS is doing!
  85.  
  86.    You must implement port and device allocation into Module_Open()! Don´t
  87.    try  to  play  with  the hardware without owning the right to do so. If
  88.    possible try to use parallel.device or serial.device. (The user defined
  89.    device will be given during Module_Open().
  90.        
  91.    It´s not required to create an real  jumptable,  by  using  JMPs.  Feel
  92.    free, to use an BRA followed by an NOP. (See RamCard.mcm)
  93.        
  94.    It´s strongly required  to  implement  all  given  jumps.  (except  the
  95.    Module_Delay).
  96.  
  97.    Implement the code as fast as possible, because its used for many times
  98.    during reading and writing memory cards. Try to avoid overhead by using
  99.    Module_Open, or if not possible Module_FrameOpen.
  100.  
  101.    Feel free to use the Module_Delay function even  if  the  ModuleF_Delay
  102.    flags  isn´t  set!  The  flag  only  deactivates the gadgets and avoids
  103.    filling out the timing sheet (Module_DelayXY)!
  104.        
  105.    Your reader expects only a frame number and returns a  complete  frame?
  106.    Well,  this  isn´t  a problem. Set the Module_Flag ModuleF_DirectAccess
  107.    and MCControl is using Module_DirectFrame insteed of  Module_FrameOpen,
  108.    Module_FrameClose,    Module_ReadCommand    and    Module_WriteCommand!
  109.    Module_DirectFrame is doing the same job for reading and writing.  Just
  110.    take a look on my RamCard.mcm as an DirectFrame example.
  111.  
  112.    If you need help then ask me and I´am telling you what to  do.  If  you
  113.    don´t  know how to code a driver then send me your information and I´ll
  114.    do my very best.
  115.  
  116. ;----------------------------------------------------------------------------
  117. MCControlModule/Module_Delay
  118.  
  119.    NAME
  120.                  Module_Delay
  121.         
  122.    SYNOPSIS
  123.                  Module_Delay(Time);
  124.                               D0
  125.  
  126.                  Module_Delay(ULONG);
  127.  
  128.    FUNCTION
  129.                  Standard MCControl timer for high speed delay
  130.                  calculations.
  131.  
  132.    INPUTS
  133.                  Time faktor (use Module_Delay#? field for getting
  134.                  values. The delay is on all systems nearly identicaly.
  135.    WARNING
  136.                  Due multi tasking it is possible that this delay is
  137.                  much longer, but this should be no problem.
  138. ;----------------------------------------------------------------------------
  139. MCControlModule/Module_Open
  140.  
  141.    NAME
  142.                  Module_Open -- open and inits the module
  143.  
  144.    SYNOPSIS
  145.                  Error   = Module_Open(Device, Unit)
  146.                  D0                    a0,     d0
  147.  
  148.                  (ULONG) = Module_Open(*UBYTE,ULONG)
  149.    FUNCTION
  150.                  Open the required device and alloc additional memory
  151.                  if needed.
  152.    INPUTS
  153.                  Device: Pointer on device name (STRING IS READ ONLY!!!)
  154.                  Unit:   Unit of the given device
  155.    RESULT
  156.                   0 = No Error
  157.                   1 = Open device error
  158.                   2 = Not compatible
  159.                  20 = Out of memory
  160.  
  161.                  Other results are currently not allowed!!
  162.    NOTES
  163.                  Device and Unit are only valid if the Device-Flag within
  164.                  the module structure (Module_Flags) is set.
  165.  
  166.    SEE ALSO
  167.                  Module_Close()
  168. ;----------------------------------------------------------------------------
  169. MCControlModule/Module_Close
  170.  
  171.    NAME
  172.                  Module_Close -- free all data and close all devices.
  173.  
  174.    SYNOPSIS
  175.                  Module_Close()
  176.  
  177.    FUNCTION
  178.                  Close all devices and free all allocated memory .
  179.    NOTES
  180.                  Module_Close must be save to be called more than
  181.                  one time. This means you must detect an closing of
  182.                  an just closed module. In this case you must return
  183.                  without any action.
  184.    SEE ALSO
  185.                  Module_Open()
  186. ;----------------------------------------------------------------------------
  187. MCControlModule/Module_FrameOpen
  188.  
  189.    NAME
  190.                  Module_FrameOpen -- Prepare for frame read/write
  191.  
  192.    SYNOPSIS
  193.                  Error   = Module_FrameOpen(Slot)
  194.                  D0                          D0
  195.  
  196.                  (ULONG) = Module_FrameOpen(UWORD);
  197.  
  198.    INPUTS
  199.                  Slot: (0-x) Number of slot to access!
  200.  
  201.    RESULT
  202.                   0 = No Error
  203.                   1 = Slot not available
  204.                  -1 = Other Error (you shouldn´t need to use this)
  205.  
  206.                  Other results are currently not allowed!!
  207.  
  208.    FUNCTION
  209.                  No special function. Just do what is required to
  210.                  access the given slot. Standard.mcm is using this
  211.                  function to active the select line of the given
  212.                  slot. RamCard.mcm is resetting data buffers only.
  213.    SEE ALSO
  214.                  Module_FrameClose()
  215. ;----------------------------------------------------------------------------
  216. MCControlModule/Module_FrameClose
  217.  
  218.    NAME
  219.                  Module_FrameClose -- frame read/write done
  220.  
  221.    SYNOPSIS
  222.                  Module_FrameClose()
  223.  
  224.    FUNCTION
  225.                  No special function. Just do what is required after
  226.                  reading a frame. Standard.mcm is using this
  227.                  function to deactive all select lines slot.
  228.    SEE ALSO
  229.                  Module_FrameOpen()
  230. ;----------------------------------------------------------------------------
  231. MCControlModule/Module_ReadCommand
  232.  
  233.    NAME
  234.                  Module_ReadCommand -- Send command and get answer
  235.  
  236.    SYNOPSIS
  237.                  Result = Module_ReadCommand(Command)
  238.                  D0                          D0
  239.  
  240.                  BYTE   = Module_ReadCommand(BYTE)
  241.  
  242.    FUNCTION
  243.                  Command will be transfered to memory card. The
  244.                  card answer will be returned to Result.
  245.  
  246.    NOTES
  247.                  There is no need to implement different routines
  248.                  for Module_ReadCommand and Module_WriteCommand.
  249.                  Internaly these commands are working equal. The
  250.                  only difference is that the ReadCommand is used
  251.                  when reading frames and the WriteCommand on writing
  252.                  frames. This allows to use different delays for
  253.                  reading and writing. If you hardware isn´t using
  254.                  any different delays use the same routine
  255.                  for both commands.
  256.  
  257.    SEE ALSO
  258.                  Module_WriteCommand()
  259. ;----------------------------------------------------------------------------
  260. MCControlModule/Module_WriteCommand
  261.  
  262.    NAME
  263.                  Module_WriteCommand -- Send command and get answer
  264.  
  265.    SYNOPSIS
  266.                  Result = Module_WriteCommand(Command)
  267.                  D0                           D0
  268.  
  269.                  BYTE = Module_WriteCommand(BYTE)
  270.  
  271.    FUNCTION
  272.                  Command will be transfered to memory card. The
  273.                  card answer will be returned to Result.
  274.  
  275.    NOTES
  276.                  There is no need to implement different routines
  277.                  for Module_ReadCommand and Module_WriteCommand.
  278.                  Internaly these commands are working equal. The
  279.                  only difference is that the ReadCommand is used
  280.                  when reading frames and the WriteCommand on writing
  281.                  frames. This allows to use different delays for
  282.                  reading and writing. If you hardware isn´t using
  283.                  any different delays use the same routine
  284.                  for both commands.
  285.                        
  286.    SEE ALSO
  287.                  Module_ReadCommand()
  288. ;----------------------------------------------------------------------------
  289. MCControlModule/Module_PADOpen
  290.  
  291.    NAME
  292.                  Module_PADOpen -- Prepare for PAD emulation
  293.  
  294.    SYNOPSIS
  295.                  Error   = Module_PADOpen()
  296.                  d0
  297.  
  298.                  (LONG)  = Module_PADOpen()
  299.  
  300.    RESULT
  301.                  0 = No Error
  302.                  Other results are currently not allowed!!
  303.  
  304.    FUNCTION
  305.                  Again! There is no predefined function for this
  306.                  function. Just do what is required or even nothing.
  307.                  Standard.mcm is using this function to set all
  308.                  IO ports to output.
  309.    SEE ALSO
  310.                  Module_PADClose()
  311. ;----------------------------------------------------------------------------
  312. MCControlModule/Module_PADClose
  313.  
  314.    NAME
  315.                  Module_PADClose -- PAD emulation done
  316.  
  317.    SYNOPSIS
  318.                  Module_PADClose()
  319.  
  320.    FUNCTION
  321.                  Again there is no predefined function for this
  322.                  function. Just do what is required or even nothing.
  323.                  Standard.mcm is using this function to reset all
  324.                  IO ports to default.
  325.    SEE ALSO
  326.                  Module_PADClose()
  327. ;----------------------------------------------------------------------------
  328. MCControlModule/Module_PADCommand
  329.  
  330.    NAME
  331.                  Module_PADCommand -- Simulate PAD
  332.  
  333.    SYNOPSIS
  334.                  Module_PADCommand(Command,Answer)
  335.                                    D0,     D1
  336.  
  337.                  Module_PADCommand(BYTE   ,BYTE)
  338.         
  339.    FUNCTION
  340.                  Well, this is a little tricky. You must send the
  341.                  Command on the command line, while simulating
  342.                  an PSX Pad answer on the Dataline by using Answer.
  343.                         
  344.                  The card will think its hearing the playstation is
  345.                  talking to a card and vice versa.
  346.    SEE ALSO
  347.                  Module_PADOpen(), Module_PADClose()
  348. ;----------------------------------------------------------------------------
  349. MCControlModule/Module_DirectFrame
  350.  
  351.    NAME
  352.                  Module_DirectFrame -- Handle 1 frame at once
  353.  
  354.    SYNOPSIS
  355.                  Error   = Module_DirectFrame(Frame,Mode,Data)
  356.                  D0                           D0,   D1,  A0
  357.  
  358.                  (LONG)  = Module_DirectFrame(WORD, LONG,*Byte)
  359.  
  360.    INPUTS
  361.                  Frame: Frame number to read or write!
  362.                  Mode:  Module_DirectFrame_Read or Module_DirectFrame_Write
  363.                  Data:  Pointer on Buffer!
  364.  
  365.    RESULT
  366.                   0 = Ok
  367.                  -1 = ERROR
  368.  
  369.                  Other results are currently not allowed!!
  370.  
  371.    FUNCTION
  372.                  Read or write the given frame (128 bytes)!
  373.  
  374.    NOTE
  375.                  Data must be 128 bytes long!
  376.                  This function requires the flag: ModuleF_DirectAccess!
  377.                  Otherwise MCControl is ignoring this routine.
  378. ;----------------------------------------------------------------------------
  379. MCControlModule/Module_DirectPage
  380.  
  381.    NAME
  382.                  Module_DirectPage -- Handle page swapping
  383.  
  384.    SYNOPSIS
  385.                  Error   = Module_DirectPage(Offset,Mode)
  386.                  D0                          D0,    D1
  387.  
  388.                  (LONG)  = Module_DirectPage(WORD, LONG)
  389.  
  390.    INPUTS
  391.                  Offset: Number of pages to jump!
  392.                  Mode:   Module_DirectPage_Next or Module_DirectPage_Prev
  393.  
  394.    RESULT
  395.                   0 = Ok
  396.                  -1 = ERROR
  397.  
  398.                  Other results are currently not allowed!!
  399.    FUNCTION
  400.                  Change activ card page of an multipage MemoryCard!
  401.  
  402.    NOTE
  403.                  This function requires the flag: ModuleF_DirectAccess!
  404.                  Otherwise MCControl is ignoring this routine.
  405.  
  406. ;----------------------------------------------------------------------------
  407.  
  408.