doc: default firmware documentation fixes (clarity, typos)

c2a155be · Tomasz Wlostowski · e639352a · c2a155be · c2a155be · c2a155be
Commit c2a155be authored Jan 28, 2013 by Tomasz Wlostowski
9 changed files
--- a/doc/firmware-manual/Makefile
+++ b/doc/firmware-manual/Makefile
@@ -14,7 +14,7 @@ HTML = $(INPUT:.in=.html)
 TXT  = $(INPUT:.in=.txt)
 PDF  = $(INPUT:.in=.pdf)

-ALL    =  $(TXT) $(PDF)
+ALL    =  $(PDF)

 MAKEINFO ?= makeinfo


--- a/doc/firmware-manual/drawings/boot_block.cdr
+++ b/doc/firmware-manual/drawings/boot_block.cdr
--- a/doc/firmware-manual/drawings/boot_block.eps
+++ b/doc/firmware-manual/drawings/boot_block.eps
--- a/doc/firmware-manual/drawings/boot_block.pdf
+++ b/doc/firmware-manual/drawings/boot_block.pdf
--- a/doc/firmware-manual/drawings/golden_block.cdr
+++ b/doc/firmware-manual/drawings/golden_block.cdr
--- a/doc/firmware-manual/drawings/golden_block.eps
+++ b/doc/firmware-manual/drawings/golden_block.eps
@@ -3,7 +3,7 @@
 %%LanguageLevel: 1
 %%Creator: CorelDRAW 12
 %%Title: golden_block.eps
-%%CreationDate: Wed Oct 17 18:01:01 2012
+%%CreationDate: Mon Jan 28 11:29:28 2013
 %%DocumentProcessColors: Cyan Magenta Yellow Black 
 %%DocumentSuppliedResources: (atend)
 %%EndComments
@@ -287,9 +287,21 @@ wCorel12Dict begin
 0 2.00013 2.00013 0.00000 @w
 /$fm 0 def
 459.97228 392.39093 m
+459.97228 483.40375 L
 459.97228 730.90885 L
 S

+@rax %Note: Object
+459.49663 491.72230 568.98113 491.72343 @E
+0 J 0 j [2 3 ] 0 d 0 R 0 @G
+0.00 0.00 0.00 0.40 K
+0 2.00013 2.00013 0.00000 @w
+/$fm 0 def
+568.98113 491.72287 m
+539.54646 491.72287 L
+459.49663 491.72287 L
+S
+
 @rax %Note: Object
 300.25474 567.58394 335.12769 661.52409 @E
 0 J 0 j [] 0 d 0 R 0 @G
@@ -297,8 +309,8 @@ S
 0 1.00006 1.00006 0.00000 @w
 /$fm 0 def
 300.25474 567.58394 m
-316.50633 567.89887 314.11247 610.08491 313.99257 615.86561 c
-313.74935 627.59792 318.37493 661.52409 335.12769 661.52409 C
+316.50633 567.89830 314.11247 610.08491 313.99257 615.86589 c
+313.74935 627.59820 318.37493 661.52409 335.12769 661.52409 C
 S

 @rax %Note: Object
@@ -6395,104 +6407,487 @@ F
 @c
 F
 T
-@rax 469.53751 705.07020 498.40554 715.43254 @E
+@rax 469.53751 705.07729 546.66170 715.26217 @E
 [0.00028346 0.00000000 0.00000000 0.00028346 469.53749464 705.24054113] @tm
 0 O 0 @g
 0.00 0.00 0.00 0.40 k
 e

 % FontChange:/_ArialMT 49389.00000 z
-%CHAR: 0 0 (P) @t
-/$fm 1 def
-3597 0 m
-3597 35354 L
-15047 35354 l
-19385 35354 22217 35173 23534 34819 c
-25559 34292 27263 33140 28629 31362 c
-29996 29584 30679 27287 30679 24480 c
-30679 22307 30284 20480 29493 19007 c
-28703 17525 27707 16364 26489 15516 c
-25279 14677 24044 14117 22793 13845 c
-21089 13508 18620 13335 15385 13335 c
-10734 13335 L
-10734 0 L
-3597 0 L
-@c
-10734 29370 m
-10734 19344 L
-14636 19344 l
-17451 19344 19336 19525 20282 19896 c
-21229 20266 21970 20842 22513 21632 c
-23048 22423 23320 23336 23320 24382 c
-23320 25666 22941 26728 22184 27567 c
-21435 28399 20472 28925 19319 29131 c
-18463 29296 16751 29370 14183 29370 c
-10734 29370 L
-@c
-F
-%CHAR: 32942 0 (C) @t
-/$fm 1 def
-59159 12998 m
-66074 10808 L
-65012 6947 63250 4083 60781 2206 c
-58320 337 55184 -601 51389 -601 c
-46697 -601 42836 1004 39815 4206 c
-36794 7417 35280 11804 35280 17360 c
-35280 23246 36803 27814 39840 31074 c
-42877 34325 46870 35955 51825 35955 c
-56147 35955 59661 34679 62361 32119 c
-63975 30613 65177 28440 65983 25608 C
-58912 23921 L
-58501 25756 57628 27205 56295 28267 c
-54969 29329 53356 29856 51463 29856 c
-48845 29856 46713 28917 45083 27032 c
-43454 25155 42639 22110 42639 17895 c
-42639 13426 43437 10240 45051 8347 c
-46656 6445 48746 5499 51315 5499 c
-53216 5499 54846 6100 56212 7310 c
-57579 8511 58558 10413 59159 12998 C
-@c
-F
-%CHAR: 68609 0 (B) @t
-/$fm 1 def
-72223 35354 m
-86356 35354 l
-89155 35354 91246 35239 92620 35000 c
-93995 34770 95221 34284 96308 33543 c
-97395 32803 98292 31823 99016 30588 c
-99741 29362 100103 27979 100103 26456 c
-100103 24802 99658 23279 98769 21896 c
-97872 20513 96662 19476 95139 18784 C
-97288 18159 98950 17089 100103 15582 c
-101263 14068 101840 12290 101840 10248 c
-101840 8643 101469 7079 100720 5556 c
-99971 4042 98950 2823 97658 1918 c
-96366 1012 94769 453 92867 239 c
-91682 115 88809 33 84257 0 c
-72223 0 L
-72223 35354 L
-@c
-79368 29469 m
-79368 21295 L
-84043 21295 l
-86825 21295 88554 21336 89229 21418 c
-90447 21558 91410 21978 92110 22678 c
-92810 23377 93155 24299 93155 25444 c
-93155 26538 92859 27427 92258 28111 c
-91649 28794 90752 29205 89566 29345 c
-88858 29428 86825 29469 83467 29469 c
-79368 29469 L
-@c
-79368 15409 m
-79368 5960 L
-85969 5960 l
-88546 5960 90176 6025 90867 6174 c
-91929 6363 92793 6840 93460 7581 c
-94127 8330 94464 9335 94464 10586 c
-94464 11648 94201 12545 93690 13286 c
-93172 14026 92431 14570 91460 14907 c
-90488 15245 88373 15409 85130 15409 c
-79368 15409 L
+%CHAR: 0 0 (M) @t
+/$fm 1 def
+3498 0 m
+3498 35354 L
+14183 35354 L
+20595 11236 L
+26933 35354 L
+37643 35354 L
+37643 0 L
+31016 0 L
+31016 27831 L
+23995 0 L
+17122 0 L
+10125 27831 L
+10125 0 L
+3498 0 L
+@c
+F
+%CHAR: 41141 0 (e) @t
+/$fm 1 def
+59514 8149 m
+66272 7021 L
+65399 4544 64033 2659 62156 1366 c
+60287 66 57941 -576 55126 -576 c
+50673 -576 47380 873 45240 3786 c
+43553 6116 42705 9063 42705 12611 c
+42705 16858 43816 20184 46039 22587 c
+48253 24991 51060 26193 54451 26193 c
+58263 26193 61267 24933 63473 22414 c
+65671 19896 66725 16043 66634 10849 C
+49652 10849 L
+49702 8841 50245 7277 51290 6165 c
+52336 5046 53645 4486 55200 4486 c
+56262 4486 57151 4774 57876 5350 c
+58600 5935 59152 6865 59514 8149 C
+@c
+59901 14998 m
+59851 16965 59349 18455 58386 19476 c
+57423 20496 56246 21007 54863 21007 c
+53381 21007 52163 20464 51200 19385 c
+50237 18315 49759 16850 49776 14998 C
+59901 14998 L
+@c
+F
+%CHAR: 68610 0 (z) @t
+/$fm 1 def
+69433 0 m
+69433 5285 L
+79031 16298 l
+80603 18101 81772 19377 82521 20134 C
+81739 20085 80702 20060 79418 20044 c
+70372 19994 L
+70372 25608 L
+91543 25608 L
+91543 20809 L
+81756 9524 L
+78307 5787 L
+80183 5902 81352 5960 81805 5960 c
+92292 5960 L
+92292 0 L
+69433 0 L
+@c
+F
+%CHAR: 93305 0 (z) @t
+/$fm 1 def
+94128 0 m
+94128 5285 L
+103726 16298 l
+105298 18101 106467 19377 107216 20134 C
+106434 20085 105397 20060 104113 20044 c
+95067 19994 L
+95067 25608 L
+116238 25608 L
+116238 20809 L
+106451 9524 L
+103002 5787 L
+104878 5902 106047 5960 106500 5960 c
+116987 5960 L
+116987 0 L
+94128 0 L
+@c
+F
+%CHAR: 118000 0 (a) @t
+/$fm 1 def
+126610 17797 m
+120461 18908 L
+121153 21385 122338 23213 124025 24406 c
+125721 25592 128224 26193 131549 26193 c
+134578 26193 136825 25830 138307 25114 c
+139781 24398 140826 23493 141427 22390 c
+142028 21287 142332 19270 142332 16323 c
+142258 8413 l
+142258 6165 142365 4503 142587 3433 c
+142802 2371 143213 1218 143806 0 C
+137097 0 L
+136924 453 136702 1119 136447 2000 c
+136340 2404 136257 2667 136208 2799 C
+135047 1671 133813 831 132496 263 c
+131179 -296 129771 -576 128273 -576 c
+125639 -576 123556 140 122042 1564 c
+120519 2996 119762 4807 119762 6997 c
+119762 8437 120107 9730 120799 10866 c
+121490 12002 122461 12866 123704 13467 c
+124947 14068 126750 14594 129096 15047 c
+132257 15640 134455 16200 135673 16710 C
+135673 17385 l
+135673 18694 135352 19616 134710 20175 c
+134068 20727 132858 21007 131072 21007 c
+129862 21007 128923 20768 128248 20291 c
+127573 19821 127030 18990 126610 17797 C
+@c
+135673 12298 m
+134809 12010 133434 11664 131549 11261 c
+129672 10857 128446 10462 127861 10084 c
+126981 9450 126536 8660 126536 7696 c
+126536 6742 126890 5927 127598 5235 c
+128306 4544 129203 4198 130298 4198 c
+131524 4198 132685 4601 133796 5400 c
+134619 6009 135154 6758 135410 7647 c
+135591 8223 135673 9326 135673 10948 c
+135673 12298 L
+@c
+F
+%CHAR: 145469 0 (n) @t
+/$fm 1 def
+172312 0 m
+165537 0 L
+165537 13072 l
+165537 15837 165389 17624 165101 18439 c
+164813 19245 164336 19879 163685 20332 c
+163035 20776 162253 21007 161339 21007 c
+160162 21007 159109 20686 158178 20044 c
+157248 19393 156606 18546 156260 17484 c
+155915 16422 155742 14463 155742 11598 c
+155742 0 L
+148967 0 L
+148967 25608 L
+155256 25608 L
+155256 21846 L
+157495 24744 160310 26193 163702 26193 c
+165192 26193 166566 25921 167801 25386 c
+169036 24843 169974 24159 170608 23320 c
+171242 22480 171686 21534 171933 20472 c
+172188 19410 172312 17895 172312 15920 c
+172312 0 L
+@c
+F
+%CHAR: 175637 0 (i) @t
+/$fm 1 def
+179185 29082 m
+179185 35354 L
+185959 35354 L
+185959 29082 L
+179185 29082 L
+@c
+179185 0 m
+179185 25608 L
+185959 25608 L
+185959 0 L
+179185 0 L
+@c
+F
+%CHAR: 189359 0 (n) @t
+/$fm 1 def
+216202 0 m
+209427 0 L
+209427 13072 l
+209427 15837 209279 17624 208991 18439 c
+208703 19245 208226 19879 207575 20332 c
+206925 20776 206143 21007 205229 21007 c
+204052 21007 202999 20686 202068 20044 c
+201138 19393 200496 18546 200150 17484 c
+199805 16422 199632 14463 199632 11598 c
+199632 0 L
+192857 0 L
+192857 25608 L
+199146 25608 L
+199146 21846 L
+201385 24744 204200 26193 207592 26193 c
+209082 26193 210456 25921 211691 25386 c
+212926 24843 213864 24159 214498 23320 c
+215132 22480 215576 21534 215823 20472 c
+216078 19410 216202 17895 216202 15920 c
+216202 0 L
+@c
+F
+%CHAR: 219527 0 (e) @t
+/$fm 1 def
+237900 8149 m
+244658 7021 L
+243785 4544 242419 2659 240542 1366 c
+238673 66 236327 -576 233512 -576 c
+229059 -576 225766 873 223626 3786 c
+221939 6116 221091 9063 221091 12611 c
+221091 16858 222202 20184 224425 22587 c
+226639 24991 229446 26193 232837 26193 c
+236649 26193 239653 24933 241859 22414 c
+244057 19896 245111 16043 245020 10849 C
+228038 10849 L
+228088 8841 228631 7277 229676 6165 c
+230722 5046 232031 4486 233586 4486 c
+234648 4486 235537 4774 236262 5350 c
+236986 5935 237538 6865 237900 8149 C
+@c
+238287 14998 m
+238237 16965 237735 18455 236772 19476 c
+235809 20496 234632 21007 233249 21007 c
+231767 21007 230549 20464 229586 19385 c
+228623 18315 228145 16850 228162 14998 C
+238287 14998 L
+@c
+F
+%CHAR: 246996 0 (s) @t
+/$fm 1 def
+248157 7310 m
+254956 8347 L
+255244 7030 255828 6025 256717 5342 c
+257598 4659 258833 4313 260430 4313 c
+262183 4313 263500 4634 264381 5285 c
+264982 5729 265278 6338 265278 7087 c
+265278 7606 265114 8034 264793 8371 c
+264455 8692 263698 8989 262529 9260 c
+257063 10462 253598 11565 252132 12561 c
+250108 13944 249095 15870 249095 18332 c
+249095 20546 249968 22414 251721 23921 c
+253474 25435 256191 26193 259870 26193 c
+263377 26193 265986 25616 267690 24480 c
+269394 23336 270563 21649 271205 19410 C
+264817 18233 L
+264546 19229 264027 19994 263261 20521 c
+262496 21056 261409 21320 259994 21320 c
+258207 21320 256931 21073 256158 20571 c
+255647 20217 255392 19756 255392 19196 c
+255392 18710 255614 18307 256067 17969 c
+256676 17517 258784 16883 262397 16060 c
+266003 15245 268521 14240 269954 13047 c
+271369 11837 272077 10158 272077 8009 c
+272077 5663 271098 3638 269131 1951 c
+267171 263 264274 -576 260430 -576 c
+256940 -576 254182 132 252141 1548 c
+250108 2955 248782 4881 248157 7310 C
+@c
+F
+T
+@rax 468.19361 474.27449 548.20800 484.64391 @E
+[0.00028346 0.00000000 0.00000000 0.00028346 468.19358917 474.45191965] @tm
+ 0 O 0 @g
+0.00 0.00 0.00 0.40 k
+e
+
+% FontChange:/_ArialMT 49389.00000 z
+%CHAR: 0 0 (S) @t
+/$fm 1 def
+1786 11499 m
+8734 12183 L
+9145 9845 9993 8133 11277 7038 c
+12553 5951 14273 5400 16447 5400 c
+18743 5400 20480 5886 21641 6865 c
+22809 7836 23394 8972 23394 10273 c
+23394 11113 23147 11820 22653 12405 c
+22167 12998 21311 13508 20085 13936 c
+19253 14232 17344 14743 14372 15483 c
+10545 16430 7861 17599 6322 18982 c
+4149 20924 3062 23295 3062 26094 c
+3062 27897 3572 29576 4593 31148 c
+5614 32712 7087 33906 9005 34729 c
+10931 35544 13244 35955 15961 35955 c
+20406 35955 23740 34984 25987 33041 c
+28226 31090 29403 28497 29518 25246 C
+22381 24933 L
+22077 26752 21418 28061 20414 28851 c
+19410 29650 17904 30045 15895 30045 c
+13821 30045 12191 29625 11022 28769 c
+10265 28226 9886 27493 9886 26580 c
+9886 25740 10240 25024 10948 24431 c
+11845 23674 14035 22884 17508 22069 c
+20982 21246 23550 20398 25213 19525 c
+26876 18644 28176 17451 29123 15928 c
+30061 14405 30531 12528 30531 10298 c
+30531 8273 29971 6371 28843 4610 c
+27715 2840 26127 1523 24069 667 c
+22011 -198 19443 -626 16372 -626 c
+11903 -626 8470 403 6075 2469 c
+3679 4536 2247 7548 1786 11499 C
+@c
+F
+%CHAR: 32942 0 (V) @t
+/$fm 1 def
+45553 0 m
+32917 35354 L
+40663 35354 L
+49603 9186 L
+58262 35354 L
+65835 35354 L
+53175 0 L
+45553 0 L
+@c
+F
+%CHAR: 65884 0 (E) @t
+/$fm 1 def
+69481 0 m
+69481 35354 L
+95690 35354 L
+95690 29370 L
+76618 29370 L
+76618 21534 L
+94365 21534 L
+94365 15582 L
+76618 15582 L
+76618 5960 L
+96365 5960 L
+96365 0 L
+69481 0 L
+@c
+F
+%CHAR: 98826 0 (C) @t
+/$fm 1 def
+125043 12998 m
+131958 10808 L
+130896 6947 129134 4083 126665 2206 c
+124204 337 121068 -601 117273 -601 c
+112581 -601 108720 1004 105699 4206 c
+102678 7417 101164 11804 101164 17360 c
+101164 23246 102687 27814 105724 31074 c
+108761 34325 112754 35955 117709 35955 c
+122031 35955 125545 34679 128245 32119 c
+129859 30613 131061 28440 131867 25608 C
+124796 23921 L
+124385 25756 123512 27205 122179 28267 c
+120853 29329 119240 29856 117347 29856 c
+114729 29856 112597 28917 110967 27032 c
+109338 25155 108523 22110 108523 17895 c
+108523 13426 109321 10240 110935 8347 c
+112540 6445 114630 5499 117199 5499 c
+119100 5499 120730 6100 122096 7310 c
+123463 8511 124442 10413 125043 12998 C
+@c
+F
+%CHAR: 148215 0 (b) @t
+/$fm 1 def
+151475 0 m
+151475 35354 L
+158249 35354 L
+158249 22620 L
+160340 24999 162809 26193 165674 26193 c
+168794 26193 171370 25057 173420 22801 c
+175461 20546 176482 17303 176482 13072 c
+176482 8701 175437 5326 173354 2963 c
+171271 601 168744 -576 165773 -576 c
+164308 -576 162867 -214 161443 519 c
+160019 1251 158792 2330 157764 3762 C
+157764 0 L
+151475 0 L
+@c
+158200 13360 m
+158200 10709 158620 8750 159451 7474 c
+160628 5672 162184 4774 164135 4774 c
+165625 4774 166901 5416 167954 6692 c
+169008 7968 169535 9985 169535 12734 c
+169535 15656 169000 17772 167938 19064 c
+166884 20356 165526 21007 163863 21007 c
+162241 21007 160892 20373 159813 19114 c
+158735 17846 158200 15936 158200 13360 c
+@c
+F
+%CHAR: 178383 0 (o) @t
+/$fm 1 def
+180359 13170 m
+180359 15418 180918 17599 182021 19706 c
+183133 21805 184705 23419 186738 24522 c
+188771 25633 191043 26193 193554 26193 c
+197422 26193 200600 24933 203078 22414 c
+205555 19896 206790 16718 206790 12874 c
+206790 9005 205539 5795 203045 3243 c
+200542 691 197398 -576 193603 -576 c
+191249 -576 189018 -49 186886 1012 c
+184754 2074 183133 3630 182021 5680 c
+180918 7729 180359 10224 180359 13170 c
+@c
+187306 12808 m
+187306 10265 187907 8322 189117 6972 c
+190319 5622 191809 4947 193578 4947 c
+195348 4947 196830 5622 198023 6972 c
+199225 8322 199826 10281 199826 12858 c
+199826 15360 199225 17294 198023 18644 c
+196830 19994 195348 20669 193578 20669 c
+191809 20669 190319 19994 189117 18644 c
+187907 17294 187306 15344 187306 12808 c
+@c
+F
+%CHAR: 208551 0 (a) @t
+/$fm 1 def
+217161 17797 m
+211012 18908 L
+211704 21385 212889 23213 214576 24406 c
+216272 25592 218775 26193 222100 26193 c
+225129 26193 227376 25830 228858 25114 c
+230332 24398 231377 23493 231978 22390 c
+232579 21287 232883 19270 232883 16323 c
+232809 8413 l
+232809 6165 232916 4503 233138 3433 c
+233353 2371 233764 1218 234357 0 C
+227648 0 L
+227475 453 227253 1119 226998 2000 c
+226891 2404 226808 2667 226759 2799 C
+225598 1671 224364 831 223047 263 c
+221730 -296 220322 -576 218824 -576 c
+216190 -576 214107 140 212593 1564 c
+211070 2996 210313 4807 210313 6997 c
+210313 8437 210658 9730 211350 10866 c
+212041 12002 213012 12866 214255 13467 c
+215498 14068 217301 14594 219647 15047 c
+222808 15640 225006 16200 226224 16710 C
+226224 17385 l
+226224 18694 225903 19616 225261 20175 c
+224619 20727 223409 21007 221623 21007 c
+220413 21007 219474 20768 218799 20291 c
+218124 19821 217581 18990 217161 17797 C
+@c
+226224 12298 m
+225360 12010 223985 11664 222100 11261 c
+220223 10857 218997 10462 218412 10084 c
+217532 9450 217087 8660 217087 7696 c
+217087 6742 217441 5927 218149 5235 c
+218857 4544 219754 4198 220849 4198 c
+222075 4198 223236 4601 224347 5400 c
+225170 6009 225705 6758 225961 7647 c
+226142 8223 226224 9326 226224 10948 c
+226224 12298 L
+@c
+F
+%CHAR: 236020 0 (r) @t
+/$fm 1 def
+246054 0 m
+239280 0 L
+239280 25608 L
+245569 25608 L
+245569 21970 L
+246647 23690 247618 24826 248474 25369 c
+249339 25913 250310 26193 251405 26193 c
+252952 26193 254434 25765 255866 24909 C
+253767 19007 L
+252631 19739 251569 20110 250590 20110 c
+249635 20110 248836 19854 248178 19328 c
+247511 18809 247001 17862 246622 16496 c
+246244 15129 246054 12265 246054 7910 c
+246054 0 L
+@c
+F
+%CHAR: 255241 0 (d) @t
+/$fm 1 def
+282273 0 m
+275984 0 L
+275984 3762 L
+274939 2297 273704 1210 272280 494 c
+270856 -222 269424 -576 267975 -576 c
+265028 -576 262509 609 260410 2980 c
+258320 5350 257266 8660 257266 12899 c
+257266 17245 258287 20546 260328 22801 c
+262369 25057 264954 26193 268074 26193 c
+270930 26193 273408 24999 275499 22620 C
+275499 35354 L
+282273 35354 L
+282273 0 L
+@c
+264189 13360 m
+264189 10627 264567 8651 265325 7425 c
+266411 5663 267942 4774 269901 4774 c
+271465 4774 272791 5441 273885 6766 c
+274972 8092 275523 10075 275523 12709 c
+275523 15648 274988 17772 273935 19064 c
+272873 20356 271515 21007 269852 21007 c
+268247 21007 266905 20365 265818 19089 c
+264732 17813 264189 15903 264189 13360 c
 @c
 F
 T

--- a/doc/firmware-manual/drawings/golden_block.pdf
+++ b/doc/firmware-manual/drawings/golden_block.pdf
--- a/doc/firmware-manual/svec-firmware-manual.in
+++ b/doc/firmware-manual/svec-firmware-manual.in
@@ -42,8 +42,7 @@
 @titlepage
 @title Default firmware for the SVEC card
 @subtitle Programmer's manual
-@author CERN BE-CO-HT / Tomasz Włostowski
-
+@author CERN BE-CO-HT / Tomasz Włostowski, 28.01.2013
 @end titlepage
 @headings single

@@ -57,46 +56,56 @@

 This document describes the default bitstreams that come preloaded with every SVEC card. As there are two FPGAs on the SVEC, there are two default bitstreams:
 @itemize
-@item @b{Bootloader bitstream}, residing in the System FPGA whose role is to start up the Application FPGA
+@item @b{Bootloader bitstream}, residing in the System FPGA whose role is to start up the Application FPGA,
 @item @b{Golden bitstream}, residing in the Application FPGA, which allows the device driver to enumerate the mezzanines.
 @end itemize

 @chapter The Bootloader

-The System FPGA bootloader allows to boot the Application FPGA from the VME bus or from the onboard Flash memory and reprogram both the System and Application bitstreams in the flash via VME. The boot process goes as follows:
+The System FPGA bootloader allows to boot the Application FPGA from the VME bus or from the onboard Flash memory and reprogram both the System and Application bitstreams in the flash via VME (see @ref{fig:boot_modes}). The boot process goes as follows:
 @itemize
-@item Power up.
-@item SFPGA checks for presence of a valid bitstream file for the Application FPGA in the Flash memory.
+@item Power up,
+@item SFPGA checks for presence of a valid bitstream file for the Application FPGA in the Flash memory,
 @item If a valid bitstream has been found, the AFPGA is initialized with it,
 @item if not, the Bootloader enters passive mode. Upon reception of a boot sequence, if gives access to the Flash for the host or lets it program the AFPGA directly.
 @end itemize

+@float Figure,fig:boot_modes
+@center @image{drawings/boot_block, 12cm,,,.pdf}
+@caption{Boot modes of the SVEC card.}
+@end float
+
 @section VME Interface
 The bootloader core supports only 32-bit data CR/CSR accesses from/to address range @code{0x70000} - @code{0x70020}, allowing for plug&play reprogramming of the cards only knowing their physical slot locations. All other transfers are ignored. The base address is @code{0x70000}, and corresponds to the @code{CSR} register. When the card is powered up, the VME interface stays in passive mode, monitoring VME accesses without ACKing them. This is to prevent conflicts with the CR/CSR space of the VME core in the Application FPGA. 

 @section Entering bootloader mode
-In order to enter the bootloader, one needs to write a magic sequence of 8 following transfers: @code{0xde}, @code{0xad}, @code{0xad}, @code{0xbe}, @code{0xca}, @code{0xfe}, @code{0xba}, @code{0xbe} to @code{BTRIGR} register. Afterwards, read the @code{IDR} register. It should be equal to @code{SVEC} ASCII string encoded in HEX. Any other value indicates that the boot trigger sequence was not correctly recognized. 
+In order to enter the bootloader, one needs to write the magic sequence of 8 following transfers: @code{0xde}, @code{0xad}, @code{0xbe}, @code{0xef}, @code{0xca}, @code{0xfe}, @code{0xba}, @code{0xbe} to the @code{BTRIGR} register (for register definitions, @pxref{System FPGA Register Map}).

+In order to check if the bootloader has been activated, one can read the @code{IDR} register. It should be equal to @code{SVEC} ASCII string encoded in HEX. Any other value indicates that the boot trigger sequence was not correctly recognized, the System FPGA is unprogrammed, the geographical address of the card is wrong or that the card itself is faulty.

 @b{Note 1:} Triggering bootloader mode causes automatic reset (un-programming) of the Application FPGA.

-@b{Note 2:} Write operations to @code{BTRIGR} register while the core is still in passie mode will not be acknowledged on the VME bus and will most likely cause bus errors. Please ignore them.
+@b{Note 2:} Since the bootloader core supports only 32-bit transfers, one must extend the magic values with zeroes (e.g. @code{0x000000de}, etc.) and write full 32-bit words. Attempts to write the magic sequence as single bytes (D8 transfer mode) will be ignored.
+
+@b{Note 3:} Trigger sequence must not be interleaved with other accesses to the bootloader address range of the same card.
+
+@b{Note 4:} Write operations to @code{BTRIGR} register while the core is still in passive mode will not be acknowledged on the VME bus and will most likely cause bus errors. Please ignore them.

 @section Programming the AFPGA
-Programming the Application FPGA directly via VME involves following steps:
+Programming the Application FPGA directly via VME involves the following steps:
 @itemize
-@item Reset the Xilinx Passive Serial boot interface by writing @code{CSR.SWRST} bit,
-@item Set download speed by writing @code{CSR.CLKDIV} field. Default value is @code{1}.
-@item Write @code{CSR.START} bit and set endianess via @code{CSR.MSBF} bit,
-@item Write the bitstream to the FIFO registers, observing FIFO full/empty status. Last transfer should have @code{FIFO_R1.XLAST} bit set to 1.
-@item Wait for assertion of @code{CSR.DONE}. @code{CSR.ERROR} bit indicates a problem during configuration (most likely, an invalid bitstream)
+@item Reset the Xilinx Passive Serial boot interface by writing the @code{CSR.SWRST} bit,
+@item Set download speed by writing the @code{CSR.CLKDIV} field. Default value is @code{1},
+@item Write the @code{CSR.START} bit and set endianness via the @code{CSR.MSBF} bit,
+@item Write the bitstream to the FIFO registers, observing FIFO full/empty status. The last transfer should have @code{FIFO_R1.XLAST} bit set to 1,
+@item Wait for assertion of @code{CSR.DONE}. @code{CSR.ERROR} bit indicates a problem during configuration (most likely, an invalid bitstream),
 @item Exit bootloader mode by writing 1 to @code{CSR.EXIT} bit.
 @end itemize

-Successful firmware download to the Application FPGA is indicated by turning on the ``AFPGA DONE'' LED.
+A code example is available in the repository (@pxref{repo_link,,2}). Successful firmware download to the Application FPGA is indicated by turning on the ``AFPGA DONE'' LED in the middle of the PCB.

 @section Programming the Flash
-SFPGA also allows raw access to the Flash memory (M25P128) via @code{FAR} register. The code below shows how to execute a single SPI transaction (command + N data bytes). 
+The SFPGA also allows raw access to the Flash memory (M25P128) via the @code{FAR} register. The code below shows how to execute a single SPI transaction (command + N data bytes). 

 @example
 uint8 spi_transfer(int cs, uint8 data) {
@@ -117,27 +126,28 @@ void flash_command(uint8 command, uint8 data[]) {
 }
 @end example

-Low-level details about programming M25Pxxx series Flash memories can be found in their datasheets.
+Low-level details about programming M25Pxxx series Flash memories can be found in their datasheets (@pxref{m25p_datasheet,,1}).

-@b{Note 1:} It is advised to protect the System FPGA bitstream from being accidentally overwritten, as this will result in bricking the card and will require re-programming the flash via JTAG.
+@b{Note 1:} It is advised to protect the region of the flash containing the system FPGA bitstream from being accidentally overwritten, as this will result in rendering the card unusable and will require re-programming the flash via JTAG. Details on memory protection can be found in the M25P series datasheet.

-@b{Note 2:} The freshly-programmed bitstreams will be loaded into the FPGAs after power-cycling the card. 
+@b{Note 2:} The freshly-programmed bitstreams will be loaded into the FPGAs after power-cycling the card. In order to avoid the power cycle, one can boot the Application FPGA directly using the same bitstream.

 @section Flash memory organization

-The flash memory of the SVEC contains 16 Megabytes of memory, that is 64k pages of 256 bytes. First 6 MBs are used for bitstream storage, the rest is available for the user application. The flash format is compatible with the SDB filesystem, with the SDB descriptor table located at offset @code{0x500000}. Locations of the bitstreams are fixed to:
+The flash memory of the SVEC contains 16 Megabytes of data, that is 64k pages of 256 bytes. The first 6 MBs are used for bitstream storage, the rest is available for the user application. The flash format is compatible with the SDB filesystem, with the SDB descriptor table located at offset @code{0x500000}. Locations of the bitstreams are fixed to:
 @itemize
 @item @code{0}: Raw bitstream for the System FPGA (up to 1 MB)
 @item @code{0x100000}: Bitstream for the Application FPGA (up to 4 MB)
 @end itemize

-An example script for building the default flash filesystem (containg the bootloader and golden bitstreams) is located in the @code{software/sdb-flash} subdirectory. The presence of SDB descriptor table at @code{0x500000}, as the SDB signature is checked by the bootloader to prevent booting up from a corrupted flash. 
+An example script for building the default flash filesystem (containg the bootloader and golden bitstreams) is located in the @code{software/sdb-flash} subdirectory in the SVEC project's repository(@pxref{repo_link,,2}). Presence of the SDB descriptor table at @code{0x500000} is checked by the bootloader to prevent booting up from a corrupted flash. 

 @b{Note:} Both bitstreams must be in raw (@code{.bin} file extension) format. @code{.bit}, @code{.mcs}, @code{.xsvf} and other formats will not work. This also applies to direct VME boot mode.


+@page
 @chapter The Golden Bitstream
-The SVEC Application FPGA golden bitstream allows the SVEC device driver to:
+The SVEC Application FPGA golden bitstream is usually loaded by default by the bootloader and allows the SVEC device driver to:
 @itemize
 @item Query the board's serial number,
 @item Check the presence of the FMC mezzanines,
@@ -154,12 +164,12 @@ The bitstream encompasses @math{I^2C}, OneWire and GPIO modules from the @code{g
 @caption{Block diagram of the SVEC golden gateware.}
 @end float

-Presence detection is done by reading out the @code{PRSNT} lines (active low) through the GPIO port. EEPROM readout is performed via the two @math{I^2C} masters. Board serial number
-is equal to the serial number of the DS18B20U+ temperature sensor, accessible via the OneWire master. The clock freqency for @code{I^2C} and OneWire dividers calculation is 62.5 MHz. 
+Presence detection is done by reading out the @code{PRSNT} lines (active low) through the GPIO port. EEPROM readout is performed via the two @math{I^2C} masters. The board serial number
+is equal to the serial number of the DS18B20U+ temperature sensor, accessible via the OneWire master. The clock freqency for @math{I^2C} and OneWire dividers calculation is 62.5 MHz. 

 @section Memory map

-@b{Warning:} Please do not hardcode the base addresses of the cores, query them from the SDB descriptor. The SDB address of @code{0x0} is guaranteed to stay constant.
+@b{Note:} Please do not hardcode the base addresses of the cores, query them from the SDB descriptor. The SDB address of @code{0x0} is guaranteed to stay constant.
 Only A32/A24/D32/CSR address modifiers are supported.

 @multitable @columnfractions .20 .10 .15 .65
@@ -171,6 +181,22 @@ Only A32/A24/D32/CSR address modifiers are supported.
 @item @code{xwb_gpio_port} @tab @code{0x13000} @tab @code{general-cores} @tab GPIO port for accessing FMC1/2 presence lines.
 @end multitable

+@macro regsection{name}
+@section \name\
+@end macro
+
+@page
+@chapter References
+@enumerate
+@anchor{m25p_datasheet}
+@item @uref{http://www.micron.com/parts/nor-flash/serial-nor-flash/m25p128-vme6gb} - M25P series SPI Flash memory datasheet
+@anchor{repo_link}
+@item @uref{http://www.ohwr.org/projects/svec/repository/} - Git repository containing this document's sources and revision history (@code{doc} subdirectory) and bootloading code examples (@code{software/sveclib} subdirectory).
+@end enumerate
+@page
 @appendix System FPGA register map
+@b{Note:} All registers are 32 bits-wide. Unaligned accesses, or accesses with data width other than 32 bits are @b{ignored}. Bits not specified in tables are not used (writes are ignored, reads return undefined values).
+
+@anchor{System FPGA Register Map}
   @include svec_xloader.in
 @bye
--- a/doc/firmware-manual/svec_xloader.in
+++ b/doc/firmware-manual/svec_xloader.in
-@subsubsection Memory map summary
+@regsection Memory map summary
 @multitable  @columnfractions .10 .15 .15 .55
 @headitem Address @tab Type @tab Prefix @tab Name
 @item @code{0x0} @tab
@@ -30,7 +30,7 @@ REG @tab
 @code{FIFO_CSR} @tab
 FIFO 'Bitstream FIFO' control/status register
 @end multitable 
-@subsubsection @code{CSR} - Control/status register
+@regsection @code{CSR} - Control/status register
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{0}
@@ -85,7 +85,7 @@ Serial clock divider
 @item @code{EXIT} @tab write 1: terminate bootloader mode and go passive (VME only)
 @item @code{CLKDIV} @tab CCLK division ratio. CCLK frequency = F_sysclk / 2 / (CLKDIV + 1)
 @end multitable
-@subsubsection @code{BTRIGR} - Bootloader Trigger Register
+@regsection @code{BTRIGR} - Bootloader Trigger Register
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{7...0}
@@ -98,7 +98,7 @@ Trigger Sequence Input
 @headitem Field @tab Description
 @item @code{BTRIGR} @tab Write a sequence of 0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe, 0xba, 0xbe to enter bootloader mode (VME only)
 @end multitable
-@subsubsection @code{FAR} - Flash Access Register
+@regsection @code{FAR} - Flash Access Register
 Provides direct access to the SPI flash memory containing the bitstream.
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
@@ -130,7 +130,7 @@ SPI Chip Select
 @item @code{READY} @tab read 1: Core is ready to initiate another transfer. DATA field contains the data read during previous transaction.@*read 0: core is busy
 @item @code{CS} @tab write 1: Enable target SPI controller@*write 0: Disable target SPI controller
 @end multitable
-@subsubsection @code{IDR} - ID Register
+@regsection @code{IDR} - ID Register
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{31...0}
@@ -143,7 +143,7 @@ Identification code
 @headitem Field @tab Description
 @item @code{IDR} @tab User-defined identification code (g_idr_value generic)
 @end multitable
-@subsubsection @code{FIFO_R0} - FIFO 'Bitstream FIFO' data input register 0
+@regsection @code{FIFO_R0} - FIFO 'Bitstream FIFO' data input register 0
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{1...0}
@@ -162,7 +162,7 @@ Last xfer
 @item @code{XSIZE} @tab Number of bytes to send (0 = 1 byte .. 3 = full 32-bit word)
 @item @code{XLAST} @tab write 1: indicates the last word to be written to the FPGA
 @end multitable
-@subsubsection @code{FIFO_R1} - FIFO 'Bitstream FIFO' data input register 1
+@regsection @code{FIFO_R1} - FIFO 'Bitstream FIFO' data input register 1
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{31...0}
@@ -175,7 +175,7 @@ Data
 @headitem Field @tab Description
 @item @code{XDATA} @tab Subsequent words of the bitstream
 @end multitable
-@subsubsection @code{FIFO_CSR} - FIFO 'Bitstream FIFO' control/status register
+@regsection @code{FIFO_CSR} - FIFO 'Bitstream FIFO' control/status register
 @multitable @columnfractions .10 .10 .15 .10 .55
 @headitem Bits @tab Access @tab Prefix @tab Default @tab Name
 @item @code{16}