diff --git a/.gitignore b/.gitignore index 8bc2baf..f995022 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ dist *.pyc __pycache__ site +.venv diff --git a/README.md b/README.md index 15c1c36..34e0b42 100644 --- a/README.md +++ b/README.md @@ -469,9 +469,12 @@ directory: ### Build Docs - pip3 install mkdocs + python3 -m venv .venv + source .venv/bin/activate + pip install -e . + pip install mkdocs cd docs - ./generate_docs.py + generate_docs.py cd .. mkdocs serve --dev-addr=0.0.0.0:8001 diff --git a/docs/.gitignore b/docs/.gitignore index cbf12de..6a2747b 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,3 @@ _build site +*.md \ No newline at end of file diff --git a/docs/app_installed.md b/docs/app_installed.md deleted file mode 100644 index 0842c2a..0000000 --- a/docs/app_installed.md +++ /dev/null @@ -1,349 +0,0 @@ -# Package tockloader.app_installed Documentation - -## Class InstalledApp -Representation of a Tock app that is installed on a specific board. This -object is created when Tockloader finds an app already installed on a board. - -At the very least this includes the TBF header and an address of where the -app is on the board. It can also include the actual app binary which is -necessary if the app needs to be moved. -### \_\_init\_\_ -```py - -def __init__(self, tbfh, tbff, address, app_binary=None) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### filter\_fixed\_ram\_address -```py - -def filter_fixed_ram_address(self, ram_address) - -``` - - - -Specify the start of RAM to filter TBFs in this TAB. For installed apps -this is a no-op because presumably we only installed apps that have a -reasonable RAM parameter. - - -### fix\_at\_next\_loadable\_address -```py - -def fix_at_next_loadable_address(self, address) - -``` - - - -Calculate the next reasonable address where we can put this app where -the address is greater than or equal to `address`. The `address` -argument is the earliest address the app can be at, either the start of -apps or immediately after a previous app. - -If the app doesn't have a fixed address, then we can put it anywhere, -and we just return the address. If the app is compiled with fixed -addresses, then we need to calculate an address. We do a little bit of -"reasonable assuming" here. Fixed addresses are based on where the _app -binary_ must be located. Therefore, the start of the app where the TBF -header goes must be before that. This can be at any address (as long as -the header will fit), but we want to make this simpler, so we just -assume the TBF header should start on a 1024 byte alignment. - - -### get\_address -```py - -def get_address(self) - -``` - - - -Get the address of where on the board the app is or should go. - - -### get\_app\_binary -```py - -def get_app_binary(self) - -``` - - - -Return just the compiled application code binary. Does not include -the TBF header. - - -### get\_app\_version -```py - -def get_app_version(self) - -``` - - - -Return the version number stored in a program header. - - -### get\_binary -```py - -def get_binary(self, address) - -``` - - - -Return the binary array comprising the entire application if it needs to -be written to the board. Otherwise, if it is already installed, return -`None`. - - -### get\_fixed\_addresses\_flash\_and\_sizes -```py - -def get_fixed_addresses_flash_and_sizes(self) - -``` - - - -Return a list of tuples of all addresses in flash this app is compiled -for and the size of the app at that address. - -[(address, size), (address, size), ...] - - -### get\_header -```py - -def get_header(self) - -``` - - - -Return the TBFH object for the header. - - -### get\_header\_binary -```py - -def get_header_binary(self) - -``` - - - -Get the TBF header as a bytes array. - - -### get\_header\_size -```py - -def get_header_size(self) - -``` - - - -Return the size of the TBF header in bytes. - - -### get\_name -```py - -def get_name(self) - -``` - - - -Return the app name. - - -### get\_size -```py - -def get_size(self) - -``` - - - -Return the total size (including TBF header) of this app in bytes. - - -### has\_app\_binary -```py - -def has_app_binary(self) - -``` - - - -Whether we have the actual application binary for this app. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -Return true if the TBF binary is compiled for a fixed address. - - -### info -```py - -def info(self, verbose=False) - -``` - - - -Get a string describing various properties of the app. - - -### is\_app -```py - -def is_app(self) - -``` - - - -Whether this is an app or padding. - - -### is\_loadable\_at\_address -```py - -def is_loadable_at_address(self, address) - -``` - - - -Check if it is possible to load this app at the given address. Returns -True if it is possible, False otherwise. - - -### is\_modified -```py - -def is_modified(self) - -``` - - - -Returns whether this app has been modified by tockloader since it was -initially created by `__init__`. - - -### is\_sticky -```py - -def is_sticky(self) - -``` - - - -Returns true if the app is set as sticky and will not be removed with -a normal app erase command. Sticky apps must be force removed. - - -### object -```py - -def object(self) - -``` - - - -Return a dict object containing the information about this app. - - -### set\_app\_binary -```py - -def set_app_binary(self, app_binary) - -``` - - - -Update the application binary. Likely this binary would come from the -existing contents of flash on a board. - - -### set\_size -```py - -def set_size(self, size) - -``` - - - -Force the entire app to be a certain size. If `size` is smaller than the -actual app an error will be thrown. - - -### set\_sticky -```py - -def set_sticky(self) - -``` - - - -Mark this app as "sticky" in the app's header. This makes it harder to -accidentally remove this app if it is a core service or debug app. - - -### verify\_credentials -```py - -def verify_credentials(self, public_keys) - -``` - - - -Using an optional array of public_key binaries, try to check any -contained credentials to verify they are valid. - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - diff --git a/docs/app_padding.md b/docs/app_padding.md deleted file mode 100644 index 7c5395d..0000000 --- a/docs/app_padding.md +++ /dev/null @@ -1,303 +0,0 @@ -# Package tockloader.app_padding Documentation - -## Class InstalledPaddingApp -Representation of a placeholder app that is only padding between other apps -that was extracted from a board. -### \_\_init\_\_ -```py - -def __init__(self, tbfh, address) - -``` - - - -Create a `InstalledPaddingApp` from an extracted TBFH. - - -### get\_address -```py - -def get_address(self) - -``` - - - -Get the address of where on the board this padding app is. - - -### get\_binary -```py - -def get_binary(self, address=None) - -``` - - - -Return the binary array comprising the header and the padding between -apps. - - -### get\_header -```py - -def get_header(self) - -``` - - - -Return the header for this padding. - - -### get\_size -```py - -def get_size(self) - -``` - - - -Return the total size of the padding in bytes. - - -### get\_tbfh -```py - -def get_tbfh(self) - -``` - - - -Return the TBF header. - - -### has\_app\_binary -```py - -def has_app_binary(self) - -``` - - - -We can always return the binary for a padding app, so we can always -return true. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -A padding app is not an executable so can be placed anywhere. - - -### info -```py - -def info(self, verbose=False) - -``` - - - -Get a string describing various properties of the padding. - - -### is\_app -```py - -def is_app(self) - -``` - - - -Whether this is an app or padding. - - -### verify\_credentials -```py - -def verify_credentials(self, public_keys) - -``` - - - -Padding apps do not have credentials, so we ignore this. - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class PaddingApp -Representation of a placeholder app that is only padding between other apps. -### \_\_init\_\_ -```py - -def __init__(self, size, address=None) - -``` - - - -Create a `PaddingApp` based on the amount of size needing in the -padding. - - -### get\_address -```py - -def get_address(self) - -``` - - - -Get the address of where on the board this padding app is. - - -### get\_binary -```py - -def get_binary(self, address=None) - -``` - - - -Return the binary array comprising the header and the padding between -apps. - - -### get\_header -```py - -def get_header(self) - -``` - - - -Return the header for this padding. - - -### get\_size -```py - -def get_size(self) - -``` - - - -Return the total size of the padding in bytes. - - -### get\_tbfh -```py - -def get_tbfh(self) - -``` - - - -Return the TBF header. - - -### has\_app\_binary -```py - -def has_app_binary(self) - -``` - - - -We can always return the binary for a padding app, so we can always -return true. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -A padding app is not an executable so can be placed anywhere. - - -### info -```py - -def info(self, verbose=False) - -``` - - - -Get a string describing various properties of the padding. - - -### is\_app -```py - -def is_app(self) - -``` - - - -Whether this is an app or padding. - - -### verify\_credentials -```py - -def verify_credentials(self, public_keys) - -``` - - - -Padding apps do not have credentials, so we ignore this. - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - diff --git a/docs/app_tab.md b/docs/app_tab.md deleted file mode 100644 index 3ea4426..0000000 --- a/docs/app_tab.md +++ /dev/null @@ -1,473 +0,0 @@ -# Package tockloader.app_tab Documentation - -## Class TabApp -Representation of a Tock app for a specific architecture and board from a -TAB file. This is different from a TAB, since a TAB can include compiled -binaries for a range of architectures, or compiled for various scenarios, -which may not be applicable for a particular board. - -A TabApp need not be a single TabTbf, as an app from a TAB can include -multiple TabTbfs if the app was compiled multiple times. This could be for -any reason (e.g. it was signed with different keys, or it uses different -compiler optimizations), but typically this is because it is compiled for -specific addresses in flash and RAM, and there are multiple linked versions -present in the TAB. If so, there will be multiple TabTbfs included in this -App object, and the correct one for the board will be used later. -### \_\_init\_\_ -```py - -def __init__(self, tbfs) - -``` - - - -Create a `TabApp` from a list of TabTbfs. - - -### add\_credential -```py - -def add_credential(self, credential_type, public_key, private_key, cleartext_id) - -``` - - - -Add a credential by type to the TBF footer. - - -### add\_tbfh\_tlv -```py - -def add_tbfh_tlv(self, tlvid, parameters) - -``` - - - -Add a particular TLV to each TBF's header. - - -### convert -```py - -def convert(self, format) - -``` - - - -Convert a TAB-based app to a different format. Valid formats: -- `cbinary`: Create a C struct with a binary representation of the app. - -This is only valid if there is one TBF file. - - -### corrupt\_tbf -```py - -def corrupt_tbf(self, field_name, value) - -``` - - - -Modify the TBF root header just before installing the application. - - -### delete\_credential -```py - -def delete_credential(self, credential_type) - -``` - - - -Remove a credential by ID from the TBF footer. - - -### delete\_tlv -```py - -def delete_tlv(self, tlvid) - -``` - - - -Delete a particular TLV from each TBF header and footer. - - -### filter\_fixed\_ram\_address -```py - -def filter_fixed_ram_address(self, ram_address) - -``` - - - -Specify the start of RAM to filter TBFs in this TAB. TBFs with fixed RAM -addresses that are not reasonably able to fit with the available RAM are -ignored from the TAB. - - -### fix\_at\_next\_loadable\_address -```py - -def fix_at_next_loadable_address(self, address) - -``` - - - -Calculate the next reasonable address where we can put this app where -the address is greater than or equal to `address`. The `address` -argument is the earliest address the app can be at, either the start of -apps or immediately after a previous app. Then return that address. -If we can't satisfy the request, return None. - -The "fix" part means remove all TBFs except for the one that we used -to meet the address requirements. - -If the app doesn't have a fixed address, then we can put it anywhere, -and we just return the address. If the app is compiled with fixed -addresses, then we need to calculate an address. We do a little bit of -"reasonable assuming" here. Fixed addresses are based on where the _app -binary_ must be located. Therefore, the start of the app where the TBF -header goes must be before that. This can be at any address (as long as -the header will fit), but we want to make this simpler, so we just -assume the TBF header should start on a 1024 byte alignment. - - -### get\_app\_version -```py - -def get_app_version(self) - -``` - - - -Return the version number stored in a program header. - -This is only valid if there is only one TBF. - - -### get\_binary -```py - -def get_binary(self, address) - -``` - - - -Return the binary array comprising the entire application. - -This is only valid if there is one TBF file. - -`address` is the address of flash the _start_ of the app will be placed -at. This means where the TBF header will go. - - -### get\_crt0\_header\_str -```py - -def get_crt0_header_str(self) - -``` - - - -Return a string representation of the crt0 header some apps use for -doing PIC fixups. We assume this header is positioned immediately -after the TBF header (AKA at the beginning of the application binary). - - -### get\_fixed\_addresses\_flash\_and\_sizes -```py - -def get_fixed_addresses_flash_and_sizes(self) - -``` - - - -Return a list of tuples of all addresses in flash this app is compiled -for and the size of the app at that address. - -[(address, size), (address, size), ...] - - -### get\_footers -```py - -def get_footers(self) - -``` - - - -Return the footers if there are any. - - -### get\_header -```py - -def get_header(self) - -``` - - - -Return a header if there is only one. - - -### get\_name -```py - -def get_name(self) - -``` - - - -Return the app name. - - -### get\_names\_and\_binaries -```py - -def get_names_and_binaries(self) - -``` - - - -Return (filename, binary) tuples for each contained TBF. This is for -updating a .tab file. - - -### get\_size -```py - -def get_size(self) - -``` - - - -Return the total size (including TBF header) of this app in bytes. - -This is only valid if there is only one TBF. - - -### has\_app\_binary -```py - -def has_app_binary(self) - -``` - - - -Return true if we have an application binary with this app. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -Return true if any TBF binary in this app is compiled for a fixed -address. That likely implies _all_ binaries are compiled for a fixed -address. - - -### info -```py - -def info(self, verbose=False) - -``` - - - -Get a string describing various properties of the app. - - -### is\_loadable\_at\_address -```py - -def is_loadable_at_address(self, address) - -``` - - - -Check if it is possible to load this app at the given address. Returns -True if it is possible, False otherwise. - - -### is\_modified -```py - -def is_modified(self) - -``` - - - -Returns whether this app needs to be flashed on to the board. Since this -is a TabApp, we did not get this app from the board and therefore we -have to flash this to the board. - - -### modify\_tbfh\_tlv -```py - -def modify_tbfh_tlv(self, tlvid, field, value) - -``` - - - -Modify a particular TLV from each TBF header to set field=value. - - -### set\_minimum\_size -```py - -def set_minimum_size(self, size) - -``` - - - -Force each version of the entire app to be a certain size. If `size` is -smaller than the actual app nothing happens. - - -### set\_size -```py - -def set_size(self, size) - -``` - - - -Force the entire app to be a certain size. If `size` is smaller than the -actual app an error will be thrown. - - -### set\_size\_constraint -```py - -def set_size_constraint(self, constraint) - -``` - - - -Change the entire app size for each compilation and architecture based -on certain rules. - -Valid rules: -- None: do nothing -- 'powers_of_two': make sure the entire size is a power of two. -- ('multiple', value): make sure the entire size is a multiple of value. - - -### set\_sticky -```py - -def set_sticky(self) - -``` - - - -Mark this app as "sticky" in the app's header. This makes it harder to -accidentally remove this app if it is a core service or debug app. - - -### verify\_credentials -```py - -def verify_credentials(self, public_keys) - -``` - - - -Using an optional array of public_key binaries, try to check any -contained credentials to verify they are valid. - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_concatenate\_and\_truncate\_binary -```py - -def _concatenate_and_truncate_binary(self, header, program_binary, footer) - -``` - - - -### \_get\_tbfs -```py - -def _get_tbfs(self) - -``` - - - -Helper function so we can implement TBF filtering. - -For normal TBFs (aka PIC TBFs), this doesn't do anything. For fixed -address TBFs, this filters the list of TBFs within the TAB to only those -that are plausibly within the app memory region for the board. - - - - -## Class TabTbf -Representation of a compiled app in the Tock Binary Format for use in -Tockloader. - -This correlates to a specific .tbf file storing a .tab file. -### \_\_init\_\_ -```py - -def __init__(self, filename, tbfh, binary, tbff) - -``` - - - -- `filename` is the identifier used in the .tab. -- `tbfh` is the header object -- `binary` is the actual compiled binary code - - - diff --git a/docs/board_interface.md b/docs/board_interface.md deleted file mode 100644 index 29f941d..0000000 --- a/docs/board_interface.md +++ /dev/null @@ -1,386 +0,0 @@ -# Package tockloader.board_interface Documentation - - -Generic interface for communicating with boards. - -While it would be nice if there was only a single method to communicate with -boards, in practice that is not feasible. So, this file includes the interface -that different communication methods must implement to effectively support -tockloader. - -## Class BoardInterface -Base class for interacting with hardware boards. All of the class functions -should be overridden to support a new method of interacting with a board. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -Check for the Tock bootloader. Returns `True` if it is present, `False` -if not, and `None` if unsure. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear at least one byte starting at `address`. - -This API is designed to support "ending the linked list of apps", or -clearing flash enough so that the flash after the last valid app will -not parse as a valid TBF header. - -Different chips with different mechanisms for writing/erasing flash make -implementing specific erase behavior difficult. Instead, we provide this -rough API, which is sufficient for the task of ending the linked list, -but doesn't guarantee exactly how many bytes after address will be -cleared, or how they will be cleared. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Get to a mode where we can read & write flash. - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Get out of bootloader mode and go back to running main code. - - -### flash\_binary -```py - -def flash_binary(self, address, binary, pad=True) - -``` - - - -Write a binary to the address given. - -`pad` is a bool indicating whether it is ok for the writing interface to -pad the binary to be written to meet any size requirements. If `True`, -the writing interface can add values (e.g., `0xFF`s) to the binary to -meet writing size constraints. If `False`, the writing interface must -not simply add values like 0xFFs, and instead must read what is already -written to do any needed padding when needing to meet size -requirements. - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### open\_link\_to\_board -```py - -def open_link_to_board(self) - -``` - - - -Open a connection to the board. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read a specific range of flash. - -If this fails for some reason this should return an empty binary array. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - - diff --git a/docs/bootloader_serial.md b/docs/bootloader_serial.md deleted file mode 100644 index 6663314..0000000 --- a/docs/bootloader_serial.md +++ /dev/null @@ -1,592 +0,0 @@ -# Package tockloader.bootloader_serial Documentation - - -Interface with a board over serial that is using the -[Tock Bootloader](https://github.com/tock/tock-bootloader). - -## Class BootloaderSerial -Implementation of `BoardInterface` for the Tock Bootloader over serial. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -For this communication protocol we can safely say the bootloader is -present. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear at least one byte starting at `address`. - -This API is designed to support "ending the linked list of apps", or -clearing flash enough so that the flash after the last valid app will -not parse as a valid TBF header. - -Different chips with different mechanisms for writing/erasing flash make -implementing specific erase behavior difficult. Instead, we provide this -rough API, which is sufficient for the task of ending the linked list, -but doesn't guarantee exactly how many bytes after address will be -cleared, or how they will be cleared. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Reset the chip and assert the bootloader select pin to enter bootloader -mode. Handle retries if necessary. - - -### erase\_page -```py - -def erase_page(self, address) - -``` - - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Reset the chip to exit bootloader mode. - - -### flash\_binary -```py - -def flash_binary(self, address, binary, pad=True) - -``` - - - -Write pages until a binary has been flashed. binary must have a length -that is a multiple of page size. - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### open\_link\_to\_board -```py - -def open_link_to_board(self, listen=False) - -``` - - - -Open the serial port to the chip/bootloader. - -Also sets up a local port for determining when two Tockloader instances -are running simultaneously. - -Set the argument `listen` to true if the serial port is being setup -because we are planning to run `run_terminal`. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read a specific range of flash. - -If this fails for some reason this should return an empty binary array. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -Run miniterm for receiving data from the board. - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_change\_baud\_rate -```py - -def _change_baud_rate(self, baud_rate) - -``` - - - -If the bootloader on the board supports it and if it succeeds, try to -increase the baud rate to make everything faster. - - -### \_check\_crc -```py - -def _check_crc(self, address, binary, valid_pages) - -``` - - - -Compares the CRC of the local binary to the one calculated by the -bootloader. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_configure\_serial\_port -```py - -def _configure_serial_port(self, port) - -``` - - - -Helper function to configure the serial port so we can read/write with -it. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - -### \_determine\_port -```py - -def _determine_port(self, any=False) - -``` - - - -Helper function to determine which serial port on the host to use to -connect to the board. - -Set `any` to true to return a device without prompting the user (i.e. -just return any port if there are multiple). - - -### \_exit\_bootloader -```py - -def _exit_bootloader(self) - -``` - - - -Tell the bootloader on the board to exit so the main software can run. - -This uses a command sent over the serial port to the bootloader. - - -### \_get\_crc\_internal\_flash -```py - -def _get_crc_internal_flash(self, address, length) - -``` - - - -Get the bootloader to compute a CRC. - - -### \_get\_serial\_port\_hash -```py - -def _get_serial_port_hash(self) - -``` - - - -Get an identifier that will be consistent for this serial port on this -machine that is also guaranteed to not have any special characters (like -slashes) that would interfere with using as a file name. - - -### \_get\_serial\_port\_hashed\_to\_ip\_port -```py - -def _get_serial_port_hashed_to_ip_port(self) - -``` - - - -This is a bit of a hack, but it's means to find a reasonably unlikely -to collide port number based on the serial port used to talk to the -board. - - -### \_issue\_command -```py - -def _issue_command(self, command, message, sync, response_len, response_code, show_errors=True) - -``` - - - -Setup a command to send to the bootloader and handle the response. - - -### \_open\_serial\_port -```py - -def _open_serial_port(self) - -``` - - - -Helper function for calling `self.sp.open()`. - -Serial ports on different OSes and systems can be finicky, and this -enables retries to try to hide failures. - - -### \_ping\_bootloader\_and\_wait\_for\_response -```py - -def _ping_bootloader_and_wait_for_response(self) - -``` - - - -Throws an exception if the device does not respond with a PONG. - - -### \_server\_thread -```py - -def _server_thread(self) - -``` - - - -### \_toggle\_bootloader\_entry\_DTR\_RTS -```py - -def _toggle_bootloader_entry_DTR_RTS(self) - -``` - - - -Use the DTR and RTS lines on UART to reset the chip and assert the -bootloader select pin to enter bootloader mode so that the chip will -start in bootloader mode. - - -### \_toggle\_bootloader\_entry\_baud\_rate -```py - -def _toggle_bootloader_entry_baud_rate(self) - -``` - - - -Set the baud rate to 1200 so that the chip will restart into the -bootloader (if that feature exists). - -Returns `True` if it successfully started the bootloader, `False` -otherwise. - - -### \_wait\_for\_serial\_port -```py - -def _wait_for_serial_port(self) - -``` - - - -Wait for the serial port to re-appear, aka the bootloader has started. - - - diff --git a/docs/display.md b/docs/display.md deleted file mode 100644 index 7155a94..0000000 --- a/docs/display.md +++ /dev/null @@ -1,414 +0,0 @@ -# Package tockloader.display Documentation - - -Utilities for creating output in various formats. - -## Class Display -None -### \_\_init\_\_ -```py - -def __init__(self, show_headers) - -``` - - - -Arguments: -- show_headers: bool, if True, label each section in the display output. - - -### bootloader\_version -```py - -def bootloader_version(self, version) - -``` - - - -Show the bootloader version stored in the bootloader itself. - - -### get -```py - -def get(self) - -``` - - - -### kernel\_attributes -```py - -def kernel_attributes(self, kern_attrs) - -``` - - - -Show the kernel attributes stored in the kernel binary. - - -### list\_apps -```py - -def list_apps(self, apps, verbose, quiet) - -``` - - - -Show information about a list of apps. - - -### list\_attributes -```py - -def list_attributes(self, attributes) - -``` - - - -Show the key value pairs for a list of attributes. - - - - -## Class HumanReadableDisplay -Format output as a string meant to be human readable. -### \_\_init\_\_ -```py - -def __init__(self, show_headers=False) - -``` - - - -Arguments: -- show_headers: bool, if True, label each section in the display output. - - -### bootloader\_version -```py - -def bootloader_version(self, version) - -``` - - - -Show the bootloader version stored in the bootloader itself. - - -### get -```py - -def get(self) - -``` - - - -### kernel\_attributes -```py - -def kernel_attributes(self, kern_attrs) - -``` - - - -Show the kernel attributes stored in the kernel binary. - - -### list\_apps -```py - -def list_apps(self, apps, verbose, quiet) - -``` - - - -Show information about a list of apps. - - -### list\_attributes -```py - -def list_attributes(self, attributes) - -``` - - - -Show the key value pairs for a list of attributes. - - -### show\_app\_map\_actual\_address -```py - -def show_app_map_actual_address(self, apps) - -``` - - - -Show a map of installed applications with known addresses. Example: - -``` -0x30000┬──────────────────────────────────────────────────┐ - │App: blink [Installed]│ - │ Length: 16384 (0x4000) │ -0x34000┴──────────────────────────────────────────────────┘ -0x38000┬──────────────────────────────────────────────────┐ - │App: blink [Installed]│ - │ Length: 16384 (0x4000) │ -0x3c000┴──────────────────────────────────────────────────┘ -``` - - -### show\_app\_map\_from\_address -```py - -def show_app_map_from_address(self, apps, start_address) - -``` - - - -Print a layout map of apps assuming they are located back-to-back -starting from `start_address`. Example: - -``` -0x30000┬──────────────────────────────────────────────────┐ - │App: blink [Installed]│ - │ Length: 16384 (0x4000) │ -0x34000┼──────────────────────────────────────────────────┤ - │App: blink [Installed]│ - │ Length: 16384 (0x4000) │ -0x3c000┴──────────────────────────────────────────────────┘ -``` - - -### show\_board\_visual -```py - -def show_board_visual(self, apps) - -``` - - - - - -## Class JSONDisplay -Format output as JSON. -### \_\_init\_\_ -```py - -def __init__(self) - -``` - - - -Arguments: -- show_headers: bool, if True, label each section in the display output. - - -### bootloader\_version -```py - -def bootloader_version(self, version) - -``` - - - -Show the bootloader version stored in the bootloader itself. - - -### get -```py - -def get(self) - -``` - - - -### kernel\_attributes -```py - -def kernel_attributes(self, kern_attrs) - -``` - - - -Show the kernel attributes stored in the kernel binary. - - -### list\_apps -```py - -def list_apps(self, apps, verbose, quiet) - -``` - - - -Show information about a list of apps. - - -### list\_attributes -```py - -def list_attributes(self, attributes) - -``` - - - -Show the key value pairs for a list of attributes. - - - - -## Class VisualDisplay -Format output as an ASCII art string. - -┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┐ -│ | │ | │ | │ | -│ | │ | │ | │ | -│ | │ | │ | │ | -│ version | │ version | │ version | │ blink | -│ | │ | │ | │ | -│ | │ | │ | │ | -│ | │ | │ | │ | -│ | │ | │ | │ | -└─────────┘ └─────────┘ └─────────┘ └───────┘ -┌───────────────────────────────────────────┐ -│ Kernel | -└───────────────────────────────────────────┘ -### \_\_init\_\_ -```py - -def __init__(self) - -``` - - - -Arguments: -- show_headers: bool, if True, label each section in the display output. - - -### bootloader\_version -```py - -def bootloader_version(self, version) - -``` - - - -Show the bootloader version stored in the bootloader itself. - - -### get -```py - -def get(self) - -``` - - - -### kernel\_attributes -```py - -def kernel_attributes(self, kern_attrs) - -``` - - - -Show the kernel attributes stored in the kernel binary. - - -### list\_apps -```py - -def list_apps(self, apps, verbose, quiet) - -``` - - - -Show information about a list of apps. - - -### list\_attributes -```py - -def list_attributes(self, attributes) - -``` - - - -Show the key value pairs for a list of attributes. - - -### \_width -```py - -def _width(self) - -``` - - - - - -### app\_bracket -```py - -def app_bracket(width, left, right) - -``` - - - -### choose -```py - -def choose(b, t, f) - -``` - - - -### end\_of\_app -```py - -def end_of_app(width, address, continuing) - -``` - - - -### start\_of\_app -```py - -def start_of_app(width, address) - -``` - - diff --git a/docs/exceptions.md b/docs/exceptions.md deleted file mode 100644 index 8e2cdcf..0000000 --- a/docs/exceptions.md +++ /dev/null @@ -1,5 +0,0 @@ -# Package tockloader.exceptions Documentation - -## Class TockLoaderException -Raised when Tockloader detects an issue. - diff --git a/docs/flash_file.md b/docs/flash_file.md deleted file mode 100644 index 0e66a02..0000000 --- a/docs/flash_file.md +++ /dev/null @@ -1,427 +0,0 @@ -# Package tockloader.flash_file Documentation - - -Interface to a board's flash file. This module does not directly interface to a -proper board, but can be used to manipulate a board's flash dump. - -## Class FlashFile -Implementation of `BoardInterface` for flash files. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -Check for the Tock bootloader. Returns `True` if it is present, `False` -if not, and `None` if unsure. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear at least one byte starting at `address`. - -This API is designed to support "ending the linked list of apps", or -clearing flash enough so that the flash after the last valid app will -not parse as a valid TBF header. - -Different chips with different mechanisms for writing/erasing flash make -implementing specific erase behavior difficult. Instead, we provide this -rough API, which is sufficient for the task of ending the linked list, -but doesn't guarantee exactly how many bytes after address will be -cleared, or how they will be cleared. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Get to a mode where we can read & write flash. - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Get out of bootloader mode and go back to running main code. - - -### flash\_binary -```py - -def flash_binary(self, address, binary) - -``` - - - -Write a binary to the address given. - -`pad` is a bool indicating whether it is ok for the writing interface to -pad the binary to be written to meet any size requirements. If `True`, -the writing interface can add values (e.g., `0xFF`s) to the binary to -meet writing size constraints. If `False`, the writing interface must -not simply add values like 0xFFs, and instead must read what is already -written to do any needed padding when needing to meet size -requirements. - - -### flush -```py - -def flush(self) - -``` - - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_local\_board\_path -```py - -def get_local_board_path(self) - -``` - - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### open\_link\_to\_board -```py - -def open_link_to_board(self) - -``` - - - -Open a link to the board by opening the flash file for reading and -writing. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read a specific range of flash. - -If this fails for some reason this should return an empty binary array. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - -### \_run\_flush\_command -```py - -def _run_flush_command(self, command) - -``` - - - - - -### set\_local\_board -```py - -def set_local_board(board, arch=None, app_address=None, flash_address=None, flush_command=None, binary_path=None) - -``` - - - -### unset\_local\_board -```py - -def unset_local_board() - -``` - - diff --git a/docs/helpers.md b/docs/helpers.md deleted file mode 100644 index 8b6dc33..0000000 --- a/docs/helpers.md +++ /dev/null @@ -1,245 +0,0 @@ -# Package tockloader.helpers Documentation - - -Various helper functions that tockloader uses. Mostly for interacting with -users in a nice way. - -## Class ListToDictAction -`argparse` action to convert `[['key', 'val'], ['key2', 'val2']]` to -`{'key': 'val', 'key2': 'val2'}`. - -This will also do the following conversions: -- `[[]]` -> `{}` -- `[['k': 'v'], []]` -> `{'k': 'v'}` -- `[['k': 'v'], ['']]` -> `{'k': 'v'}` -- `[['k': 'v'], ['a']]` -> `{'k': 'v', 'a': ''}` -### \_\_init\_\_ -```py - -def __init__(self, option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None, deprecated=False) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### format\_usage -```py - -def format_usage(self) - -``` - - - -### \_\_call\_\_ -```py - -def __call__(self, parser, namespace, values, option_string=None) - -``` - - - -Call self as a function. - - -### \_\_repr\_\_ -```py - -def __repr__(self) - -``` - - - -Return repr(self). - - -### \_get\_args -```py - -def _get_args(self) - -``` - - - -### \_get\_kwargs -```py - -def _get_kwargs(self) - -``` - - - - - -### menu -```py - -def menu(options, *, return_type, default_index=0, prompt='Which option? ', title='') - -``` - - - -Present a menu of choices to a user - -`options` should be a like-list object whose iterated objects can be coerced -into strings. - -`return_type` must be set to one of - - "index" - for the index into the options array - - "value" - for the option value chosen - -`default_index` is the index to present as the default value (what happens -if the user simply presses enter). Passing `None` disables default -selection. - - -### menu\_multiple -```py - -def menu_multiple(options, prompt='Make your selections:') - -``` - - - -### menu\_multiple\_indices -```py - -def menu_multiple_indices(options, prompt='Make your selections:') - -``` - - - -### menu\_new -```py - -def menu_new(options, *, return_type, default_index=None, prompt='', title='') - -``` - - - -Present an interactive menu of choices to a user. - -`options` should be a like-list object whose iterated objects can be coerced -into strings. - -`return_type` must be set to one of: - - "index" - for the index into the options array - - "value" - for the option value chosen - -`default_index` is the index to present as the default value (what happens -if the user simply presses enter). Passing `None` disables default -selection. - - -### menu\_new\_yes\_no -```py - -def menu_new_yes_no(prompt='') - -``` - - - -Present an interactive yes/no prompt to the user. - - -### number\_or -```py - -def number_or(value) - -``` - - - -Try to format value as a number. If that fails, just leave it alone. - - -### plural -```py - -def plural(value) - -``` - - - -Return '' or 's' based on whether the `value` means a string should have -a plural word. - -`value` can be a list or a number. If the number or the length of the list -is 1, then '' will be returned. Otherwise 's'. - - -### print\_flash -```py - -def print_flash(address, flash) - -``` - - - -Return binary data in a nice hexdump format. - - -### set\_terminal\_title -```py - -def set_terminal_title(title) - -``` - - - -### set\_terminal\_title\_from\_port -```py - -def set_terminal_title_from_port(port) - -``` - - - -Set the title of the user's terminal for Tockloader. - - -### set\_terminal\_title\_from\_port\_info -```py - -def set_terminal_title_from_port_info(info) - -``` - - - -Set a terminal title from a `pyserial` object. - - -### text\_in\_box -```py - -def text_in_box(string, box_width, box_height=3) - -``` - - - -Return a string like: -``` -┌───────────────┐ -│ str │ -└───────────────┘ -``` - diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index b248334..0000000 --- a/docs/index.md +++ /dev/null @@ -1,465 +0,0 @@ -# ![TockLoader](http://www.tockos.org/assets/img/tockloader.svg#a "Tockloader Logo") - -Tool for programming Tock onto hardware boards. - -Install -------- - -``` -pip3 install pipx -pipx install tockloader -``` - -If you want tab completions: - -``` -register-python-argcomplete tockloader >> ~/.bashrc -``` - -Usage ------ - -This tool installs a binary called `tockloader`, which supports several commands. - -### Primary Commands - -These are the main commands for managing apps on a board. - -#### `tockloader install` - -Load Tock applications on to the board. Use `--no-replace` to install -multiple copies of the same app. - -#### `tockloader update` - -Update an application that is already flashed to the board with a new -binary. - -#### `tockloader uninstall [application name(s)]` - -Remove an application from flash by its name. - - -### Board Inspection Commands - -These query the board for its current state. - -#### `tockloader list` - -Print information about the apps currently loaded onto the board. - -#### `tockloader info` - -Show all properties of the board. - - -### Utility Commands - -These provide other helpful features. - -#### `tockloader listen` - -Listen to UART `printf()` data from a board. Use the option `--rtt` to use -Segger's RTT listener instead of using a serial port. - - -### Other Commands - -These provide more internal functionality. - -#### `tockloader flash` - -Load binaries onto hardware platforms that are running a compatible bootloader. -This is used by the [TockOS](https://github.com/helena-project/tock) Make system -when kernel binaries are programmed to the board with `make program`. - -#### `tockloader inspect-tab` - -Show details about a compiled TAB file. - -#### `tockloader enable-app [application name(s)]` - -Enable an app so that the kernel will run it at boot. - -#### `tockloader disable-app [application name(s)]` - -Disable an app so that the kernel will not start it at boot. - -#### `tockloader sticky-app [application name(s)]` - -Mark an app as sticky so that the `--force` flag is required to uninstall it. - -#### `tockloader unsticky-app [application name(s)]` - -Remove the sticky flag from an app. - -#### `tockloader list-attributes` - -Show all of the attributes that are stored on the board. - -#### `tockloader set-attribute [attribute key] [attribute value]` - -Set a particular attribute key to the specified value. This will overwrite -an existing attribute if the key matches. - -#### `tockloader remove-attribute [attribute key]` - -Remove a particular attribute from the board. - -#### `tockloader dump-flash-page [page number]` - -Show the contents of a page of flash. - -#### `tockloader read [address] [# bytes]` - -Read arbitrary flash memory from the board. - -#### `tockloader write [address] [# bytes] [value]` - -Write arbitrary flash memory on the board with a specific value. - -#### `tockloader list-known-boards` - -Print which boards tockloader has default settings for built-in. - -#### `tockloader set-start-address [address]` - -Set the jump address the bootloader uses for the location of the kernel. - -#### `tockloader local-board set [board]` - -Set the name of the board to use with a local binary file instead of hardware. - -#### `tockloader local-board unset` - -Remove the board to use with a local binary file instead of hardware. - -#### `tockloader local-board flush` - -Write the local binary file to the hardware board. - -#### `tockloader tbf tlv add|modify|delete [TLVNAME]` - -Interact with TLV structures within a TBF. - -#### `tockloader tbf credential add|delete [credential type]` - -Add and remove credentials in the TBF footer. - -#### `tockloader tbf convert [output format]` - -Convert a TBF to a different format. - -#### `tockloader tickv get|append|invalidate|dump|cleanup|reset [key] [value]` - -Interact with a TicKV key-value database. - - -Specifying the Board --------------------- - -For tockloader to know how to interface with a particular hardware board, -it tries several options: - -1. Read the parameters from the bootloader. Tockloader assumes it can open a - serial connection to a - [tock-bootloader](https://github.com/tock/tock-bootloader/) on the board. - -2. Use `JLinkExe`, `OpenOCD`, `STLink`, or the default virtual board to discover - known boards. - -3. Use the `--board` command line flag and a list of known boards. - -4. Use individual command line flags that specify how to interact with the - board. - -If command line flags are passed they take priority over any automatically -discovered options. - -Tockloader has hardcoded parameters for a variety of boards. You can list these -with: - - tockloader list-known-boards - -To use a known board, if it is not automatically discovered, you can: - - tockloader [command] --board [board] - -If your board is not a known board, you can specify the required parameters -via command line options. Note, you also need to provide a name for the board. - - tockloader [command] --board [board] --arch [arch] --page-size [page_size] - -- `board`: The name of the board. This helps prevent incompatible applications - from being flashed on the wrong board. -- `arch`: The architecture of the board. Likely `cortex-m0` or `cortex-m4`. -- `page_size`: The size in bytes of the smallest erasable unit in flash. - -Specifying the Communication Channel ------------------------------------- - -Tockloader defaults to using a serial connection to an on-chip bootloader to -program and interact with a board. If you need to use a different communication -mechanism, you can specify what Tockloader should use with command line -arguments. Note, Tockloader's board autodiscovery process also selects different -communication channels based on which board it finds. - -To use a JTAG interface using JLinkExe, specify `--jlink`. JLinkExe requires -knowing the device type of the MCU on the board. - - tockloader [command] --board [board] --arch [arch] --page-size [page_size] \ - --jlink --jlink-cmd [jlink_cmd] --jlink-device [device] \ - --jlink-speed [speed] --jlink-if [if] \ - --jlink-serial-number [serial_number] - -- `jlink_cmd`: The JLink executable to invoke. Defaults to `JLinkExe` on - Mac/Linux, and `JLink` on Windows. -- `device`: The JLinkExe device identifier. -- `speed`: The speed value to pass to JLink. Defaults to 1200. -- `if`: The interface to pass to JLink. -- `serial-number`: The serial number of the target board to use with JLink. - -Tockloader can also do JTAG using OpenOCD. OpenOCD needs to know which config -file to use. - - tockloader [command] --board [board] --arch [arch] --page-size [page_size] \ - --openocd --openocd-board [openocd_board] \ - --openocd-cmd [openocd_cmd] \ - --openocd-options [openocd_options] \ - --openocd-commands [openocd_commands] - -- `openocd_board`: The `.cfg` file in the board folder in OpenOCD to use. -- `openocd_cmd`: The OpenOCD executable to invoke. Defaults to `openocd`. -- `openocd_options`: A list of Tock-specific flags used to customize how - Tockloader calls OpenOCD based on experience with various boards and their - quirks. Options include: - - `noreset`: Removes the command `reset init;` from OpenOCD commands. - - `nocmdprefix`: Removes the commands `init; reset init; halt;` from OpenOCD - commands. - - `workareazero`: Adds the command `set WORKAREASIZE 0;` to OpenOCD commands. - - `resume`: Adds the commands `soft_reset_halt; resume;` to OpenOCD commands. -- `openocd_commands`: This sets a custom OpenOCD command string to allow - Tockloader to program arbitrary chips with OpenOCD before support for the - board is officially include in Tockloader. The following main operations can - be customized: - - `program`: Operation used to write a binary to the chip. - - `read`: Operation used to read arbitrary flash memory on the chip. - - `erase`: Operation that erases arbitrary ranges of flash memory on the chip. - - The custom values are specified as key=value pairs, for example, - `--openocd_commands 'program=write_image; halt;' 'erase=flash fillb - {address:#x} 0xff 512;'`. Operation strings can include wildcards which will - get set with the correct value by Tockloader: - - `{{binary}}`: The binary file path. - - `{address:#x}`: The specified address for the binary to be programmed at. - - `{length}`: The number of bytes. Only valid for the `read` operation. - -For STM32 boards, Tockloader supports -[STLINK](https://github.com/stlink-org/stlink). The stlink tool knows how to -interface with the boards, so there are not many flags. - - tockloader [command] --board [board] --arch [arch] --page-size [page_size] \ - --stlink \ - --stinfo-cmd [stinfo_cmd] --stflash-cmd [stflash_cmd] - -- `stinfo_cmd`: The st-info executable to invoke. Defaults to `st-info`. -- `stflash_cmd`: The st-flash executable to invoke. Defaults to `st-flash`. - -For nRF5x boards, Tockloader supports -[nrfutil](https://www.nordicsemi.com/Products/Development-tools/nRF-Util). This -tool uses JLink to program Nordic's nRF5x development boards. - - tockloader [command] --board [board] --arch [arch] --page-size [page_size] \ - --nrfutil \ - --nrfutil-cmd [nrfutil_cmd] - --nrfutil-serial-number [serial_number] - -- `nrfutil_cmd`: The nrfutil executable to invoke. Defaults to `nrfutil`. -- `serial_number`: The serial number of a particular board to flash. Defaults to - the first board discovered. - -Finally, Tockloader can treat a local file as though it were the flash contents -of a board. The file can then be loaded separately onto a board. - - tockloader [command] --flash-file [filepath] - -- `filepath`: The file to use as the flash contents. Will be created if it - doesn't exist. - -Tockloader can use a flash file by default. This is particularly helpful for -virtual, QEMU-based boards, or other boards that do not support fine-grained -reading and writing. You can set the default local board to use: - - tockloader local-board set [board] - -If the board you are using is new or not a known board in tockloader, you can -manually specifying the necessary parameters: - - tockloader local-board set [board] --arch [arch] --app-address [address] --flash-address [address] --flush-command [command] --binary-path [path] - -- `board`: Name of the board you want to use. -- `arch`: Name of the architecture the board uses. -- `app-address`: The flash address where apps start. -- `flash-address`: The address where flash starts. -- `flush-command`: The command to write the file to the board. Use `{binary}` to - specify where the file path should go in the command. -- `binary-path`: Where the actual flash-file binary should be located. Optional. - If not provided defaults to a suitable tockloader application data - directory. - -Then, tockloader commands will use a virtual image file for all operations that -interact with a board. - -You can reverse this with: - - tockloader local-board unset - -Example Usage -------------- - -Install an app, make sure it's up to date, and make sure it's the only app on -the board: - - tockloader install --make --erase - -Get all info from the board that can be used to help debugging: - - tockloader info - -Print additionally debugging information. This can be helpful when using JTAG. - - tockloader install --debug - -Get `printf()` data from a board: - - tockloader listen - -Additional Flags ----------------- - -There are additional flags that might be useful for customizing tockloader's -operation based on the requirements of a particular hardware platform. - -- `--app-address`: Manually specify the address at the beginning of where apps - are stored. This can be in hex or decimal. -- `--bundle-apps`: This forces tockloader to write all apps as a concatenated - bundle using only a single flash command. This will require that anytime any - app changes in any way (e.g. its header changes or the app is updated or a new - app is installed) all apps are re-written. -- `--layout`: Specify exactly how apps and padding apps should be written to the - board. This implies `--erase` and `--force` as all existing (even sticky) apps - will be removed. - - The layout is specified as a string of how apps from TBFs and padding apps - should be written to the board. The syntax for the layout uses the following - identifiers: - - - `T`: indicates to install a TBF app. - - `p`: indicates to install a padding app of `` bytes. - - For example `--layout Tp1024TT` specifies to install the first app at the - `app-address`, then install a 1024 byte padding app, then install the second - app, then install the third app. No board-specific alignment or sizing will - be used; the apps will be installed exactly as described. It can be helpful - to use `tockloader list --map` to view how the apps were actually installed. - -Credentials and Integrity Support ---------------------------------- - -Tockloader supports working with credentials stored in the TBF footer. -Tockloader will attempt to verify that stored credentials are valid for the -given TBF. For credentials that require keys to verify, Tockloader can check the -credential using: - - $ tockloader inspect-tab --verify-credentials [list of key files] - example: - $ tockloader inspect-tab --verify-credentials tockkey.public.der - -Tockloader can also add credentials. To add a hash: - - $ tockloader tbf credential add sha256 - -To add an RSA signature: - - $ tockloader tbf credential add rsa2048 --private-key tockkey2048.private.der --public-key tockkey2048.public.der - -To remove credentials: - - $ tockloader tbf credential delete sha256 - - -Features --------- - -- Supported communication protocols - - Serial over USB - - Segger JLinkExe JTAG support - - OpenOCD JTAG support -- JLink RTT listener -- JSON output using `--output-format json` for certain commands. - - -Complete Install Instructions ------------------------------ - -Tockloader is a Python script that is installed as an executable. -To use Tockloader, you need python3, a couple dependencies, and -the Tockloader package. - -- Ubuntu - ``` - sudo apt install python3-pip - pip3 install -U pip --user # update pip - pip3 install tockloader --user - ``` - -- MacOS - ``` - brew install python3 - pip3 install tockloader - ``` - -- Windows - - [Download and Install Python 3](https://www.python.org/downloads/windows/) - - Execute within CMD/PowerShell/...: - ``` - pip3 install tockloader - ``` - -Internal Notes --------------- - -### Test Locally - -To test the code locally without installing as a package, from the top-level -directory: - - python3 -m tockloader.main - - -### Build and Install Locally - - pipx install build - pyproject-build - pipx install . - -### Upload to PyPI - - pipx install build - pipx install flit - pyproject-build - flit publish - - -### Build Docs - - pip3 install mkdocs - cd docs - ./generate_docs.py - cd .. - mkdocs serve --dev-addr=0.0.0.0:8001 - -### Create requirements.txt - - pip3 install pipreqs - pipreqs . --force diff --git a/docs/jlinkexe.md b/docs/jlinkexe.md deleted file mode 100644 index 7e03d50..0000000 --- a/docs/jlinkexe.md +++ /dev/null @@ -1,433 +0,0 @@ -# Package tockloader.jlinkexe Documentation - - -Interface for boards using Segger's JLinkExe program. - -All communication with the board is done using JLinkExe commands and scripts. - -Different MCUs require different command line arguments so that the JLinkExe -tool knows which JTAG interface it is talking to. Since we don't want to burden -the user with specifying the board each time, we default to using a generic -cortex-m0 target, and use that to read the bootloader attributes to get the -correct version. Once we know more about the board we are talking to we use the -correct command line argument for future communication. - -## Class JLinkExe -Base class for interacting with hardware boards. All of the class functions -should be overridden to support a new method of interacting with a board. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -Check for the Tock bootloader. Returns `True` if it is present, `False` -if not, and `None` if unsure. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear at least one byte starting at `address`. - -This API is designed to support "ending the linked list of apps", or -clearing flash enough so that the flash after the last valid app will -not parse as a valid TBF header. - -Different chips with different mechanisms for writing/erasing flash make -implementing specific erase behavior difficult. Instead, we provide this -rough API, which is sufficient for the task of ending the linked list, -but doesn't guarantee exactly how many bytes after address will be -cleared, or how they will be cleared. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Get to a mode where we can read & write flash. - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Get out of bootloader mode and go back to running main code. - - -### flash\_binary -```py - -def flash_binary(self, address, binary, pad=False) - -``` - - - -Write using JTAG - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### open\_link\_to\_board -```py - -def open_link_to_board(self) - -``` - - - -Open a connection to the board. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read a specific range of flash. - -If this fails for some reason this should return an empty binary array. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -Use JLinkRTTClient to listen for RTT messages. - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - -### \_get\_tockloader\_board\_from\_emulators -```py - -def _get_tockloader_board_from_emulators(self, emulators) - -``` - - - -Returns None or a board name if we can parse the emulators list -and find a valid board. - -To add to this list, connect your board, then: - -$ JLinkExe -> ShowEmuList - -and hope there is something unique we can match on. - - -### \_list\_emulators -```py - -def _list_emulators(self) - -``` - - - -Retrieve a list of JLink compatible devices. - - -### \_run\_jtag\_commands -```py - -def _run_jtag_commands(self, commands, binary, write=True) - -``` - - - -- `commands`: List of JLinkExe commands. Use {binary} for where the name - of the binary file should be substituted. -- `binary`: A bytes() object that will be used to write to the board. -- `write`: Set to true if the command writes binaries to the board. Set - to false if the command will read bits from the board. - - - diff --git a/docs/main.md b/docs/main.md deleted file mode 100644 index 665700c..0000000 --- a/docs/main.md +++ /dev/null @@ -1,429 +0,0 @@ -# Package tockloader.main Documentation - - -### Main command line interface for Tockloader. - -Each `tockloader` command is mapped to a function which calls the correct -tockloader class function. This file also handles discovering and reading in TAB -files. - -### check\_and\_run\_make -```py - -def check_and_run_make(args) - -``` - - - -Checks for a Makefile, and it it exists runs `make`. - - -### collect\_tabs -```py - -def collect_tabs(args) - -``` - - - -Load in Tock Application Bundle (TAB) files. If none are specified, this -searches for them in subfolders. - -Also allow downloading apps by name from a server. - - -### command\_disable\_app -```py - -def command_disable_app(args) - -``` - - - -### command\_dump\_flash\_page -```py - -def command_dump_flash_page(args) - -``` - - - -### command\_enable\_app -```py - -def command_enable_app(args) - -``` - - - -### command\_erase\_apps -```py - -def command_erase_apps(args) - -``` - - - -### command\_flash -```py - -def command_flash(args) - -``` - - - -### command\_info -```py - -def command_info(args) - -``` - - - -### command\_inspect\_tab -```py - -def command_inspect_tab(args) - -``` - - - -### command\_install -```py - -def command_install(args) - -``` - - - -### command\_list -```py - -def command_list(args) - -``` - - - -### command\_list\_attributes -```py - -def command_list_attributes(args) - -``` - - - -### command\_list\_known\_boards -```py - -def command_list_known_boards(args) - -``` - - - -### command\_listen -```py - -def command_listen(args) - -``` - - - -### command\_local\_board\_flush -```py - -def command_local_board_flush(args) - -``` - - - -### command\_local\_board\_path -```py - -def command_local_board_path(args) - -``` - - - -### command\_local\_board\_set -```py - -def command_local_board_set(args) - -``` - - - -### command\_local\_board\_unset -```py - -def command_local_board_unset(args) - -``` - - - -### command\_read -```py - -def command_read(args) - -``` - - - -Read the correct flash range from the chip. - - -### command\_remove\_attribute -```py - -def command_remove_attribute(args) - -``` - - - -### command\_set\_attribute -```py - -def command_set_attribute(args) - -``` - - - -### command\_set\_start\_address -```py - -def command_set_start_address(args) - -``` - - - -### command\_sticky\_app -```py - -def command_sticky_app(args) - -``` - - - -### command\_tbf\_convert -```py - -def command_tbf_convert(args) - -``` - - - -### command\_tbf\_credential\_add -```py - -def command_tbf_credential_add(args) - -``` - - - -### command\_tbf\_credential\_delete -```py - -def command_tbf_credential_delete(args) - -``` - - - -### command\_tbf\_tlv\_add -```py - -def command_tbf_tlv_add(args) - -``` - - - -### command\_tbf\_tlv\_delete -```py - -def command_tbf_tlv_delete(args) - -``` - - - -### command\_tbf\_tlv\_modify -```py - -def command_tbf_tlv_modify(args) - -``` - - - -### command\_tickv\_append -```py - -def command_tickv_append(args) - -``` - - - -### command\_tickv\_append\_rsa\_key -```py - -def command_tickv_append_rsa_key(args) - -``` - - - -Helper operation to store an RSA public key in a TicKV database. This adds -two key-value pairs: - -1. `rsa-key-n` -2. `rsa-key-e` - -where `` is the size of the key. So, for 2048 bit RSA keys the two -TicKV keys will be `rsa2048-key-n` and `rsa2048-key-e`. - -The actual values for n and e are stored as byte arrays. - - -### command\_tickv\_cleanup -```py - -def command_tickv_cleanup(args) - -``` - - - -### command\_tickv\_dump -```py - -def command_tickv_dump(args) - -``` - - - -### command\_tickv\_get -```py - -def command_tickv_get(args) - -``` - - - -### command\_tickv\_hash -```py - -def command_tickv_hash(args) - -``` - - - -### command\_tickv\_invalidate -```py - -def command_tickv_invalidate(args) - -``` - - - -### command\_tickv\_reset -```py - -def command_tickv_reset(args) - -``` - - - -### command\_uninstall -```py - -def command_uninstall(args) - -``` - - - -### command\_unsticky\_app -```py - -def command_unsticky_app(args) - -``` - - - -### command\_update -```py - -def command_update(args) - -``` - - - -### command\_write -```py - -def command_write(args) - -``` - - - -Write flash range on the chip with a specific value. - - -### get\_addable\_tlvs -```py - -def get_addable_tlvs() - -``` - - - -Return a list of (tlv_name, #parameters) tuples for all TLV types that -tockloader can add. - - -### main -```py - -def main() - -``` - - - -Read in command line arguments and call the correct command function. - diff --git a/docs/nrfutil.md b/docs/nrfutil.md deleted file mode 100644 index d459414..0000000 --- a/docs/nrfutil.md +++ /dev/null @@ -1,427 +0,0 @@ -# Package tockloader.nrfutil Documentation - - -Interface for boards using nrfutil. - -## Class NrfUtil -Base class for interacting with hardware boards. All of the class functions -should be overridden to support a new method of interacting with a board. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -Check for the Tock bootloader. Returns `True` if it is present, `False` -if not, and `None` if unsure. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear bytes by writing 0xFFs. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Get to a mode where we can read & write flash. - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Get out of bootloader mode and go back to running main code. - - -### flash\_binary -```py - -def flash_binary(self, address, binary, pad=False) - -``` - - - -Write using nrfutil. - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### nrfutil\_installed -```py - -def nrfutil_installed(self) - -``` - - - -### open\_link\_to\_board -```py - -def open_link_to_board(self) - -``` - - - -Open a connection to the board. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read using nrfutil. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### vcom0\_device -```py - -def vcom0_device(self) - -``` - - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - -### \_ensure\_board\_link\_open -```py - -def _ensure_board_link_open(self) - -``` - - - -### \_ensure\_nrfutil\_installed -```py - -def _ensure_nrfutil_installed(self) - -``` - - - -### \_first\_attached\_board\_serial -```py - -def _first_attached_board_serial(self) - -``` - - - -Check if an nRF device is attached. - - -### \_get\_nrfutil\_json\_msg -```py - -def _get_nrfutil_json_msg(self, json_messages, message_type) - -``` - - - -### \_run\_nrfutil -```py - -def _run_nrfutil(self, args, as_json=False, custom_error=None, init=False) - -``` - - - - diff --git a/docs/openocd.md b/docs/openocd.md deleted file mode 100644 index d99e14c..0000000 --- a/docs/openocd.md +++ /dev/null @@ -1,417 +0,0 @@ -# Package tockloader.openocd Documentation - - -Interface for boards using OpenOCD. - -This interface has a special option called `openocd_options` which is just a -list of strings that are interpreted as flags to the OpenOCD class in this file. -These allow individual boards to have custom operations in a semi-reasonable -way. Note, I just made up the string (flag) names; they are not passed to -OpenOCD directly. - -## Class OpenOCD -Base class for interacting with hardware boards. All of the class functions -should be overridden to support a new method of interacting with a board. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### attached\_board\_exists -```py - -def attached_board_exists(self) - -``` - - - -For this particular board communication channel, check if there appears -to be a valid board attached to the host that tockloader can communicate -with. - - -### bootloader\_is\_present -```py - -def bootloader_is_present(self) - -``` - - - -Check for the Tock bootloader. Returns `True` if it is present, `False` -if not, and `None` if unsure. - - -### clear\_bytes -```py - -def clear_bytes(self, address) - -``` - - - -Clear at least one byte starting at `address`. - -This API is designed to support "ending the linked list of apps", or -clearing flash enough so that the flash after the last valid app will -not parse as a valid TBF header. - -Different chips with different mechanisms for writing/erasing flash make -implementing specific erase behavior difficult. Instead, we provide this -rough API, which is sufficient for the task of ending the linked list, -but doesn't guarantee exactly how many bytes after address will be -cleared, or how they will be cleared. - - -### determine\_current\_board -```py - -def determine_current_board(self) - -``` - - - -Figure out which board we are connected to. Most likely done by reading -the attributes. Doesn't return anything. - - -### enter\_bootloader\_mode -```py - -def enter_bootloader_mode(self) - -``` - - - -Get to a mode where we can read & write flash. - - -### exit\_bootloader\_mode -```py - -def exit_bootloader_mode(self) - -``` - - - -Get out of bootloader mode and go back to running main code. - - -### flash\_binary -```py - -def flash_binary(self, address, binary, pad=False) - -``` - - - -Write using openocd `program` command. - - -### get\_all\_attributes -```py - -def get_all_attributes(self) - -``` - - - -Get all attributes on a board. Returns an array of attribute dicts. - - -### get\_apps\_start\_address -```py - -def get_apps_start_address(self) - -``` - - - -Return the address in flash where apps start. - - -### get\_attribute -```py - -def get_attribute(self, index) - -``` - - - -Get a single attribute. Returns a dict with two keys: `key` and `value`. - - -### get\_board\_arch -```py - -def get_board_arch(self) - -``` - - - -Return the architecture of the board we are connected to. - - -### get\_board\_name -```py - -def get_board_name(self) - -``` - - - -Return the name of the board we are connected to. - - -### get\_bootloader\_version -```py - -def get_bootloader_version(self) - -``` - - - -Return the version string of the bootloader. Should return a value -like `0.5.0`, or `None` if it is unknown. - - -### get\_flash\_address -```py - -def get_flash_address(self) - -``` - - - -Return the address where flash starts. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return the kernel ABI version installed on the board. If the version -cannot be determined, return `None`. - - -### get\_page\_size -```py - -def get_page_size(self) - -``` - - - -Return the size of the page in bytes for the connected board. - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -Check if the board name is a known board. - - -### open\_link\_to\_board -```py - -def open_link_to_board(self) - -``` - - - -Open a connection to the board. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Display the boards that have settings configured in tockloader. - - -### read\_range -```py - -def read_range(self, address, length) - -``` - - - -Read a specific range of flash. - -If this fails for some reason this should return an empty binary array. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -### set\_attribute -```py - -def set_attribute(self, index, raw) - -``` - - - -Set a single attribute. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address the bootloader jumps to to start the actual code. - - -### translate\_address -```py - -def translate_address(self, address) - -``` - - - -Translate an address from MCU address space to the address required for -the board interface. This is used for boards where the address passed to -the board interface is not the address where this region is exposed in -the MCU address space. This method must be called from the board -interface implementation prior to memory accesses. - - -### \_align\_and\_stretch\_to\_page -```py - -def _align_and_stretch_to_page(self, address, binary) - -``` - - - -Return a new (address, binary) that is a multiple of the page size -and is aligned to page boundaries. - - -### \_configure\_from\_known\_boards -```py - -def _configure_from_known_boards(self) - -``` - - - -If we know the name of the board we are interfacing with, this function -tries to use the `KNOWN_BOARDS` array to populate other needed settings -if they have not already been set from other methods. - -This can be used in multiple locations. First, it is used when -tockloader first starts because if a user passes in the `--board` -argument then we know the board and can try to pull in settings from -KNOWN_BOARDS. Ideally, however, the user doesn't have to pass in any -arguments, but then we won't know what board until after we have had a -chance to read its attributes. The board at least needs the "board" -attribute to be set, and then we can use KNOWN_BOARDS to fill in the -rest. - - -### \_decode\_attribute -```py - -def _decode_attribute(self, raw) - -``` - - - -### \_gather\_openocd\_cmdline -```py - -def _gather_openocd_cmdline(self, commands, binary, write=True, exit=True) - -``` - - - -- `commands`: List of openocd commands. Use {binary} for where the name - of the binary file should be substituted. -- `binary`: A bytes() object that will be used to write to the board. -- `write`: Set to true if the command writes binaries to the board. Set - to false if the command will read bits from the board. -- `exit`: When `True`, openocd will exit after executing commands. - - -### \_list\_emulators -```py - -def _list_emulators(self) - -``` - - - -Return a list of board names that are attached to the host. - - -### \_run\_openocd\_commands -```py - -def _run_openocd_commands(self, commands, binary, write=True) - -``` - - - - diff --git a/docs/tab.md b/docs/tab.md deleted file mode 100644 index 95ef3b2..0000000 --- a/docs/tab.md +++ /dev/null @@ -1,188 +0,0 @@ -# Package tockloader.tab Documentation - -## Class TAB -Tock Application Bundle object. This class handles the TAB format. -### \_\_init\_\_ -```py - -def __init__(self, tab_path, args=Namespace()) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### extract\_app -```py - -def extract_app(self, arch) - -``` - - - -Return a `TabApp` object from this TAB, or `None` if the requested -architecture is not present in the TAB. You must specify the desired MCU -architecture so the correct App object can be retrieved. Note that an -architecture may have multiple TBF files if the app is compiled for a -fixed address, and multiple fixed address versions are included in the -TAB. - - -### extract\_tbf -```py - -def extract_tbf(self, tbf_name) - -``` - - - -Return a `TabApp` object from this TAB. You must specify the -desired TBF name, and only that TBF will be returned. - - -### get\_app\_name -```py - -def get_app_name(self) - -``` - - - -Return the app name from the metadata file. - - -### get\_compatible\_boards -```py - -def get_compatible_boards(self) - -``` - - - -Return a list of compatible boards from the metadata file. - - -### get\_supported\_architectures -```py - -def get_supported_architectures(self) - -``` - - - -Return a list of architectures that this TAB has compiled binaries for. -Note that this will return all architectures that have any TBF binary, -but some of those TBF binaries may be compiled for very specific -addresses. That is, there isn't a guarantee that the TBF file will work -on any chip with one of the supported architectures. - - -### get\_tbf\_names -```py - -def get_tbf_names(self) - -``` - - - -Returns a list of the names of all of the .tbf files contained in the -TAB, without the extension. - - -### is\_compatible\_with\_board -```py - -def is_compatible_with_board(self, board) - -``` - - - -Check if the Tock app is compatible with a particular Tock board. - - -### is\_compatible\_with\_kernel\_version -```py - -def is_compatible_with_kernel_version(self, kernel_version) - -``` - - - -Check if the Tock app is compatible with the version of the kernel. -Default to yes unless we can be confident the answer is no. - -`kernel_version` should be a string, or None if the kernel API version -is unknown. - - -### update\_tbf -```py - -def update_tbf(self, app) - -``` - - - -Inserts a new or modified `TabApp` into the .tab file. - -Only works with .tab files stored locally. - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_extract\_tbf\_from\_filebuffer -```py - -def _extract_tbf_from_filebuffer(self, tbf_filename, binary) - -``` - - - -### \_get\_metadata\_key -```py - -def _get_metadata_key(self, key) - -``` - - - -Return the value for a specific key from the metadata file. - - -### \_parse\_metadata -```py - -def _parse_metadata(self) - -``` - - - -Open and parse the included metadata file in the TAB, returning the -key-value pairs as a dict. - - - diff --git a/docs/tbfh.md b/docs/tbfh.md deleted file mode 100644 index 795de9d..0000000 --- a/docs/tbfh.md +++ /dev/null @@ -1,1939 +0,0 @@ -# Package tockloader.tbfh Documentation - -## Class TBFFooter -Represent an optional footer after the application binary in the TBF. -### \_\_init\_\_ -```py - -def __init__(self, tbfh, app_binary, buffer) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### add\_credential -```py - -def add_credential(self, credential_type, public_key, private_key, integrity_blob, cleartext_id) - -``` - - - -Add credential by credential type name. - - -### delete\_credential -```py - -def delete_credential(self, credential_type) - -``` - - - -Remove credential by credential type. - - -### delete\_tlv -```py - -def delete_tlv(self, tlvid) - -``` - - - -Delete a particular TLV by ID if it exists. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -Get the TBF footer in a bytes array. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### shrink -```py - -def shrink(self, number_bytes) - -``` - - - -Try to shrink the footer `number_bytes`. Shrink as much as possible up -to the number by removing padding. - - -### to\_str\_at\_address -```py - -def to_str_at_address(self, address) - -``` - - - -### verify\_credentials -```py - -def verify_credentials(self, public_keys, integrity_blob) - -``` - - - -Check credential TLVs with an optional array of public keys (stored as -binary arrays). - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFFooterTLVCredentials -Represent a Credentials TLV in the footer of a TBF. -### \_\_init\_\_ -```py - -def __init__(self, buffer, integrity_blob) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### shrink -```py - -def shrink(self, num_bytes) - -``` - - - -Shrink a reserved credential by the number of bytes specified. Do -nothing if this is not a reserved credential. - - -### verify -```py - -def verify(self, keys, integrity_blob) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_credentials\_name\_to\_id -```py - -def _credentials_name_to_id(credential_type) - -``` - - - -### \_credentials\_type\_to\_str -```py - -def _credentials_type_to_str(self) - -``` - - - - - -## Class TBFFooterTLVCredentialsConstructor -Represent a Credentials TLV in the footer of a TBF. -### \_\_init\_\_ -```py - -def __init__(self, credential_id) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### compute -```py - -def compute(self, public_key, private_key, integrity_blob, cleartext_id) - -``` - - - -Actually generate the credential. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### shrink -```py - -def shrink(self, num_bytes) - -``` - - - -Shrink a reserved credential by the number of bytes specified. Do -nothing if this is not a reserved credential. - - -### verify -```py - -def verify(self, keys, integrity_blob) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_credentials\_name\_to\_id -```py - -def _credentials_name_to_id(credential_type) - -``` - - - -### \_credentials\_type\_to\_str -```py - -def _credentials_type_to_str(self) - -``` - - - - - -## Class TBFHeader -Tock Binary Format header class. This can parse TBF encoded headers and -return various properties of the application. -### \_\_init\_\_ -```py - -def __init__(self, buffer) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### add\_tlv -```py - -def add_tlv(self, tlvname, parameters) - -``` - - - -### adjust\_starting\_address -```py - -def adjust_starting_address(self, address) - -``` - - - -Alter this TBF header so the fixed address in flash will be correct -if the entire TBF binary is loaded at address `address`. - - -### corrupt\_tbf -```py - -def corrupt_tbf(self, field_name, value) - -``` - - - -Give a field name and value to set when creating the binary. - - -### delete\_tlv -```py - -def delete_tlv(self, tlvname) - -``` - - - -Delete a particular TLV by ID if it exists. - - -### get\_app\_name -```py - -def get_app_name(self) - -``` - - - -Return the package name if it was encoded in the header, otherwise -return a tuple of (package_name_offset, package_name_size). - - -### get\_app\_size -```py - -def get_app_size(self) - -``` - - - -Get the total size the app takes in bytes in the flash of the chip. - - -### get\_app\_version -```py - -def get_app_version(self) - -``` - - - -Return the version number of the application, if there is one. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -Get the TBF header in a bytes array. - - -### get\_binary\_end\_offset -```py - -def get_binary_end_offset(self) - -``` - - - -Return at what offset the application binary ends. Remaining space -is taken up by footers. - - -### get\_fixed\_addresses -```py - -def get_fixed_addresses(self) - -``` - - - -Return (fixed_address_ram, fixed_address_flash) if there are fixed -addresses, or None. - - -### get\_footer\_size -```py - -def get_footer_size(self) - -``` - - - -Return the size in bytes of the footer. If no footer is included this -will return 0. - - -### get\_header\_size -```py - -def get_header_size(self) - -``` - - - -Get the size of the header in bytes. This includes any alignment -padding at the end of the header. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return (kernel_major, kernel_minor) if there is kernel version present, -or None. - - -### get\_size\_before\_app -```py - -def get_size_before_app(self) - -``` - - - -Get the number of bytes before the actual app binary in the .tbf file. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -Return true if this TBF header includes the fixed addresses TLV. - - -### has\_footer -```py - -def has_footer(self) - -``` - - - -Return true if this TBF has a footer. - - -### has\_kernel\_version -```py - -def has_kernel_version(self) - -``` - - - -Return true if this TBF header includes the kernel version TLV. - - -### is\_app -```py - -def is_app(self) - -``` - - - -Whether this is an app or padding. - - -### is\_enabled -```py - -def is_enabled(self) - -``` - - - -Whether the application is marked as enabled. Enabled apps start when -the board boots, and disabled ones do not. - - -### is\_modified -```py - -def is_modified(self) - -``` - - - -Whether the TBF header has been modified by Tockloader after it was -initially read in (either from a new TAB or from the board). - - -### is\_sticky -```py - -def is_sticky(self) - -``` - - - -Whether the app is marked sticky and won't be erase during normal app -erases. - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -Whether the CRC and other checks passed for this header. - - -### modify\_tlv -```py - -def modify_tlv(self, tlvname, field, value) - -``` - - - -Modify a TLV by setting a particular field in the TLV object to value. - - -### object -```py - -def object(self) - -``` - - - -### set\_app\_size -```py - -def set_app_size(self, size) - -``` - - - -Set the total size the app takes in bytes in the flash of the chip. - -Since this does not change the header size we do not need to update -any other fields in the header. - - -### set\_flag -```py - -def set_flag(self, flag_name, flag_value) - -``` - - - -Set a flag in the TBF header. - -Valid flag names: `enable`, `sticky` - - -### to\_str\_at\_address -```py - -def to_str_at_address(self, address) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_checksum -```py - -def _checksum(self, buffer) - -``` - - - -Calculate the TBF header checksum. - - -### \_get\_binary\_tlv -```py - -def _get_binary_tlv(self) - -``` - - - -Get the TLV for the binary header, whether it's a program or main. - - -### \_get\_tlv -```py - -def _get_tlv(self, tlvid) - -``` - - - -Return the TLV from the self.tlvs array if it exists. - - - - -## Class TBFHeaderPadding -TBF Header that is only padding between apps. Since apps are packed as -linked-list, this allows apps to be pushed to later addresses while -preserving the linked-list structure. -### \_\_init\_\_ -```py - -def __init__(self, size) - -``` - - - -Create the TBF header. All we need to know is how long the entire -padding should be. - - -### add\_tlv -```py - -def add_tlv(self, tlvname, parameters) - -``` - - - -### adjust\_starting\_address -```py - -def adjust_starting_address(self, address) - -``` - - - -Alter this TBF header so the fixed address in flash will be correct -if the entire TBF binary is loaded at address `address`. - - -### corrupt\_tbf -```py - -def corrupt_tbf(self, field_name, value) - -``` - - - -Give a field name and value to set when creating the binary. - - -### delete\_tlv -```py - -def delete_tlv(self, tlvname) - -``` - - - -Delete a particular TLV by ID if it exists. - - -### get\_app\_name -```py - -def get_app_name(self) - -``` - - - -Return the package name if it was encoded in the header, otherwise -return a tuple of (package_name_offset, package_name_size). - - -### get\_app\_size -```py - -def get_app_size(self) - -``` - - - -Get the total size the app takes in bytes in the flash of the chip. - - -### get\_app\_version -```py - -def get_app_version(self) - -``` - - - -Return the version number of the application, if there is one. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -Get the TBF header in a bytes array. - - -### get\_binary\_end\_offset -```py - -def get_binary_end_offset(self) - -``` - - - -Return at what offset the application binary ends. Remaining space -is taken up by footers. - - -### get\_fixed\_addresses -```py - -def get_fixed_addresses(self) - -``` - - - -Return (fixed_address_ram, fixed_address_flash) if there are fixed -addresses, or None. - - -### get\_footer\_size -```py - -def get_footer_size(self) - -``` - - - -Return the size in bytes of the footer. If no footer is included this -will return 0. - - -### get\_header\_size -```py - -def get_header_size(self) - -``` - - - -Get the size of the header in bytes. This includes any alignment -padding at the end of the header. - - -### get\_kernel\_version -```py - -def get_kernel_version(self) - -``` - - - -Return (kernel_major, kernel_minor) if there is kernel version present, -or None. - - -### get\_size\_before\_app -```py - -def get_size_before_app(self) - -``` - - - -Get the number of bytes before the actual app binary in the .tbf file. - - -### has\_fixed\_addresses -```py - -def has_fixed_addresses(self) - -``` - - - -Return true if this TBF header includes the fixed addresses TLV. - - -### has\_footer -```py - -def has_footer(self) - -``` - - - -Return true if this TBF has a footer. - - -### has\_kernel\_version -```py - -def has_kernel_version(self) - -``` - - - -Return true if this TBF header includes the kernel version TLV. - - -### is\_app -```py - -def is_app(self) - -``` - - - -Whether this is an app or padding. - - -### is\_enabled -```py - -def is_enabled(self) - -``` - - - -Whether the application is marked as enabled. Enabled apps start when -the board boots, and disabled ones do not. - - -### is\_modified -```py - -def is_modified(self) - -``` - - - -Whether the TBF header has been modified by Tockloader after it was -initially read in (either from a new TAB or from the board). - - -### is\_sticky -```py - -def is_sticky(self) - -``` - - - -Whether the app is marked sticky and won't be erase during normal app -erases. - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -Whether the CRC and other checks passed for this header. - - -### modify\_tlv -```py - -def modify_tlv(self, tlvname, field, value) - -``` - - - -Modify a TLV by setting a particular field in the TLV object to value. - - -### object -```py - -def object(self) - -``` - - - -### set\_app\_size -```py - -def set_app_size(self, size) - -``` - - - -Set the total size the app takes in bytes in the flash of the chip. - -Since this does not change the header size we do not need to update -any other fields in the header. - - -### set\_flag -```py - -def set_flag(self, flag_name, flag_value) - -``` - - - -Set a flag in the TBF header. - -Valid flag names: `enable`, `sticky` - - -### to\_str\_at\_address -```py - -def to_str_at_address(self, address) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_checksum -```py - -def _checksum(self, buffer) - -``` - - - -Calculate the TBF header checksum. - - -### \_get\_binary\_tlv -```py - -def _get_binary_tlv(self) - -``` - - - -Get the TLV for the binary header, whether it's a program or main. - - -### \_get\_tlv -```py - -def _get_tlv(self, tlvid) - -``` - - - -Return the TLV from the self.tlvs array if it exists. - - - - -## Class TBFTLV -None -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - - - -## Class TBFTLVFixedAddress -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVKernelVersion -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVMain -None -### \_\_init\_\_ -```py - -def __init__(self, buffer) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVPackageName -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVPermissions -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### add -```py - -def add(self, parameters) - -``` - - - -### get\_allowed\_commands -```py - -def get_allowed_commands(self) - -``` - - - -Returns a dict of the format: - -``` -{ - driver_number: [allowed command ID list] -} -``` - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVPersistentACL -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVPicOption1 -None -### \_\_init\_\_ -```py - -def __init__(self, buffer) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVProgram -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, total_size=0) - -``` - - - -Create a Program TLV. To create an empty program TLV, pass `None` in as -the buffer and the total size of the app in `total_size`. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVShortId -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVUnknown -None -### \_\_init\_\_ -```py - -def __init__(self, tipe, buffer) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TBFTLVWriteableFlashRegions -None -### \_\_init\_\_ -```py - -def __init__(self, buffer, parameters=[]) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### add -```py - -def add(self, parameters) - -``` - - - -### get\_size -```py - -def get_size(self) - -``` - - - -### get\_tlvid -```py - -def get_tlvid(self) - -``` - - - -### object -```py - -def object(self) - -``` - - - -### pack -```py - -def pack(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -### get\_addable\_tlvs -```py - -def get_addable_tlvs() - -``` - - - -Return a list of (tlv_name, #parameters) tuples for all TLV types that -tockloader can add. - - -### get\_tlv\_names -```py - -def get_tlv_names() - -``` - - - -Return a list of all TLV names. - - -### get\_tlvid\_from\_name -```py - -def get_tlvid_from_name(tlvname) - -``` - - - -### roundup -```py - -def roundup(x, to) - -``` - - diff --git a/docs/tickv.md b/docs/tickv.md deleted file mode 100644 index d7316ae..0000000 --- a/docs/tickv.md +++ /dev/null @@ -1,1231 +0,0 @@ -# Package tockloader.tickv Documentation - - -Manage and use a TicKV formatted database. - -TicKV: https://github.com/tock/tock/tree/master/libraries/tickv - -## Class TicKV -Interface to a generic TicKV database. -### \_\_init\_\_ -```py - -def __init__(self, storage_binary, region_size) - -``` - - - -Create a new TicKV object with a given binary buffer representing -the storage. - - -### append -```py - -def append(self, hashed_key, value) - -``` - - - -Add a key-value pair to a TicKV database. - - -### cleanup -```py - -def cleanup(self) - -``` - - - -Remove all invalid keys and re-write existing valid objects. - - -### get -```py - -def get(self, hashed_key) - -``` - - - -Retrieve a key-value object from a TicKV database. - - -### get\_all -```py - -def get_all(self, region_index) - -``` - - - -Retrieve all key-value objects from a TicKV database. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -Return the TicKV database as a binary object that can be written to the -board. - - -### invalidate -```py - -def invalidate(self, hashed_key) - -``` - - - -Mark a key-value object as deleted in a TicKV database. - - -### reset -```py - -def reset(self) - -``` - - - -Reset the database back to an initialized state. - - -### \_append\_object -```py - -def _append_object(self, kv_object) - -``` - - - -### \_get\_all -```py - -def _get_all(self, region_index, valid_only) - -``` - - - -### \_get\_number\_regions -```py - -def _get_number_regions(self) - -``` - - - -### \_get\_region\_binary -```py - -def _get_region_binary(self, region_index) - -``` - - - -### \_get\_starting\_region -```py - -def _get_starting_region(self, hashed_key) - -``` - - - -We use the lowest two bytes to determine the page we should try to find -or store this key on. - - -### \_invalidate\_hashed\_key -```py - -def _invalidate_hashed_key(self, hashed_key) - -``` - - - -### \_region\_range -```py - -def _region_range(self, starting_region) - -``` - - - -Provide an iterator for iterating all pages in the database starting -with a specific page. - - -### \_reset -```py - -def _reset(self) - -``` - - - -### \_update\_region\_binary -```py - -def _update_region_binary(self, region_index, region_binary) - -``` - - - - - -## Class TicKVObject -A TicKV object that is created in tockloader. -### \_\_init\_\_ -```py - -def __init__(self, header, value_bytes) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### get\_checksum -```py - -def get_checksum(self) - -``` - - - -### get\_hashed\_key -```py - -def get_hashed_key(self) - -``` - - - -### get\_value\_bytes -```py - -def get_value_bytes(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -Return the total length of this object in the database in bytes. - - -### object -```py - -def object(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_calculate\_checksum -```py - -def _calculate_checksum(self, object_bytes) - -``` - - - -### \_get\_object\_bytes -```py - -def _get_object_bytes(self) - -``` - - - - - -## Class TicKVObjectBase -Shared class representing an item in a TicKV database. -### \_\_init\_\_ -```py - -def __init__(self, header, checksum=None) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### get\_checksum -```py - -def get_checksum(self) - -``` - - - -### get\_hashed\_key -```py - -def get_hashed_key(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -Return the total length of this object in the database in bytes. - - -### object -```py - -def object(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_calculate\_checksum -```py - -def _calculate_checksum(self, object_bytes) - -``` - - - -### \_get\_object\_bytes -```py - -def _get_object_bytes(self) - -``` - - - - - -## Class TicKVObjectFlash -A TicKV object that is read off of the flash. -### \_\_init\_\_ -```py - -def __init__(self, binary) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### get\_checksum -```py - -def get_checksum(self) - -``` - - - -### get\_hashed\_key -```py - -def get_hashed_key(self) - -``` - - - -### get\_value\_bytes -```py - -def get_value_bytes(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -Return the total length of this object in the database in bytes. - - -### object -```py - -def object(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_calculate\_checksum -```py - -def _calculate_checksum(self, object_bytes) - -``` - - - -### \_get\_object\_bytes -```py - -def _get_object_bytes(self) - -``` - - - - - -## Class TicKVObjectHeader -The base header for an item in a TicKV database. -### \_\_init\_\_ -```py - -def __init__(self, hashed_key, version=1, flags=8) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self, length) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - - - -## Class TicKVObjectHeaderFlash -An item header read from an existing database. This handles parsing the -structure from a byte array. -### \_\_init\_\_ -```py - -def __init__(self, binary) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self, length) - -``` - - - -### get\_value\_length -```py - -def get_value_length(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - - - -## Class TicKVObjectTock -Tock-formatted object stored in TicKV. -### \_\_init\_\_ -```py - -def __init__(self, header, storage_object, padding=0, checksum=None) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### get\_checksum -```py - -def get_checksum(self) - -``` - - - -### get\_hashed\_key -```py - -def get_hashed_key(self) - -``` - - - -### get\_value\_bytes -```py - -def get_value_bytes(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -Return the total length of this object in the database in bytes. - - -### object -```py - -def object(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_calculate\_checksum -```py - -def _calculate_checksum(self, object_bytes) - -``` - - - -### \_get\_object\_bytes -```py - -def _get_object_bytes(self) - -``` - - - - - -## Class TicKVObjectTockFlash -Tock-formatted object stored in TicKV and read from flash. -### \_\_init\_\_ -```py - -def __init__(self, tickv_object) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### get\_checksum -```py - -def get_checksum(self) - -``` - - - -### get\_hashed\_key -```py - -def get_hashed_key(self) - -``` - - - -### get\_value\_bytes -```py - -def get_value_bytes(self) - -``` - - - -### invalidate -```py - -def invalidate(self) - -``` - - - -### is\_valid -```py - -def is_valid(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -Return the total length of this object in the database in bytes. - - -### object -```py - -def object(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - -### \_calculate\_checksum -```py - -def _calculate_checksum(self, object_bytes) - -``` - - - -### \_get\_object\_bytes -```py - -def _get_object_bytes(self) - -``` - - - - - -## Class TockStorageObject -This is the item stored in a TicKV value that Tock processes/kernel can -access. -### \_\_init\_\_ -```py - -def __init__(self, value_bytes, write_id=0, version=0) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TockStorageObjectFlash -Tock-formatted K-V object read from a flash binary. - -This is useful when reading a Tock K-V from a board. -### \_\_init\_\_ -```py - -def __init__(self, binary) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -### length -```py - -def length(self) - -``` - - - -### \_\_str\_\_ -```py - -def __str__(self) - -``` - - - -Return str(self). - - - - -## Class TockTicKV -Extension of a TicKV database that adds an additional header with a -`write_id` to enable enforcing access control. -### \_\_init\_\_ -```py - -def __init__(self, storage_binary, region_size) - -``` - - - -Create a new TicKV object with a given binary buffer representing -the storage. - - -### append -```py - -def append(self, key, value, write_id) - -``` - - - -Add a key-value pair to the database. - - -### cleanup -```py - -def cleanup(self) - -``` - - - -Remove all invalid keys and re-store valid key-value pairs. - - -### dump -```py - -def dump(self) - -``` - - - -Display the entire contents of the database. - - -### get -```py - -def get(self, key) - -``` - - - -Get the Tock-formatted value from the database given the key. - - -### get\_all -```py - -def get_all(self, region_index) - -``` - - - -Get all Tock objects from the database and assume they are all Tock -formatted. - - -### get\_binary -```py - -def get_binary(self) - -``` - - - -Return the TicKV database as a binary object that can be written to the -board. - - -### invalidate -```py - -def invalidate(self, key) - -``` - - - -Delete a key-value pair from the database. - - -### reset -```py - -def reset(self) - -``` - - - -Reset the database back to an initialized state. - - -### \_append\_object -```py - -def _append_object(self, kv_object) - -``` - - - -### \_get\_all -```py - -def _get_all(self, region_index, valid_only) - -``` - - - -### \_get\_number\_regions -```py - -def _get_number_regions(self) - -``` - - - -### \_get\_region\_binary -```py - -def _get_region_binary(self, region_index) - -``` - - - -### \_get\_starting\_region -```py - -def _get_starting_region(self, hashed_key) - -``` - - - -We use the lowest two bytes to determine the page we should try to find -or store this key on. - - -### \_hash\_key -```py - -def _hash_key(self, key) - -``` - - - -Compute the SipHash24 for the given key. - - -### \_hash\_key\_int -```py - -def _hash_key_int(self, key) - -``` - - - -Compute the SipHash24 for the given key. Return as u64. - - -### \_invalidate\_hashed\_key -```py - -def _invalidate_hashed_key(self, hashed_key) - -``` - - - -### \_region\_range -```py - -def _region_range(self, starting_region) - -``` - - - -Provide an iterator for iterating all pages in the database starting -with a specific page. - - -### \_reset -```py - -def _reset(self) - -``` - - - -### \_update\_region\_binary -```py - -def _update_region_binary(self, region_index, region_binary) - -``` - - - - diff --git a/docs/tockloader.md b/docs/tockloader.md deleted file mode 100644 index 5f57bac..0000000 --- a/docs/tockloader.md +++ /dev/null @@ -1,616 +0,0 @@ -# Package tockloader.tockloader Documentation - - -Main Tockloader interface. - -All high-level logic is contained here. All board-specific or communication -channel specific code is in other files. - -## Class TockLoader -Implement all Tockloader commands. All logic for how apps are arranged -is contained here. -### \_\_init\_\_ -```py - -def __init__(self, args) - -``` - - - -Initialize self. See help(type(self)) for accurate signature. - - -### dump\_flash\_page -```py - -def dump_flash_page(self, page_num) - -``` - - - -Print one page of flash contents. - - -### erase\_apps -```py - -def erase_apps(self) - -``` - - - -Erase flash where apps go. All apps are not actually cleared, we just -overwrite the header of the first app. - - -### flash\_binary -```py - -def flash_binary(self, binary, address, pad=None) - -``` - - - -Tell the bootloader to save the binary blob to an address in internal -flash. - -This will pad the binary as needed, so don't worry about the binary -being a certain length. - -This accepts an optional `pad` parameter. If used, the `pad` parameter -is a tuple of `(length, value)` signifying the number of bytes to pad, -and the particular byte to use for the padding. - - -### info -```py - -def info(self) - -``` - - - -Print all info about this board. - - -### install -```py - -def install(self, tabs, replace='yes', erase=False, sticky=False, layout=None) - -``` - - - -Add or update TABs on the board. - -- `replace` can be "yes", "no", or "only" -- `erase` if true means erase all other apps before installing -- `layout` is a layout string for specifying how apps should be installed - - -### list\_apps -```py - -def list_apps(self, verbose, quiet, map, verify_credentials_public_keys) - -``` - - - -Query the chip's flash to determine which apps are installed. - -- `verbose` - bool: Show details about TBF. -- `quiet` - bool: Just show the app name. -- `map` - bool: Show a diagram listing apps with addresses. -- `verify_credentials_public_keys`: Either `None`, meaning do not verify - any credentials, or a list of public keys binaries to use to help - verify credentials. The list can be empty and all credentials that can - be checked without keys will be verified. - - -### list\_attributes -```py - -def list_attributes(self) - -``` - - - -Download all attributes stored on the board. - - -### open -```py - -def open(self) - -``` - - - -Select and then open the correct channel to talk to the board. - -For the bootloader, this means opening a serial port. For JTAG, not much -needs to be done. - - -### print\_known\_boards -```py - -def print_known_boards(self) - -``` - - - -Simple function to print to console the boards that are hardcoded -into Tockloader to make them easier to use. - - -### read\_flash -```py - -def read_flash(self, address, length) - -``` - - - -Print some flash contents. - - -### remove\_attribute -```py - -def remove_attribute(self, key) - -``` - - - -Remove an existing attribute already stored on the board. - - -### run\_terminal -```py - -def run_terminal(self) - -``` - - - -Create an interactive terminal session with the board. - -This is a special-case use of Tockloader where this is really a helper -function for running some sort of underlying terminal-like operation. -Therefore, how we set this up is a little different from other -tockloader commands. In particular, we do _not_ want `tockloader.open()` -to have been called at this point. - - -### set\_attribute -```py - -def set_attribute(self, key, value) - -``` - - - -Change an attribute stored on the board. - - -### set\_flag -```py - -def set_flag(self, app_names, flag_name, flag_value) - -``` - - - -Set a flag in the TBF header. - - -### set\_start\_address -```py - -def set_start_address(self, address) - -``` - - - -Set the address that the bootloader jumps to to run kernel code. - - -### tickv\_append -```py - -def tickv_append(self, key, value=None, write_id=0) - -``` - - - -Add a key,value pair to the database. The first argument can a list of -key, value pairs. - - -### tickv\_cleanup -```py - -def tickv_cleanup(self) - -``` - - - -Clean the database by remove invalid objects and re-storing valid -objects. - - -### tickv\_dump -```py - -def tickv_dump(self) - -``` - - - -Display all of the contents of a TicKV database. - - -### tickv\_get -```py - -def tickv_get(self, key) - -``` - - - -Read a key, value pair from a TicKV database on a board. - - -### tickv\_hash -```py - -def tickv_hash(self, key) - -``` - - - -Return the hash of the specified key. - - -### tickv\_invalidate -```py - -def tickv_invalidate(self, key) - -``` - - - -Invalidate a particular key in the database. - - -### tickv\_reset -```py - -def tickv_reset(self) - -``` - - - -Reset the database by erasing it and re-initializing. - - -### uninstall\_app -```py - -def uninstall_app(self, app_names) - -``` - - - -If an app by this name exists, remove it from the chip. If no name is -given, present the user with a list of apps to remove. - - -### write\_flash -```py - -def write_flash(self, address, length, value) - -``` - - - -Write a byte to some flash contents. - - -### \_app\_is\_aligned\_correctly -```py - -def _app_is_aligned_correctly(self, address, size) - -``` - - - -Check if putting an app at this address will be OK with the MPU. - - -### \_bootloader\_is\_present -```py - -def _bootloader_is_present(self) - -``` - - - -Check if a bootloader exists on this board. It is specified by the -string "TOCKBOOTLOADER" being at address 0x400. - - -### \_convert\_offset\_to\_absolute\_flash\_address -```py - -def _convert_offset_to_absolute_flash_address(self, offset) - -``` - - - -Compute the absolute flash address for an offset for the attached board. - - -### \_extract\_all\_app\_headers -```py - -def _extract_all_app_headers(self, verbose=False, extract_app_binary=False) - -``` - - - -Iterate through the flash on the board for the header information about -each app. - -Options: -- `verbose`: Show ALL apps, including padding apps. -- `extract_app_binary`: Get the actual app binary in addition to the - headers. - - -### \_extract\_apps\_from\_tabs -```py - -def _extract_apps_from_tabs(self, tabs, arch) - -``` - - - -Iterate through the list of TABs and create the app object for each. - - -### \_get\_apps\_start\_address -```py - -def _get_apps_start_address(self) - -``` - - - -Return the address in flash where applications start on this platform. -This might be set on the board itself, in the command line arguments -to Tockloader, or just be the default. - - -### \_get\_flash\_start\_address -```py - -def _get_flash_start_address(self) - -``` - - - -Return the address where flash starts. - - -### \_get\_memory\_start\_address -```py - -def _get_memory_start_address(self) - -``` - - - -Return the address in memory where application RAM starts on this -platform. We mostly don't know this, so it may be None. - - -### \_print\_apps -```py - -def _print_apps(self, apps, verbose, quiet) - -``` - - - -Print information about a list of apps - - -### \_replace\_with\_padding -```py - -def _replace_with_padding(self, app) - -``` - - - -Update the TBF header of installed app `app` with a padding header -to effectively uninstall it. - - -### \_reshuffle\_apps -```py - -def _reshuffle_apps(self, apps, preserve_order=False) - -``` - - - -Given an array of apps, some of which are new and some of which exist, -sort them so we can write them to flash. - -This function is really the driver of tockloader, and is responsible for -setting up applications in a way that can be successfully used by the -board. - -If `preserve_order` is set to `True` this won't actually do any -shuffling, and will instead load apps with padding in the order they are -in the array. - - -### \_set\_attribute -```py - -def _set_attribute(self, key, value, log_status=True) - -``` - - - -Internal function for setting an attribute stored on the board. - -Bootloader mode must be active. - -Returns None if successful and an error string if not. - - -### \_start\_communication\_with\_board -```py - -def _start_communication_with_board(self) - -``` - - - -Based on the transport method used, there may be some setup required -to connect to the board. This function runs the setup needed to connect -to the board. It also times the operation. - -For the bootloader, the board needs to be reset and told to enter the -bootloader mode. For JTAG, this is unnecessary. - - -### \_tickv\_get\_database -```py - -def _tickv_get_database(self) - -``` - - - -Read the flash for a TicKV database. Since this might be stored on -external flash, we might need to use a backup mechanism to read the -flash. - - -### \_tickv\_write\_database -```py - -def _tickv_write_database(self, tickv_db) - -``` - - - -Write a TicKV database back to flash, overwriting the existing database. - - -### \_update\_board\_specific\_options -```py - -def _update_board_specific_options(self) - -``` - - - -This uses the name of the board to update any hard-coded options about -how Tockloader should function. This is a convenience mechanism, as it -prevents users from having to pass them in through command line arguments. - - - - -### flush\_local\_board -```py - -def flush_local_board(args) - -``` - - - -### get\_local\_board\_path -```py - -def get_local_board_path() - -``` - - - -### is\_known\_board -```py - -def is_known_board(board) - -``` - - - -### set\_local\_board -```py - -def set_local_board(board, arch=None, app_address=None, flash_address=None, flush_command=None, binary_path=None) - -``` - - - -### unset\_local\_board -```py - -def unset_local_board() - -``` - - diff --git a/mkdocs.yml b/mkdocs.yml index 2857bc4..270f231 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Tockloader theme: readthedocs -pages: +nav: - Home: 'index.md' - API Documentation: - Main: main.md