home *** CD-ROM | disk | FTP | other *** search
/ No Fragments Archive 10: Diskmags / nf_archive_10.iso / MAGS / ST_NEWS / STN_01_C.MSA / DATA_DOC20 < prev    next >
Text File  |  1994-03-14  |  16KB  |  461 lines
  1.  üALL ABOUT XBIOS FUNCTIONS Çby Richard Karsmakers
  2.  
  3. Originally  published  in üST NEWSÇ Volume 1 Issue  5,  launched  on 
  4. October 5th 1986.
  5.  
  6. In  the  previous issues of üST NEWSÇ we already had a  little  chat 
  7. concerning  System Variables,  BIOS routines and GEMDOS  routines; 
  8. this  time,  we'll  have  an  in-depth  look  at  XBIOS  routines, 
  9. sometimes  called  EBIOS routines - it stands for  Extended  BIOS. 
  10. These functions are there to enable the programmer to use specific 
  11. hardware characteristics of the Atari ST. For MC68000 programmers, 
  12. it  is  handy to know that TRAP #14 is needed  for  calling  these 
  13. routines. Thereby, the function number must be put on the stack.
  14. While  writing  this article,  we made use of  Data  Becker's  "ST 
  15. Intern" (ISBN 3-89011-119-X,  Data Becker,  Merowingestr. 30, 4000 
  16. Düsseldorf,  West  Germany;  in Holland:  Postbus 8411,  3503  RK, 
  17. Utrecht,  Tel.  030-430254). If you want to know äeverything Ç about 
  18. XBIOS functions,  you should buy that publication; it's a must for 
  19. all serious ST programmers/users.  In this article,  we will  only 
  20. have a look at how to program these routines from assembler. All C 
  21. freaks will definately have to get "ST Intern", as will the people 
  22. that want better examples....
  23. In each example, you might wonder why we added the last line, that 
  24. usually  includes  an  'add'  instruction.   This  instruction  is 
  25. necessary  to  clear the stack (as far as  I've  understood).  The 
  26. number that goes with it, can be calculated as follows:
  27. Each .l you put on the stack: +4
  28. Each .w you put on the stack: +2
  29. Each .b you put on the stack: +1
  30. See? Now, let's go on.....
  31.  
  32. ü0 initmousÇ
  33.  
  34. Example: move.l vector,-(sp)
  35.          move.l parameter,-(sp)
  36.          move.w type,-(sp)
  37.          move.w #0,-(sp)
  38.          trap #14
  39.          add.l#12,sp
  40.  
  41. This  function can be used to initialize all routines that  handle 
  42. the mouse.
  43.  
  44.  
  45. 'vector'  is  the  address  of a routine that  is  called  by  the 
  46.  keyboard processor when a mouse-report occurs.
  47. 'type' can choose one of the following alternatives:
  48.          0        Disable Mouse
  49.          1        Enable Mouse, Relative mode
  50.          2        Enable Mouse, Absolute mode
  51.          3        Unused
  52.          4        enable Mouse, Keyboard mode
  53. 'parameter'  points  to a parameter block,  that is  built  up  as 
  54. follows:
  55.          char topmode
  56.          char buttons
  57.          char xparam
  58.          char yparam
  59. 'topmode' can have on of the following values:
  60.          0        Y=0 is located at the bottom corner
  61.          1        Y=0 is located at the top corner
  62. 'buttons'  is a parameter for the 'Set Mouse Buttons'  command  of 
  63. the  IKBD  (we  might publish an article about that  in  the  near 
  64. future as well).
  65.  
  66.  
  67. 'xparam' & 'yparam' are factors for the mouse movement.  When  you 
  68. have  choosen  'type' to be 2 (that means that you work  with  the 
  69. mouse in absolute mode),  vier additional parameters are added  to 
  70. the parameterblock:
  71.          int xmax
  72.          int ymax
  73.          int xstart
  74.          int ystart
  75. These  are  the x-and y-coördinates of the maximal  value  of  the 
  76. mouse,  and the other parameters specify the position at which the 
  77. mouse should originally be put.
  78.  
  79. ü1 ssbrkÇ
  80.  
  81. Example: move.w quantity,-(sp)
  82.          move.w #1,-(sp)
  83.          trap #14
  84.          addq.l #4,sp
  85.  
  86. This function may be used to allocate (reserve) a piece of memory.
  87.  
  88.  
  89. 'quantity'  is the number of bytes that should be  reserved.  That 
  90. chunk  of  memory will be allocated at the  top  of  memory.  This 
  91. function  should  be  called before the  Operating  System  starts 
  92. Initialization.
  93.  
  94. ü2 physbaseÇ
  95.  
  96. Example: move.w #2,-(sp)
  97.          trap #14
  98.          addq.l #2,sp
  99.  
  100. This function returns a longword,  that signifies the Base of  the 
  101. physical screen. On a 512 K machine, this would result in $78000.
  102.  
  103. ü3 logbaseÇ
  104.  
  105. Example: move.w #3,-(sp)
  106.          trap #14
  107.          addq.l #2,sp
  108.  
  109.  
  110.  
  111. This  function  sets  the  logical  base  of  screen  memory.  All 
  112. operations that use screen memory will be working on this part  of 
  113. memory.  If physical and logical screen memory are the  same,  you 
  114. will also be able to see what happens on the screen.  The function 
  115. returns  a  longword,  which will be $78000 if you have  a  512  K 
  116. machine.
  117.  
  118. ü4 getrezÇ
  119.  
  120. Example: move.w #4,-(sp)
  121.          trap #14
  122.          addq.l #2,sp
  123.  
  124. The 'getrez' function returns the screen resolution,  which can be 
  125. one of the following values:
  126.          0        Low Resolution (320x200 pixels; 16 colors)
  127.          1        Medium Resolution (640x200 pixels; 4 colors)
  128.          2        High Resolution (640x400 pixels; 2 colors)
  129.  
  130. ü
  131.  
  132.  
  133. 5 setscreenÇ
  134.  
  135. Example: move.w res,-(sp)
  136.          move.l physaddr,-(sp)
  137.          move.l logaddr,-(sp)
  138.          move.w #5,-(sp)
  139.          trap #14
  140.          add.l #12,sp
  141.  
  142. This function allows the user to change the screen parameters that 
  143. could  be  read  using  one of  the  three  functions  we  already 
  144. mentioned before. If one of those parameters should not be set, it 
  145. is necessary to enter a negative value. The parameters will be set 
  146. on the next Vertical Blank Interrupt (VBL).
  147.  
  148. ü6 setpaletteÇ
  149.  
  150. Example: move.l paletpntr,-(sp)
  151.          move.w #6,-(sp)
  152.          trap #14
  153.          addq.l #6,sp
  154.  
  155. This function enables you to load a new color  palette.  Therefore 
  156. you  must give a pointer to a table with color values (16  values, 
  157. all words).  The address of the pointer should be even. The colors 
  158. will  be loaded at the next VBL.  If you know how to  handle  this 
  159. routine quite well,  it's possible to simulate more then 16 colors 
  160. on  your screen at one time.  I think Magnetic Scrolls  used  this 
  161. trick on the first picture of "The Pawn" (which is said to use 500 
  162. colors!).  Examples:  $000 is black,  $777 is white,  $700 is red, 
  163. $070 is green and $007 is blue.
  164.  
  165. ü7 setcolor
  166.  
  167. ÇExample: move.w color,-(sp)
  168.          move.w colnumber,-(sp)
  169.          move.w #7,-(sp)
  170.          trap #14
  171.          addq.l #6,sp
  172.  
  173. This function makes it possible to change just one color at a time 
  174. (just  like  "Press  '1' or '2' to Start"  with  Michtron's  "Time 
  175. Bandit V2.0").
  176. 'colnumber' is the number of the color that should be changed.
  177. 'color' is the new value of that color, ranging from $000-$777.
  178. If you enter -1 as color,  you will simply get the old color value 
  179. of the color with the number 'colnumber'.
  180.  
  181. ü8 floprdÇ
  182.  
  183. Example: move.w count,-(sp)
  184.          move.w side,-(sp)
  185.          move.w track,-(sp)
  186.          move.w sector,-(sp)
  187.          move.w device,-(sp)
  188.          clr.l -(sp)
  189.          move.l buffer,-(sp)
  190.          move.w #8,-(sp)
  191.          trap #14
  192.          add.l #20,sp
  193.  
  194. This function enables the reading of one or several sectors from a 
  195. disk.
  196.  
  197.  
  198.  
  199. 'count' is the number of tracks that should be read  sequentially. 
  200. Values  between 1 and 9 are normally possible (number  of  sectors 
  201. per track),  but with maxi-formatted disks I see no reason why one 
  202. shouldn't use '10' as well.
  203. 'side' selects the side that should be read from. 0 is side A, and 
  204. 1 is side B.  On single sided floppy-drives (like the one I have - 
  205. snif, snif!) you can only use 0 - side A.
  206. 'track'  specifies the number of the track the sectors  should  be 
  207. read from. This value can vary; it depends on the number of tracks 
  208. per side.  Mostly,  this will be 80 (so the value can be from 0 to 
  209. 79),  but is can also be 40,  83,  or even another value (that  is 
  210. because  of  the flexibility of the Disk format for  Atari  system 
  211. disk drives).
  212. 'sector'  is the sector number of the sector that should  be  read 
  213. first.  Normally, this can be from 0-9, but sometimes it can be 10 
  214. as well (on maxi-formatted disks).
  215. 'device'  is  the number of the device the information  should  be 
  216. read from. This can be 0 (for drive A) or 1 (for drive B).
  217. The  line 'clr.l -(sp)' just puts an empty longword on the  stack. 
  218. This is unused.
  219. 'buffer'  is the address of a piece of memory where the data  read 
  220. should be put.  This should always be at a longword-boundary,  and 
  221. there  should  be enough room to put to info in (512 bytes  x  the 
  222. number of sectors you read).
  223. The 'floprd' function returns an error code. This can be:
  224.          0        OK
  225.         -1        General Error
  226.         -2        Drive not Ready
  227.         -3        Unknown command
  228.         -4        CRC Error
  229.         -5        Bad Request
  230.         -6        Seek Error
  231.         -7        Unknown Media
  232.         -8        Sector not Found
  233.         -9        (No Paper)
  234.        -10        Write Error
  235.        -11        Read Error
  236.        -12        General error
  237.        -13        Disk is Writeprotected
  238.        -14        Disk has been Changed
  239.        -15        Unknown Device
  240.        -16        Bad Sector
  241.        -17        Put Disk in Drive
  242.  
  243. ü9 flopwrÇ
  244.  
  245. Example: move.w count,-(sp)
  246.          move.w side,-(sp)
  247.          move.w track,-(sp)
  248.          move.w sector,-(sp)
  249.          move.w device,-(sp)
  250.          clr.l -(sp)
  251.          move.l buffer,-(sp)
  252.          move.w #9,-(sp)
  253.          trap #14
  254.          add.l #20,sp
  255.  
  256. This function enables the user to write one or several sectors  to 
  257. a  disk.  The parameters have the same meaning as those listed  at 
  258. function  8 (floprd).  This function also returns an  error  code, 
  259. which can also be one of those listed at the 'floprd' function.
  260.  
  261. ü
  262.  
  263.  
  264.  
  265. 10 flopfmtÇ
  266.  
  267. Example: move.w virgin.-(sp)
  268.          move.l magic,-(sp)
  269.          move.w interleave,-(sp)
  270.          move.w side,-(sp)
  271.          move.w track,-(sp)
  272.          move.w sectra,-(sp)
  273.          move.w device,-(sp)
  274.          clr.l -(sp)
  275.          move.l buffer,-(sp)
  276.          move.w #10,-(sp)
  277.          trap #14
  278.          add.l #26,sp
  279.  
  280. This routine can format one single track.  The parameters have the 
  281. following meaning:
  282. 'virgin'  is  the value with which all sectors  of  the  specified 
  283. track  will  be filled when formatted.  $E5E5 is mostly  used  for 
  284. this.  You  must  look  out not to use $F as value  for  the  high 
  285. nibble!
  286.  
  287. 'magic'  is the magic number (the ST is crawling with them!)  that 
  288. has  to  accompany the formatting.  In this case,  it  has  to  be 
  289. $87654321 (I suppose the people at Atari had a lack of originality 
  290. when  they used introduced this magic number;  some other  'magic' 
  291. numbers are birth-dates, BIOS launch-dates, etc.).
  292. 'interleave'  specified the sequence in which sectors are  written 
  293. to disk. Normally this is 1. I think the guy who designed Copystar 
  294. at RDS software used this variable for his "fast-load disk"-bit.
  295. 'side'  determines  the side on which the track  is  located  that 
  296. should be formatted. Ofcourse, one cannot select another value for 
  297. this than 0 if one has a single sided disk drive.
  298. 'track'  is  the  number of the track that  should  be  formatted. 
  299. Normally,  this will be 0-79,  but it can also be a higher  number 
  300. (even upto 83!).  Watch out:  if you want the track to be used for 
  301. program storage,  the boot sector must 'know' that there are  such 
  302. high  tracks!  Also,  not all disk drives are able to read  tracks 
  303. above number 79.  As a part of copy protection,  this function can 
  304. cause quite a lot of grey hairs with certain people.
  305. 'sectra'  is the number of sectors on that  track.  Unless  you're 
  306. designing  some hot-shot copy protection,  this should be  of  the 
  307. same  value that all other tracks are formatted  with.  This  will 
  308. normally be from 0 to 9, but it can also be 10.
  309. 'device'  is the device number (have a look at 'floprd' for  whihc 
  310. numbers you may use).
  311. 'clr.l -(sp)' is here used to put an empty - unused - longword  on 
  312. the stack,  just like its counterpart in the function 'floprd' and 
  313. 'flopwr'.
  314. 'buffer'  for  the complete trackdata.  If you use 9  sectors  per 
  315. track, this must be at least 8 Kb in size.
  316. The function returns an error code.  If it is -16,  bad sector, it 
  317. means that the data couldn't be properly verified.  In that  case, 
  318. the buffer will contain a list of bad sectors (seperated by  '0'). 
  319. You  can try to format the track again,  or you can mark  the  bad 
  320. sectors.
  321. Just like the 'floprd' and 'flopwr' functions,  you can check  for 
  322. an error with the following sequence:
  323.          tst d0
  324.          bmi error
  325.          ....Rest of the program
  326.    error ....Error handle routine
  327.  
  328. ü11 unused
  329.  
  330.  
  331. 12 midiws
  332. Ç
  333. Example: move.l pntr,-(sp)
  334.          move.w count,-(sp)
  335.          move.w #12,-(sp)
  336.          trap #14
  337.          addq.l #8,sp
  338.  
  339. With this function, it is possible to send a string of data to the 
  340. MIDI OUT port.
  341. 'pntr' is the pointer to the memory address on which the string is 
  342. located.
  343. 'count' is the number of bytes that should be sent -1.  So if  you 
  344. want to send 12 bytes, that value should be 11.
  345.  
  346. ü13 mfpintÇ
  347.  
  348. Example: move.l vector,-(sp)
  349.          move.w number,-(sp)
  350.          move.w #13,-(sp)
  351.          trap #14
  352.          addq.l #8,sp
  353. This  function is used to initialize an Interrupt routine  in  the 
  354. MFP.
  355. 'number' is the number of the MFP-Interrupt,  which can be from  0 
  356. to 15.
  357. 'vector'  is the address on which the vector that belongs to  that 
  358. Interrupt routine is located.
  359.  
  360. ü14 iorecÇ
  361.  
  362. Example: move.w device,-(sp)
  363.          move.w #14,-(sp)
  364.          trap #14
  365.          addq.l #4,sp
  366.  
  367. This routine is there to get the pointer to a buffer-data-line for 
  368. an input device. The following input devices may be selected:
  369.          0        RS232
  370.          1        Keyboard
  371.          2        MIDI
  372.  
  373.  
  374.  
  375. The buffer-data-line is built up as follows:
  376.          long     ibuf       Pointer to input buffer
  377.          int      ibufsize   Size of input buffer
  378.          int      ibufhd     Head Index
  379.          int      ibuftl     Tail Index
  380.          int      ibuflow    Low water Mark
  381.          int      ibufhi     High water Mark
  382. For more specific information, I am afraid I must tell you to have 
  383. a  look  at pages 200 and 201 of Data Becker's  "ST  Intern".  The 
  384. specifications  and  examples mentioned there might  make  working 
  385. with this XBIOS function more clear, whereas talking about them in 
  386. this article would be too much of a hassle.
  387.  
  388. ü
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397. 15 rsconfÇ
  398.  
  399. Example: move.w scr,-(sp)
  400.          move.w tsr,-(sp)
  401.          move.w rsr,-(sp)
  402.          move.w ucr,-(sp)
  403.          move.w ctrl,-(sp)
  404.          move.w baud,-(sp)
  405.          move.w #15,-(sp)
  406.          trap #14
  407.          add.l #14,sp
  408.  
  409. This  XBIOS  function  configurates  the  RS232   Interface.   The 
  410. parameters thereby have the following meaning:
  411. 'scr' is the Synchronous Character Register in the MFP.
  412. 'tsr' is the Transmitter Status Register in the MFP.
  413. 'rsr' is the Receiver Status Register in the MFP.
  414. 'ucr' is the USART Control Register in the MFP.
  415. 'ctrl' is a communication-parameter.
  416. 'baud' is the baudrate.
  417.  
  418.  
  419. Whenever a parameter turns out to be -1,  the old value is kept on 
  420. the MFP 68901.  You should have a look at some documentation about 
  421. the MFP 68901 processor for the meaning of the MFP registers.
  422. 'ctrl' is used to specify the Handshake-Mode:
  423.  
  424.          0        No Handshake (that is default on power-up)
  425.          1        XON/XOFF
  426.          2        RTS/CTS
  427.          3        XON/XOFF and RTS/CTS (not very useful)
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441. 'baud' can have one of the following values:
  442.  
  443.          0        19200
  444.          1         9600
  445.          2         4800
  446.          3         3600
  447.          4         2400
  448.          5         2000
  449.          6         1800
  450.          7         1200
  451.          8          600
  452.          9          300
  453.         10          200
  454.         11          150
  455.         12          134
  456.         13          110
  457.         14           75
  458.         15           50
  459.  
  460.  
  461.