| Index: embios/trunk/tools/embios.py |
| — | — | @@ -21,6 +21,11 @@ |
| 22 | 22 | #
|
| 23 | 23 | #
|
| 24 | 24 |
|
| | 25 | +"""
|
| | 26 | + Command line interface to communicate with emBIOS devices.
|
| | 27 | + Run it without arguments to see usage information.
|
| | 28 | +"""
|
| | 29 | +
|
| 25 | 30 | import sys
|
| 26 | 31 | import os
|
| 27 | 32 | import time
|
| — | — | @@ -71,8 +76,8 @@ |
| 72 | 77 | for arg in doc[function]['args']:
|
| 73 | 78 | logger.log("<" + arg + "> ")
|
| 74 | 79 | if doc[function]['kwargs']:
|
| 75 | | - for kwarg in doc[function]['kwargs']:
|
| 76 | | - logger.log("[" + kwarg + "] ")
|
| | 80 | + for kwvalue, kwarg in enumerate(doc[function]['kwargs']):
|
| | 81 | + logger.log("[" + kwarg + " = " + str(kwvalue) + "] ")
|
| 77 | 82 | if doc[function]['varargs']:
|
| 78 | 83 | logger.log("<db1> ... <dbN>")
|
| 79 | 84 | logger.log("\n")
|
| — | — | @@ -235,7 +240,7 @@ |
| 236 | 241 | def reset(self, force=False):
|
| 237 | 242 | """
|
| 238 | 243 | Resets the device"
|
| 239 | | - If <force> is 1, the reset will be forced, otherwise it will be gracefully,
|
| | 244 | + If [force] is 1, the reset will be forced, otherwise it will be gracefully,
|
| 240 | 245 | which may take some time.
|
| 241 | 246 | """
|
| 242 | 247 | force = self._bool(force)
|
| — | — | @@ -247,7 +252,7 @@ |
| 248 | 253 | def poweroff(self, force=False):
|
| 249 | 254 | """
|
| 250 | 255 | Powers the device off
|
| 251 | | - If <force> is 1, the poweroff will be forced, otherwise it will be gracefully,
|
| | 256 | + If [force] is 1, the poweroff will be forced, otherwise it will be gracefully,
|
| 252 | 257 | which may take some time.
|
| 253 | 258 | """
|
| 254 | 259 | force = self._bool(force)
|
| — | — | @@ -328,10 +333,10 @@ |
| 329 | 334 | def i2cread(self, bus, slave, addr, size):
|
| 330 | 335 | """
|
| 331 | 336 | Reads data from an I2C device
|
| 332 | | - <bus> the bus index
|
| 333 | | - <slave> the slave address
|
| 334 | | - <addr> the start address on the I2C device
|
| 335 | | - <size> the number of bytes to read
|
| | 337 | + <bus>: the bus index
|
| | 338 | + <slave>: the slave address
|
| | 339 | + <addr>: the start address on the I2C device
|
| | 340 | + <size>: the number of bytes to read
|
| 336 | 341 | """
|
| 337 | 342 | bus = self._hexint(bus)
|
| 338 | 343 | slave = self._hexint(slave)
|
| — | — | @@ -347,10 +352,10 @@ |
| 348 | 353 | def i2cwrite(self, bus, slave, addr, *args):
|
| 349 | 354 | """
|
| 350 | 355 | Writes data to an I2C device
|
| 351 | | - <bus> the bus index
|
| 352 | | - <slave> the slave address
|
| 353 | | - <addr> the start address on the I2C device
|
| 354 | | - <db1> ... <dbN> the data in single bytes, encoded in hex,
|
| | 356 | + <bus>: the bus index
|
| | 357 | + <slave>: the slave address
|
| | 358 | + <addr>: the start address on the I2C device
|
| | 359 | + <db1> ... <dbN>: the data in single bytes, encoded in hex,
|
| 355 | 360 | seperated by whitespaces, eg. 37 5A 4F EB
|
| 356 | 361 | """
|
| 357 | 362 | bus = self._hexint(bus)
|
| — | — | @@ -510,13 +515,13 @@ |
| 511 | 516 | def createthread(self, nameptr, entrypoint, stackptr, stacksize, threadtype, priority, state):
|
| 512 | 517 | """
|
| 513 | 518 | Creates a new thread and returns its thread ID
|
| 514 | | - <namepointer> a pointer to the thread's name
|
| 515 | | - <entrypoint> a pointer to the entrypoint of the thread
|
| 516 | | - <stackpointer> a pointer to the stack of the thread
|
| 517 | | - <stacksize> the size of the thread's stack
|
| 518 | | - <type> the thread type, vaild are: 0 => user thread, 1 => system thread
|
| 519 | | - <priority> the priority of the thread, from 1 to 255
|
| 520 | | - <state> the thread's initial state, valid are: 1 => ready, 0 => suspended
|
| | 519 | + <namepointer>: a pointer to the thread's name
|
| | 520 | + <entrypoint>: a pointer to the entrypoint of the thread
|
| | 521 | + <stackpointer>: a pointer to the stack of the thread
|
| | 522 | + <stacksize>: the size of the thread's stack
|
| | 523 | + <type>: the thread type, vaild are: 0 => user thread, 1 => system thread
|
| | 524 | + <priority>: the priority of the thread, from 1 to 255
|
| | 525 | + <state>: the thread's initial state, valid are: 1 => ready, 0 => suspended
|
| 521 | 526 | """
|
| 522 | 527 | nameptr = self._hexint(nameptr)
|
| 523 | 528 | entrypoint = self._hexint(entrypoint)
|
| — | — | @@ -586,7 +591,7 @@ |
| 587 | 592 | This may BRICK your device (unless it has a good recovery option)
|
| 588 | 593 | <addr_mem>: the address in memory to copy the data from
|
| 589 | 594 | <addr_bootflsh>: the address in bootflash to write to
|
| 590 | | - <force>: Use this flag to suppress the 5 seconds delay
|
| | 595 | + [force]: Use this flag to suppress the 5 seconds delay
|
| 591 | 596 | """
|
| 592 | 597 | addr_flash = self._hexint(addr_flash)
|
| 593 | 598 | addr_mem = self._hexint(addr_mem)
|
| — | — | @@ -605,8 +610,8 @@ |
| 606 | 611 | @command
|
| 607 | 612 | def runfirmware(self, addr, filename):
|
| 608 | 613 | """
|
| 609 | | - Uploads the firmware in 'filename' to the beginning of the
|
| 610 | | - user memory and executes it
|
| | 614 | + Uploads the firmware in <filename>
|
| | 615 | + to the address at <addr> and executes it.
|
| 611 | 616 | """
|
| 612 | 617 | addr = self._hexint(addr)
|
| 613 | 618 | self.uploadfile(addr, filename)
|
| — | — | @@ -615,7 +620,7 @@ |
| 616 | 621 | @command
|
| 617 | 622 | def execfirmware(self, addr):
|
| 618 | 623 | """
|
| 619 | | - Executes the firmware at addr
|
| | 624 | + Executes the firmware at <addr>
|
| 620 | 625 | """
|
| 621 | 626 | addr = self._hexint(addr)
|
| 622 | 627 | self.logger.info("Running firmware at "+self._hex(addr)+". Bye.")
|
| — | — | @@ -625,6 +630,9 @@ |
| 626 | 631 | def aesencrypt(self, addr, size, keyindex):
|
| 627 | 632 | """
|
| 628 | 633 | Encrypts a buffer using a hardware key
|
| | 634 | + <addr>: the starting address of the buffer
|
| | 635 | + <size>: the size of the buffer
|
| | 636 | + <keyindex>: the index of the key in the crypto unit
|
| 629 | 637 | """
|
| 630 | 638 | addr = self._hexint(addr)
|
| 631 | 639 | size = self._hexint(size)
|
| — | — | @@ -635,6 +643,9 @@ |
| 636 | 644 | def aesdecrypt(self, addr, size, keyindex):
|
| 637 | 645 | """
|
| 638 | 646 | Decrypts a buffer using a hardware key
|
| | 647 | + <addr>: the starting address of the buffer
|
| | 648 | + <size>: the size of the buffer
|
| | 649 | + <keyindex>: the index of the key in the crypto unit
|
| 639 | 650 | """
|
| 640 | 651 | addr = self._hexint(addr)
|
| 641 | 652 | size = self._hexint(size)
|
| — | — | @@ -644,7 +655,10 @@ |
| 645 | 656 | @command
|
| 646 | 657 | def hmac_sha1(self, addr, size, destination):
|
| 647 | 658 | """
|
| 648 | | - Generates a HMAC-SHA1 hash of the buffer and saves it to 'destination'
|
| | 659 | + Generates a HMAC-SHA1 hash of the buffer
|
| | 660 | + <addr>: the starting address of the buffer
|
| | 661 | + <size>: the size of the buffer
|
| | 662 | + <destination>: the location where the key will be stored
|
| 649 | 663 | """
|
| 650 | 664 | addr = self._hexint(addr)
|
| 651 | 665 | size = self._hexint(size)
|
| — | — | @@ -677,11 +691,16 @@ |
| 678 | 692 | """
|
| 679 | 693 | Target-specific function: ipodnano2g
|
| 680 | 694 | Reads data from the NAND chip into memory
|
| | 695 | + <addr>: the memory location where the data is written to
|
| | 696 | + <start>: start block
|
| | 697 | + <count>: block count
|
| | 698 | + <doecc>: FIXME
|
| | 699 | + <checkempty>: FIXME
|
| 681 | 700 | """
|
| 682 | 701 | addr = self._hexint(addr)
|
| 683 | 702 | start = self._hexint(start)
|
| 684 | 703 | count = self._hexint(count)
|
| 685 | | - doecc = int(doecc)
|
| | 704 | + doecc = int(doecc) # FIXME shouldn't this be bool?
|
| 686 | 705 | checkempty = int(checkempty)
|
| 687 | 706 | self.logger.info("Reading " + self._hex(count) + " NAND pages starting at " + \
|
| 688 | 707 | self._hex(start) + " to " + self._hex(addr) + "...")
|
| — | — | @@ -693,11 +712,15 @@ |
| 694 | 713 | """
|
| 695 | 714 | Target-specific function: ipodnano2g
|
| 696 | 715 | Writes data to the NAND chip
|
| | 716 | + <addr>: the memory location where the data is read from
|
| | 717 | + <start>: start block
|
| | 718 | + <count>: block count
|
| | 719 | + <doecc>: FIXME
|
| 697 | 720 | """
|
| 698 | 721 | addr = self._hexint(addr)
|
| 699 | 722 | start = self._hexint(start)
|
| 700 | 723 | count = self._hexint(count)
|
| 701 | | - doecc = int(doecc)
|
| | 724 | + doecc = int(doecc) # FIXME shouldn't this be bool?
|
| 702 | 725 | self.logger.info("Writing " + self._hex(count) + " NAND pages starting at " + \
|
| 703 | 726 | self._hex(start) + " from " + self._hex(addr) + "...")
|
| 704 | 727 | self.embios.ipodnano2g_nandwrite(addr, start, count, doecc)
|
| — | — | @@ -708,6 +731,9 @@ |
| 709 | 732 | """
|
| 710 | 733 | Target-specific function: ipodnano2g
|
| 711 | 734 | Erases blocks on the NAND chip and stores the results to memory
|
| | 735 | + <addr>: the memory location where the results are stored
|
| | 736 | + <start>: start block
|
| | 737 | + <count>: block count
|
| 712 | 738 | """
|
| 713 | 739 | addr = self._hexint(addr)
|
| 714 | 740 | start = self._hexint(start)
|
| — | — | @@ -722,6 +748,7 @@ |
| 723 | 749 | """
|
| 724 | 750 | Target-specific function: ipodnano2g
|
| 725 | 751 | Dumps the whole NAND chip to four files
|
| | 752 | + <filenameprefix>: prefix of the files that will be created
|
| 726 | 753 | """
|
| 727 | 754 | info = self.embios.ipodnano2g_getnandinfo()
|
| 728 | 755 | self.logger.info("Dumping NAND contents...")
|
| — | — | @@ -754,7 +781,8 @@ |
| 755 | 782 | """
|
| 756 | 783 | Target-specific function: ipodnano2g
|
| 757 | 784 | Wipes the whole NAND chip and logs the result to a file
|
| 758 | | - <force>: Use this flag to suppress the 5 seconds delay
|
| | 785 | + <filename>: location of the log file
|
| | 786 | + [force]: use this flag to suppress the 5 seconds delay
|
| 759 | 787 | """
|
| 760 | 788 | self.logger.warn("Wiping the whole NAND chip!\n")
|
| 761 | 789 | if force == False:
|
| — | — | @@ -797,6 +825,7 @@ |
| 798 | 826 | def getvolumeinfo(self, volume):
|
| 799 | 827 | """
|
| 800 | 828 | Gathers some information about a storage volume used
|
| | 829 | + <volume>: FIXME
|
| 801 | 830 | """
|
| 802 | 831 | volume = self._hexint(volume)
|
| 803 | 832 | data = self.embios.storage_get_info(volume)
|
| — | — | @@ -836,7 +865,7 @@ |
| 837 | 866 | def readrawstoragefile(self, volume, sector, count, file, buffer = False, buffsize = "100000"):
|
| 838 | 867 | """
|
| 839 | 868 | Reads <count> sectors starting at <sector> from storage <volume> to file <file>,
|
| 840 | | - buffering them in memory at <buffer> in chunks of <buffsize> bytes (both optional).
|
| | 869 | + buffering them in memory at [buffer] in chunks of [buffsize] bytes (both optional).
|
| 841 | 870 | """
|
| 842 | 871 | volume = self._hexint(volume)
|
| 843 | 872 | sector = self._hexint(sector)
|
| — | — | @@ -863,7 +892,7 @@ |
| 864 | 893 | def writerawstoragefile(self, volume, sector, count, file, buffer = False, buffsize = "100000"):
|
| 865 | 894 | """
|
| 866 | 895 | Writes contents of <file> to <count> sectors starting at <sector> on storage <volume>,
|
| 867 | | - buffering them in memory at <buffer> in chunks of <buffsize> bytes (both optional).
|
| | 896 | + buffering them in memory at [buffer] in chunks of [buffsize] bytes (both optional).
|
| 868 | 897 | """
|
| 869 | 898 | volume = self._hexint(volume)
|
| 870 | 899 | sector = self._hexint(sector)
|
| — | — | @@ -893,7 +922,7 @@ |
| 894 | 923 | @command
|
| 895 | 924 | def mkdir(self, dirname):
|
| 896 | 925 | """
|
| 897 | | - Creates a directory
|
| | 926 | + Creates a directory with the name <dirname>
|
| 898 | 927 | """
|
| 899 | 928 | self.logger.info("Creating directory " + dirname + "...")
|
| 900 | 929 | self.embios.dir_create(dirname)
|
| — | — | @@ -902,7 +931,7 @@ |
| 903 | 932 | @command
|
| 904 | 933 | def rmdir(self, dirname):
|
| 905 | 934 | """
|
| 906 | | - Removes an empty directory
|
| | 935 | + Removes an empty directory with the name <dirname>
|
| 907 | 936 | """
|
| 908 | 937 | self.logger.info("Removing directory " + dirname + "...")
|
| 909 | 938 | self.embios.dir_remove(dirname)
|
| — | — | @@ -911,7 +940,7 @@ |
| 912 | 941 | @command
|
| 913 | 942 | def rm(self, filename):
|
| 914 | 943 | """
|
| 915 | | - Removes a file
|
| | 944 | + Removes a file with the name <filename>
|
| 916 | 945 | """
|
| 917 | 946 | self.logger.info("Removing file " + filename + "...")
|
| 918 | 947 | self.embios.file_unlink(filename)
|
| — | — | @@ -920,7 +949,7 @@ |
| 921 | 950 | @command
|
| 922 | 951 | def mv(self, oldname, newname):
|
| 923 | 952 | """
|
| 924 | | - Renames or moves a file or directory
|
| | 953 | + Renames or moves file or directory <oldname> to <newname>
|
| 925 | 954 | """
|
| 926 | 955 | self.logger.info("Renaming " + oldname + " to " + newname + "...")
|
| 927 | 956 | self.embios.file_rename(oldname, newname)
|
| — | — | @@ -930,6 +959,10 @@ |
| 931 | 960 | def get(self, remotename, localname, buffer = False, buffsize = "10000"):
|
| 932 | 961 | """
|
| 933 | 962 | Downloads a file
|
| | 963 | + <remotename>: filename on the device
|
| | 964 | + <localname>: filename on the computer
|
| | 965 | + [buffer]: buffer address (optional)
|
| | 966 | + [buffsize]: buffer size (optional)
|
| 934 | 967 | """
|
| 935 | 968 | if buffer == False: buffer = self.embios.lib.dev.usermem.lower
|
| 936 | 969 | else: buffer = self._hexint(buffer)
|
| — | — | @@ -953,6 +986,10 @@ |
| 954 | 987 | def put(self, localname, remotename, buffer = False, buffsize = "10000"):
|
| 955 | 988 | """
|
| 956 | 989 | Uploads a file
|
| | 990 | + <remotename>: filename on the device
|
| | 991 | + <localname>: filename on the computer
|
| | 992 | + [buffer]: buffer address (optional)
|
| | 993 | + [buffsize]: buffer size (optional)
|
| 957 | 994 | """
|
| 958 | 995 | if buffer == False: buffer = self.embios.lib.dev.usermem.lower
|
| 959 | 996 | else: buffer = self._hexint(buffer)
|
| — | — | @@ -978,6 +1015,7 @@ |
| 979 | 1016 | def ls(self, path = "/"):
|
| 980 | 1017 | """
|
| 981 | 1018 | Lists all files in the specified path
|
| | 1019 | + [path]: the path which is listed
|
| 982 | 1020 | """
|
| 983 | 1021 | handle = self.embios.dir_open(path)
|
| 984 | 1022 | self.logger.info("Directory listing of " + path + ":\n")
|
| Index: embios/trunk/tools/libembios.py |
| — | — | @@ -21,6 +21,11 @@ |
| 22 | 22 | #
|
| 23 | 23 | #
|
| 24 | 24 |
|
| | 25 | +"""
|
| | 26 | + emBIOS client library.
|
| | 27 | + Provides functions to communicate with emBIOS devices via the USB bus.
|
| | 28 | +"""
|
| | 29 | +
|
| 25 | 30 | import sys
|
| 26 | 31 | import struct
|
| 27 | 32 | import usb.core
|
