From 65e7cd5684d8d522e03892bb16a01fbe5fb17b56 Mon Sep 17 00:00:00 2001 From: Vlad Radulescu Date: Wed, 25 Feb 2026 22:58:02 +0200 Subject: [PATCH 1/2] Small changes to the docs. Mkdocs apparently change the pages key to nav key. At least the latest version I got would revuse to build. Added some more info on how to build the documentation kind of suggesting we do this in the venv. On ubuntu at least the environment is manged by the OS, so you can't install without some amount or risk an the console yelling at you. Probably the location I added this is not optimal, but I'm open to suggestions. Added the .venv to gitignore. --- .gitignore | 1 + README.md | 7 +++++-- mkdocs.yml | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) 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/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 From acd69906ae78d11347a8f3d31f9fe245a72ccae4 Mon Sep 17 00:00:00 2001 From: Vlad Radulescu Date: Wed, 25 Feb 2026 23:03:41 +0200 Subject: [PATCH 2/2] The .md file are build artefacts. They probably should not be checked in the repo at all. So I removed them. --- docs/.gitignore | 1 + docs/app_installed.md | 349 ------- docs/app_padding.md | 303 ------ docs/app_tab.md | 473 --------- docs/board_interface.md | 386 -------- docs/bootloader_serial.md | 592 ----------- docs/display.md | 414 -------- docs/exceptions.md | 5 - docs/flash_file.md | 427 -------- docs/helpers.md | 245 ----- docs/index.md | 465 --------- docs/jlinkexe.md | 433 --------- docs/main.md | 429 -------- docs/nrfutil.md | 427 -------- docs/openocd.md | 417 -------- docs/tab.md | 188 ---- docs/tbfh.md | 1939 ------------------------------------- docs/tickv.md | 1231 ----------------------- docs/tockloader.md | 616 ------------ 19 files changed, 1 insertion(+), 9339 deletions(-) delete mode 100644 docs/app_installed.md delete mode 100644 docs/app_padding.md delete mode 100644 docs/app_tab.md delete mode 100644 docs/board_interface.md delete mode 100644 docs/bootloader_serial.md delete mode 100644 docs/display.md delete mode 100644 docs/exceptions.md delete mode 100644 docs/flash_file.md delete mode 100644 docs/helpers.md delete mode 100644 docs/index.md delete mode 100644 docs/jlinkexe.md delete mode 100644 docs/main.md delete mode 100644 docs/nrfutil.md delete mode 100644 docs/openocd.md delete mode 100644 docs/tab.md delete mode 100644 docs/tbfh.md delete mode 100644 docs/tickv.md delete mode 100644 docs/tockloader.md 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() - -``` - -