WebSVN – freemyipod – Diff – /embios/trunk/tools/embios.py

 #    You should have received a copy of the GNU General Public License
 #    along with emBIOS.  If not, see <http://www.gnu.org/licenses/>.
+#
+#
+"""
+    Command line interface to communicate with emBIOS devices.
+    Run it without arguments to see usage information.
+"""
 import sys
 import os
 import time
 import struct
 import locale
         if specific == False or specific == function:
             logger.log(function + " ", 2)
             for arg in doc[function]['args']:
                 logger.log("<" + arg + "> ")
             if doc[function]['kwargs']:
-                for kwarg in doc[function]['kwargs']:
+                for kwvalue, kwarg in enumerate(doc[function]['kwargs']):
-                    logger.log("[" + kwarg + "] ")
+                    logger.log("[" + kwarg + " = " + str(kwvalue) + "] ")
             if doc[function]['varargs']:
                 logger.log("<db1> ... <dbN>")
             logger.log("\n")
             if doc[function]['documentation']:
                 logger.log(doc[function]['documentation']+"\n", 4)
     @command
     def reset(self, force=False):
         """
             Resets the device"
-            If <force> is 1, the reset will be forced, otherwise it will be gracefully,
+            If [force] is 1, the reset will be forced, otherwise it will be gracefully,
             which may take some time.
         """
         force = self._bool(force)
         if force: self.logger.info("Resetting forcefully...\n")
         else: self.logger.info("Resetting...\n")
     @command
     def poweroff(self, force=False):
         """
             Powers the device off
-            If <force> is 1, the poweroff will be forced, otherwise it will be gracefully,
+            If [force] is 1, the poweroff will be forced, otherwise it will be gracefully,
             which may take some time.
         """
         force = self._bool(force)
         if force: self.logger.info("Powering off forcefully...\n")
         else: self.logger.info("Powering off...\n")
     @command
     def i2cread(self, bus, slave, addr, size):
         """
             Reads data from an I2C device
-            <bus> the bus index
+            <bus>: the bus index
-            <slave> the slave address
+            <slave>: the slave address
-            <addr> the start address on the I2C device
+            <addr>: the start address on the I2C device
-            <size> the number of bytes to read
+            <size>: the number of bytes to read
         """
         bus = self._hexint(bus)
         slave = self._hexint(slave)
         addr = self._hexint(addr)
         size = self._hexint(size)
     @command
     def i2cwrite(self, bus, slave, addr, *args):
         """
             Writes data to an I2C device
-            <bus> the bus index
+            <bus>: the bus index
-            <slave> the slave address
+            <slave>: the slave address
-            <addr> the start address on the I2C device
+            <addr>: the start address on the I2C device
-            <db1> ... <dbN> the data in single bytes, encoded in hex,
+            <db1> ... <dbN>: the data in single bytes, encoded in hex,
                 seperated by whitespaces, eg. 37 5A 4F EB
         """
         bus = self._hexint(bus)
         slave = self._hexint(slave)
         addr = self._hexint(addr)
     @command
     def createthread(self, nameptr, entrypoint, stackptr, stacksize, threadtype, priority, state):
         """
             Creates a new thread and returns its thread ID
-            <namepointer> a pointer to the thread's name
+            <namepointer>: a pointer to the thread's name
-            <entrypoint> a pointer to the entrypoint of the thread
+            <entrypoint>: a pointer to the entrypoint of the thread
-            <stackpointer> a pointer to the stack of the thread
+            <stackpointer>: a pointer to the stack of the thread
-            <stacksize> the size of the thread's stack
+            <stacksize>: the size of the thread's stack
-            <type> the thread type, vaild are: 0 => user thread, 1 => system thread
+            <type>: the thread type, vaild are: 0 => user thread, 1 => system thread
-            <priority> the priority of the thread, from 1 to 255
+            <priority>: the priority of the thread, from 1 to 255
-            <state> the thread's initial state, valid are: 1 => ready, 0 => suspended
+            <state>: the thread's initial state, valid are: 1 => ready, 0 => suspended
         """
         nameptr = self._hexint(nameptr)
         entrypoint = self._hexint(entrypoint)
         stackpointer = self._hexint(stackpointer)
         stacksize = self._hexint(stacksize)
             Writes <size> bytes from memory to bootflash.
             ATTENTION: Don't call this unless you really know what you're doing!
             This may BRICK your device (unless it has a good recovery option)
             <addr_mem>: the address in memory to copy the data from
             <addr_bootflsh>: the address in bootflash to write to
-            <force>: Use this flag to suppress the 5 seconds delay
+            [force]: Use this flag to suppress the 5 seconds delay
         """
         addr_flash = self._hexint(addr_flash)
         addr_mem = self._hexint(addr_mem)
         size = self._hexint(size)
         force = self._bool(force)
         self.embios.bootflashwrite(addr_mem, addr_flash, size)
     @command
     def runfirmware(self, addr, filename):
         """
-            Uploads the firmware in 'filename' to the beginning of the
+            Uploads the firmware in <filename>
-            user memory and executes it
+            to the address at <addr> and executes it.
         """
         addr = self._hexint(addr)
         self.uploadfile(addr, filename)
         self.execfirmware(addr)
     @command
     def execfirmware(self, addr):
         """
-            Executes the firmware at addr
+            Executes the firmware at <addr>
         """
         addr = self._hexint(addr)
         self.logger.info("Running firmware at "+self._hex(addr)+". Bye.")
         self.embios.execfirmware(addr)
     @command
     def aesencrypt(self, addr, size, keyindex):
         """
             Encrypts a buffer using a hardware key
+            <addr>: the starting address of the buffer
+            <size>: the size of the buffer
+            <keyindex>: the index of the key in the crypto unit
         """
         addr = self._hexint(addr)
         size = self._hexint(size)
         keyindex = self._hexint(keyindex)
         self.embios.aesencrypt(addr, size, keyindex)
     @command
     def aesdecrypt(self, addr, size, keyindex):
         """
             Decrypts a buffer using a hardware key
+            <addr>: the starting address of the buffer
+            <size>: the size of the buffer
+            <keyindex>: the index of the key in the crypto unit
         """
         addr = self._hexint(addr)
         size = self._hexint(size)
         keyindex = self._hexint(keyindex)
         self.embios.aesdecrypt(addr, size, keyindex)
     @command
     def hmac_sha1(self, addr, size, destination):
         """
-            Generates a HMAC-SHA1 hash of the buffer and saves it to 'destination'
+            Generates a HMAC-SHA1 hash of the buffer
+            <addr>: the starting address of the buffer
+            <size>: the size of the buffer
+            <destination>: the location where the key will be stored
         """
         addr = self._hexint(addr)
         size = self._hexint(size)
         destination = self._hexint(destination)
         sha1size = 0x14
     @command
     def ipodnano2g_nandread(self, addr, start, count, doecc, checkempty):
         """
             Target-specific function: ipodnano2g
             Reads data from the NAND chip into memory
+            <addr>: the memory location where the data is written to
+            <start>: start block
+            <count>: block count
+            <doecc>: FIXME
+            <checkempty>: FIXME
         """
         addr = self._hexint(addr)
         start = self._hexint(start)
         count = self._hexint(count)
-        doecc = int(doecc)
+        doecc = int(doecc) # FIXME shouldn't this be bool?
         checkempty = int(checkempty)
         self.logger.info("Reading " + self._hex(count) + " NAND pages starting at " + \
                          self._hex(start) + " to " + self._hex(addr) + "...")
         self.embios.ipodnano2g_nandread(addr, start, count, doecc, checkempty)
         self.logger.info("done\n")
     @command
     def ipodnano2g_nandwrite(self, addr, start, count, doecc):
         """
             Target-specific function: ipodnano2g
             Writes data to the NAND chip
+            <addr>: the memory location where the data is read from
+            <start>: start block
+            <count>: block count
+            <doecc>: FIXME
         """
         addr = self._hexint(addr)
         start = self._hexint(start)
         count = self._hexint(count)
-        doecc = int(doecc)
+        doecc = int(doecc) # FIXME shouldn't this be bool?
         self.logger.info("Writing " + self._hex(count) + " NAND pages starting at " + \
                          self._hex(start) + " from " + self._hex(addr) + "...")
         self.embios.ipodnano2g_nandwrite(addr, start, count, doecc)
         self.logger.info("done\n")
     @command
     def ipodnano2g_nanderase(self, addr, start, count):
         """
             Target-specific function: ipodnano2g
             Erases blocks on the NAND chip and stores the results to memory
+            <addr>: the memory location where the results are stored
+            <start>: start block
+            <count>: block count
         """
         addr = self._hexint(addr)
         start = self._hexint(start)
         count = self._hexint(count)
         self.logger.info("Erasing " + self._hex(count) + " NAND blocks starting at " + \
     @command
     def ipodnano2g_dumpnand(self, filenameprefix):
         """
             Target-specific function: ipodnano2g
             Dumps the whole NAND chip to four files
+            <filenameprefix>: prefix of the files that will be created
         """
         info = self.embios.ipodnano2g_getnandinfo()
         self.logger.info("Dumping NAND contents...")
         try:
             infofile = open(filenameprefix+"_info.txt", 'wb')
     @command
     def ipodnano2g_wipenand(self, filename, force=False):
         """
             Target-specific function: ipodnano2g
             Wipes the whole NAND chip and logs the result to a file
+            <filename>: location of the log file
-            <force>: Use this flag to suppress the 5 seconds delay
+            [force]: use this flag to suppress the 5 seconds delay
         """
         self.logger.warn("Wiping the whole NAND chip!\n")
         if force == False:
             self.logger.warn("If this was not what you intended press Ctrl-C NOW")
             for i in range(10):
     @command
     def getvolumeinfo(self, volume):
         """
             Gathers some information about a storage volume used
+            <volume>: FIXME
         """
         volume = self._hexint(volume)
         data = self.embios.storage_get_info(volume)
         self.logger.info("Sector size: "+str(data["sectorsize"])+"\n")
         self.logger.info("Number of sectors: "+str(data["numsectors"])+"\n")
     @command
     def readrawstoragefile(self, volume, sector, count, file, buffer = False, buffsize = "100000"):
         """
             Reads <count> sectors starting at <sector> from storage <volume> to file <file>,
-            buffering them in memory at <buffer> in chunks of <buffsize> bytes (both optional).
+            buffering them in memory at [buffer] in chunks of [buffsize] bytes (both optional).
         """
         volume = self._hexint(volume)
         sector = self._hexint(sector)
         count = self._hexint(count)
         if buffer == False: buffer = self.embios.lib.dev.usermem.lower
     @command
     def writerawstoragefile(self, volume, sector, count, file, buffer = False, buffsize = "100000"):
         """
             Writes contents of <file> to <count> sectors starting at <sector> on storage <volume>,
-            buffering them in memory at <buffer> in chunks of <buffsize> bytes (both optional).
+            buffering them in memory at [buffer] in chunks of [buffsize] bytes (both optional).
         """
         volume = self._hexint(volume)
         sector = self._hexint(sector)
         count = self._hexint(count)
         if buffer == False: buffer = self.embios.lib.dev.usermem.lower
         self.logger.info("done\n")
     @command
     def mkdir(self, dirname):
         """
-            Creates a directory
+            Creates a directory with the name <dirname>
         """
         self.logger.info("Creating directory " + dirname + "...")
         self.embios.dir_create(dirname)
         self.logger.info(" done\n")
     @command
     def rmdir(self, dirname):
         """
-            Removes an empty directory
+            Removes an empty directory with the name <dirname>
         """
         self.logger.info("Removing directory " + dirname + "...")
         self.embios.dir_remove(dirname)
         self.logger.info(" done\n")
     @command
     def rm(self, filename):
         """
-            Removes a file
+            Removes a file with the name <filename>
         """
         self.logger.info("Removing file " + filename + "...")
         self.embios.file_unlink(filename)
         self.logger.info(" done\n")
     @command
     def mv(self, oldname, newname):
         """
-            Renames or moves a file or directory
+            Renames or moves file or directory <oldname> to <newname>
         """
         self.logger.info("Renaming " + oldname + " to " + newname + "...")
         self.embios.file_rename(oldname, newname)
         self.logger.info(" done\n")
     @command
     def get(self, remotename, localname, buffer = False, buffsize = "10000"):
         """
             Downloads a file
+            <remotename>: filename on the device
+            <localname>: filename on the computer
+            [buffer]: buffer address (optional)
+            [buffsize]: buffer size (optional)
         """
         if buffer == False: buffer = self.embios.lib.dev.usermem.lower
         else: buffer = self._hexint(buffer)
         buffsize = self._hexint(buffsize)
         try:
     @command
     def put(self, localname, remotename, buffer = False, buffsize = "10000"):
         """
             Uploads a file
+            <remotename>: filename on the device
+            <localname>: filename on the computer
+            [buffer]: buffer address (optional)
+            [buffsize]: buffer size (optional)
         """
         if buffer == False: buffer = self.embios.lib.dev.usermem.lower
         else: buffer = self._hexint(buffer)
         buffsize = self._hexint(buffsize)
         try:
     @command
     def ls(self, path = "/"):
         """
             Lists all files in the specified path
+            [path]: the path which is listed
         """
         handle = self.embios.dir_open(path)
         self.logger.info("Directory listing of " + path + ":\n")
         while True:
             try:

Subversion Repositories freemyipod

(root)/embios/trunk/tools/embios.py @ 402 – Rev 401 → 402