
 1. Install the driver
 ---------------------

  a sudo make install in driver/orinoco-0.13b-hermesap-0.1a/ should do it
  if you get unresolved symbols reinstall your kernel and/or
  pcmcia_cs properly
  if it still doesn't work you _could_ but _shouldn't_ ;) just
  copy all the .c and .h files from driver/orinoco-0.13b-hermesap-0.1a/ 
  over the ones of your kernel or pcmcia_cs and recompile+install your 
  kernel or pcmcia_cs

 2. Find a Tertiary (=AP mode) firmware
 --------------------------------------

 - Why is there no firmware included?
 + Since I don't have any license / copyright information on Tertiary
   Firmware(s) I won't include them here.
   So you have to find / extract one yourself as explained here.

 Now you need an Tertiary Firmware to enable BSS master mode.
 Any Accesspoint driver for Hermes cards contains such a firmware,
 since the Firmware gets loaded into the RAM of the Card during init.
 We have to extract this Firmware from the Binary now.
 If you know someone with an Apple and MacOSX installed on it you'll
 find such an AP mode driver with Tertiary Firmware here:
 /System/Library/Extensions/AppleAirPortFW.kext/Contents/MacOS/AppleAirPortFW
 This will also be the easiest solution, since I will take this binary
 (taken from the pmac of my parents :)) as example here.

 5083e8db3c0ac336eaf857b5d339d96e is the MD5sum of the AppleAirPortFW
 I've got - if it matches the MD5sum of yours you can skip most of the
 stuff here sice you can use the offsets from the example I'll use here. 

 3. Extract the Tertiary firmware from our binary
 ------------------------------------------------

 The binfw2hfw tool in the hfw/ dir will extract the firmware and 
 write it in ASCII (in hex) to stdout.
 The arguments for this tool are:
 binfw2hfw <file> <plugs-ofs> <segms-ofs> <segm_1> ... <segm_n>
 file is the binary file
 plugs-ofs is the offset of the plugrecods array in the binary
 segms-ofs is the offset of the segmentrecords array in the binary
 segm_1
 ...
 segm_n are the offsets of each firmware data segment in the binary

 If you didn't take the MacOSX binary but a little endian binary then
 you have to change line 16 of hfw/binfw2hfw.c from:
 src_endian= __BIG_ENDIAN; //__LITTLE_ENDIAN;
 to
 src_endian= __LITTLE_ENDIAN;

 Now you've got to find these (plugs, segms, segm_datas) offsets.
 Now is the time to grab an hexeditor and load the binary with it.

 Now we search for ".HEX" and will find A1XXYYZZ.HEX
 A will indicate what type of firmware we found:
   P for Primary
   S for Secondary / Station
   T for Tertiary - this is the one we need
 XX.YY is the firmware version
 e.g.: T1084000.HEX ist Tertiary Firmware v8.40

 In the AppleAirPortFW (and maybe also in other binaries) we will also find
 a Primary and Secondary Firmware but we don't need them so we ignore it.

 From this T1XXYYZZ.HEX we now seek backwards for hex 61 44 fe
 This is the beginning of the Tertiary FW (Secondary FWs also begin with that)
 In the AppleAirPortFW we'll find it at 0x10b6a from which we seek back 6 byte
 to 0x10B64 - these 6 byte are (in this FW) 00 48 1f 00 02 a4
 they are: 32 bit card_offset, 16 bit size and they are in little endian
 (even if our binary is big endian - these values are offsets for the card
 and the card does little endian)
 so 001f4800 and a402 will be their big endian representation
 1f4800 is the memoryoffset of the card to which this segment will be written
 the 2nd means: this segment is a402 byte long (alway must be even since
 the card usually only accepts word read/writes - although my hermes_mem
 device will handle odd reads and writes correctly for convenience of the user)

 Let's look for the segmentrecords array now - we got the layout of the 1st
 segment now, so we can find the segmentrecords array:
 The card offset of the 1st segment is 1f4800 in bigendian, 481f00 in little.
 Now we search for that - if our binary is little endian we take the little
 endian, otherwise (for MacOSX e.g.) we take the big.
 We'll find 00 1f 48 00 at 0x1c0c8 followed by 00 00 a4 02 (our segment len)
 and 00 00 00 00 (we ignore that for now)
 After that we'll find the next segment: card offset 00 1f f0 00
 length 00 00 10 00 and the trailing 00 00 00 00
 Where the offset of the next segment should be are only zeros so there
 are no more segments.

 Now we add the length of the 1st segment a402 to the offset of our 1st segment
 plus 6 (0x10B64+0xa402+6=0x1AF6C). Here we find the 2nd (last) segment:
 00 f0 1f 00 00 10 --big endian--> offset 00 1f f0 00 length 10 00
 
 We've got the Offsets of the Segments and of the Segmentrecords array now.
 What remains is the Plugrecords Array:

 It should be above the segmentrecords array and has the following structure:
 u32 code
 u32 target_offset
 u32 length
 mention that these values are little endian if you've got a le binary
 the code starts with FF and is followed by 00 for PDR entries
 (we ingore other entries for now)
 so if we look back up the file we'll find the 1st valid plugrecord at 
 0x1BF78: ff 00 00 03 | 00 1f cb b6 | 00 00 00 0c
 (that's the code for the NIC Serial Number and usually the 1st plugrecord
 and therefor a good code+len to look for when seeking the plugrecords array
 the target_offset depends on the firmware)

 So we finally got everything we need - but wait! don't close your hexeditor
 yet. We'll verify one last thing later...

 But first we extract the firmware with the values we obtained from our dig
 int the binary above:
 
 binfw2hfw ~/lucent/AppleAirPortFW 0x1BF78 0x1C0C8 0x10B64 0x1AF6C > T1084000.hfw
 If you got an error: xyz seems to be invalid you probably didn't find the
 right offset with your hexeditor - retry it ;)
 If everything worked we got this hfwfile - open it with any texteditor - 
 it should have the following structure:
 
 PLUG  FF00... ... ...
 PLUG  FF00... ... ...
 ...
 SEG   ... ... ...
 DATA ...
 DATA ...
 ...
 SEG ... ... ...
 DATA ...
 DATA ...
 ...
 
 But two lines are missing and we've got to add them manually:

 The Entrypoint for the Firmware - syntax: "ENTRY <OFFSET>"
 _usually_ this entrypoint is 001F4808 but maybe, it is not for your firmware.
 Now is the time so grab your hexeditor again and verify this entrypoint.
 The card wants the entrypoint divided by 2 - so is it stored in your binary
 001F4808/2 = FA404 - we search for that (it's always in big endian) 
 in the binary. we will find two u32 values in front of it - if they are equal
 then the entrypoint _should_ be ok ;)
 If not - uhm 8) - look for u32 a, u32 b, u32 c where:
 (a == b) && (c is withing the card_offset of a segment)
 This can be done quite well in C but i didn't do that yet since all firmwares
 I got until now have their entrypoint at 001F4808.
 
 We now add this entrypoint not-divided by 2 ;) before the first PLUG line
 in our hfw file.

 For example if FA404 is the entrypoint from our binary we will add the line:
 ENTRY 001F4808
 before the 1st PLUG line.

 Now we add the second missing line containing "HFW1" 
 _before_ the ENTRY line we just added. That's all.

 Gratulations!! :)) The hard work is done and you may finally send the
 hexeditor as well as the binary back to hell - you'll never need them again
 (well ok you'll need the hexeditor again if you want to extract a new 
 firmware version ;))
 Now you've got the extracted hfw firmware file you can upload any time.
 Relax and have a break - the hard part is done ;)

 4. Upload the firmware into the card
 ------------------------------------

 Upload the extracted hfw file from chapter 3 into your card - e.g.:
 sudo ./hfwload eth1 ~/lucent/hfw/firmware/hermes/T1084000-ram.hfw
 (the network device must be down (ifconfig eth1 down) before doing this)
 If you didn't get an error your card probably accepted the AP mode firmware.

 5. AP mode
 ----------

 now your can do an ifconfig eth1 up and the card will start broadcasting
 beacons (you'll see the RX/TX Led flashing - if not something probably
 went wrong ;()

 in iwconfig ethX you should now see Mode: Master

 you may set an SSID with iwconfig ethX essid foobar
 zero-length ("Any") won't work in BSS mode - if you want hidden mode do:
 iwpriv ethX hidden 1
 you may turn it of again with
 iwpriv ethX hidden 0

 you can also set the channel with iwconfig ethX channel X

 WEP _should_ work as usual - you can configure wepkeys with 
 iwconfig ethX enc s:...

 other stuff is untested / not working yet
 but have a look at the TODO before asking for features ;)

 ---------------------------------------------------------------------------

 Please don't send me firmwares or binaries via mail - send me an URL
 from which I can get them if you think i should have a look at it.

 If you have a question please look at the FAQ first.

 Don't ask me to give you a firmware -> see FAQ

 If you have any bugreports/comments/feature requests/etc mail me:
 hermesap@hunz.org

 I'd appreciate it if someone could provide a web based discussion board
 since I don't like mailinglists very much.
 The advantage over direct mails to me is that several users often have 
 the same questions 
 and so I (or someone else) only have to answer them once in the Board. 

   -Hunz <hermesap@hunz.org>
   

