You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/01/27 19:12:33 UTC
[2/3] incubator-mynewt-site git commit: console and filesystem review
edits and git repo link correction
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/8bb118dc/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index f805483..27f2814 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -17,7 +17,7 @@
},
{
"location": "/download/",
- "text": "For general information on using Git at Apache, go to https://git-wip-us.apache.org.\n\n\nIf you are not a committer, follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is https://git-wip-us.apache.org/docs/workflow.html.\n\n\nTo clone the Mynewt OS development repository:\n\n\nNon Committers\n\n\n $ git clone http://git/wip/us.apache.org/repos/asf/incubator-mynewt-larva.git\n\n\n\n\nCommitters\n\n\n $ git clone https://git/wip/us.apache.org/repos/asf/incubator-mynewt-larva.git",
+ "text": "For general information on using Git at Apache, go to https://git-wip-us.apache.org.\n\n\nIf you are not a committer, follow the proposed non-committer workflow to share your work. The direct link to the proposed workflow is https://git-wip-us.apache.org/docs/workflow.html.\n\n\nTo clone the Mynewt OS development repository:\n\n\nNon Committers\n\n\n $ git clone http://git-wip-us.apache.org/repos/asf/incubator-mynewt-larva.git\n\n\n\n\nCommitters\n\n\n $ git clone https://git-wip-us.apache.org/repos/asf/incubator-mynewt-larva.git",
"title": "Download"
},
{
@@ -727,7 +727,7 @@
},
{
"location": "/modules/console/",
- "text": "Console\n\n\nThe console is an operating system window where users interact with system programs of the operating system or a console application by entering text input (typically from a keyboard) and reading text output (typically on the computer terminal or monitor). The text written on the console brings some information and is a sequence of characters sent by the OS or programs running on the OS. \n\n\nSupport is currently available for console access via the serial port on the hardware board.\n\n\nDescription\n\n\nIn the Mynewt OS, the console library comes in two versions:\n\n\n\n\nfull - containing the full implementation\n\n\nstub - containing stubs for the API\n\n\n\n\nIf an egg or project requires the full console capability it lists that dependency in its egg.yml file. For example, the shell egg is defined by the following egg.yml file:\n\n\n egg.name: libs/shell \n egg.vers: 0.1\n egg.deps:\n - libs/console/full\n - libs/os\n
egg.identities:\n - SHELL \n\n\n\n\nOn the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but may have a dependency on an egg that has console capability. In that case you would use a console stub. Another example would be the bootloader project where we want to keep the size of the image small. It includes the \nlibs/os\n egg that can print out messages on a console (e.g. if there is a hard fault) and the \nlibs/util\n egg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub instead and the egg.yml file for the project boot egg looks like the following:\n\n\n project.name: boot\n project.identities: bootloader\n project.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util \n\n\n\n
\nData structures\n\n\nConsole interaction is intrinsically composed of two unidirectional systems. The console implementation uses two ring buffers containing input (receive) and output (transmit) characters, respectively. Read and write operations on the console_ring structure are managed by labeling the read location indicator the \ncr_tail\n and the write location indicator the \ncr_head\n. The console ring length is variable and is specified as the \ncr_size\n member of the data structure. \ncr_buf\n is the pointer to the actual array of data contained.\n\n\nstruct console_ring {\n 32 uint8_t cr_head;\n 33 uint8_t cr_tail;\n 34 uint8_t cr_size;\n 35 uint8_t _pad;\n 36 uint8_t *cr_buf;\n 37 }\n\n\n\n\nstruct console_tty {\n 40 struct console_ring ct_tx;\n 41 uint8_t ct_tx_buf[CONSOLE_TX_BUF_SZ]; /* must be after console_ring */\n 42 struct console_ring ct_rx;\n 43 uint8_t ct_rx_buf[CONSOLE_RX_BUF_SZ]; /* must be after console_ring */
\n 44 console_rx_cb ct_rx_cb; /* callback that input is ready */\n 45 console_write_char ct_write_char;\n 46 } console_tty\n\n\n\n\nList of Functions\n\n\nThe functions available in console are:\n\n\n\n\nconsole_printf\n\n\nconsole_add_char\n\n\nconsole_pull_char\n\n\nconsole_pull_char_head\n\n\nconsole_queue_char\n\n\nconsole_blocking_tx\n\n\nconsole_blocking_mode\n\n\nconsole_write\n\n\nconsole_read\n\n\nconsole_tx_char\n\n\nconsole_rx_char\n\n\nconsole_init\n\n\n\n\nFunction Reference\n\n\n\n\n console_printf\n\n\n void \n console_printf(const char *fmt, ...)\n\n\n\n\nWrites a formatted message instead of raw output to the console. It first composes a C string containing text specified as arguments to the function or containing the elements in the variable argument list passed to it using snprintf or vsnprintf, respectively. It then uses function \nconsole_write\n to output the formatted data (messages) on the console.\n\n\nArguments\n\n\n\n\n\n\n\n\nArgument
s\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfmt\n\n\nPointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console.\n\n\n\n\n\n\n...\n\n\nDepending on the format string, the function may expect either a sequence of additional arguments to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in \n in stdarg.h.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nWhile \nconsole_printf\n, with its well understood formatting options in C, is more convenient and easy on the eyes than the raw output of \nconsole_write\n, the associated code size is considerably larger.\n\n\nExample\n\n\nExample #1:\n\n\nchar adv_data_buf[32];\n\nvoid\ntask()\n{ \n char adv_data_buf[32];\n\n console_printf(\n%s\n, adv_data_buf);\n}\n\n\n\n\nExample #2:\n\n\nstruct exception_frame {\n uint32_t r0;\n uint32_t r1;\n\nstruct trap_frame {\n struct e
xception_frame *ef;\n uint32_t r2;\n uint32_t r3;\n};\n\nvoid\ntask(struct trap_frame *tf)\n{\n console_printf(\n r0:%8.8x r1:%8.8x\n, tf-\nef-\nr0, tf-\nef-\nr1);\n console_printf(\n r8:%8.8x r9:%8.8x\n, tf-\nr2, tf-\nr3);\n}\n\n\n\n\n\n\n console_add_char\n\n\n static void\n console_add_char(struct console_ring *cr, char ch)\n\n\n\n\nAdds a character to the console ring buffer. When you store an item in the buffer you store it at the head location, and the head advances to the next location.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*cr\n\n\nPointer to a console ring data structure whose \ncr_head\nvariable is to be set to the second argument in this function call\n\n\n\n\n\n\nch\n\n\nCharacter to be inserted to the ring\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful
about (e.g. high memory requirements).\n\n\nExample\n\n\nAdd a new line character to the output (transmit) buffer.\n\n\nvoid\ntask()\n{\n struct console_ring *tx = \nct-\nct_tx;\n\n console_add_char(tx, '\\n');\n}\n\n\n\n\n\n\n console_pull_char \n\n\n static uint8_t\n console_pull_char(struct console_ring *cr)\n\n\n\n\nReads (remove) a byte from the console ring buffer. When you read (pull) an item, you read it at the current tail location, and the tail advances to the next position. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*cr\n\n\nPointer to the console ring buffer from where a character is to be removed\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns the character pulled from the ring buffer.\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nRead the characters i
n the ring buffer into a string.\n\n\nvoid\ntask(struct console_ring *cr, char *str, int cnt)\n{ \n for (i = 0; i \n cnt; i++) {\n if (cr-\ncr_head == cr-\ncr_tail) {\n i = -1;\n break;\n }\n ch = console_pull_char(cr);\n *str++ = ch;\n }\n}\n\n\n\n\n\n\n console_pull_char_head \n\n\n static void\n console_pull_char_head(struct console_ring *cr)\n\n\n\n\nRemoves the last character inserted into the ring buffer by moving back the head location and shrinking the ring size by 1. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ncr\n\n\nPointer to the console ring buffer from which the last inserted character must be deleted\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nIn orde
r to see a character getting deleted when a user hits backspace while typying a command, the following needs to happen in sequence:\n\n\n\n\noutput a backspace (move cursor back one character)\n\n\noutput space (erasing whatever character there was before)\n\n\noutput backspace (move cursor back one character)\n\n\nremove the previous character from incoming RX queue\n\n\n\n\nThe example below shows console_pull_char_head being used for the last step.\n\n\nvoid\ntask(uint8_t data)\n{\n struct console_tty *ct = (struct console_tty *)arg;\n struct console_ring *tx = \nct-\nct_tx;\n struct console_ring *rx = \nct-\nct_rx;\n\n switch (data) {\n case '\\b':\n console_add_char(tx, '\\b');\n console_add_char(tx, ' ');\n console_add_char(tx, '\\b');\n console_pull_char_head(rx);\n break;\n }\n}\n\n\n\n\n\n\n\n console_queue_char \n\n\n static void\n console_queue_char(char ch)\n\n\n\n\nManage the buffer queue bef
ore inserting a character into it. If the head of the output (transmit) console ring is right up to its tail, the queue needs to be drained first before any data can be added. Then it uses console_add_char function to add the character.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nch\n\n\nCharacter to be inserted to the queue\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nThis function makes sure no interrupts are allowed while the transmit buffer is draining and the character is being added.\n\n\nExample\n\n\nInsert example\n\n\n\n\n\n\n console_blocking_tx \n\n\n static void\n console_blocking_tx(char ch)\n\n\n\n\nCalls the hal function hal_uart_blocking_tx to transmit a byte to the console over UART in a blocking mode until the entire character has been sent. Hence it must be called with interrupts disabled. It is used when printing diagnostic output from system crash. \n\n\nArguments\n\n\n\n\
n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nch\n\n\n8 bit character (data) to be transmitted\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of a console output queue being flushed.\n\n\nvoid\ntask(void)\n{\n struct console_tty *ct = \nconsole_tty;\n uint8_t byte;\n\n while (ct-\nct_tx.cr_head != ct-\nct_tx.cr_tail) {\n byte = console_pull_char(\nct-\nct_tx);\n console_blocking_tx(byte);\n }\n}\n\n\n\n\n\n\n console_blocking_mode \n\n\n void\n console_blocking_mode(void)\n\n\n\n\nCalls the console_blocking_tx function to flush the buffered console output (transmit) queue. The function OS_ENTER_CRITICAL() is called to disable interrupts and OS_EXIT_CRITICAL() is called to enabl
e interrupts back again once the buffer is flushed.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\n\n\nnone\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of calling \nconsole_blocking_mode\n and printing crash information from an assert to help debug.\n\n\nvoid\n_assert_func(const char *file, int line, const char *func, const char *e)\n{\n int sr;\n\n OS_ENTER_CRITICAL(sr);\n (void)sr;\n os_die_line = line;\n os_die_module = file;\n console_blocking_mode();\n console_printf(\nAssert %s; failed in %s:%d\\n\n, e ? e : \n, file, line);\n system_reset();\n}\n\n\n\n\n\n\n console_write \n\n\n void\n console_write(char *str, int cnt)\n\n\n\n\nTransmit characters to console display ov
er serial port. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*str\n\n\npointer to the character or packet to be transmitted\n\n\n\n\n\n\ncnt\n\n\nsize of the character or packet\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of the function being used in an echo command with a newline at the end.\n\n\nstatic int\nshell_echo_cmd(int argc, char **argv)\n{\n int i;\n\n for (i = 1; i \n argc; i++) {\n console_write(argv[i], strlen(argv[i]));\n console_write(\n \n, sizeof(\n \n)-1);\n }\n console_write(\n\\n\n, sizeof(\n\\n\n)-1);\n\n return (0);\n}\n\n\n\n\n\n\n console_read \n\n\n int\n console_read(char *str, int cnt)\n\n\n\n\nCalls hal function hal_uart
_start_rx to start receiving input from console terminal over serial port.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_tx_char \n\n\n static int\n console_tx_char(void *arg)\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functi
ons?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_rx_char \n\n\n static int\n console_rx_char(void *arg, uint8_t data)\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_init \n\n\n int\n console_init(console_rx_cb rx_cb)\n\n\n\n\nInitializes console receive buffer and calls hal funtions hal_uart_init_cbs and hal_uart_config to initialize serial port connection and configure it (e.g. baud rate, flow control etc.)\n\n\nArguments\n\n\n\n\n\
n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.",
+ "text": "Console\n\n\nThe console is an operating system window where users interact with system programs of the operating system or a console application by entering text input (typically from a keyboard) and reading text output (typically on the computer terminal or monitor). The text written on the console brings some information and is a sequence of characters sent by the OS or programs running on the OS. \n\n\nSupport is currently available for console access via the serial port on the hardware board.\n\n\nDescription\n\n\nIn the Mynewt OS, the console library comes in two versions:\n\n\n\n\nfull - containing the full implementation\n\n\nstub - containing stubs for the API\n\n\n\n\nBoth of these have \negg.yml\n file which states that they provide the \nconsole\n API. If an egg uses this API, it should list \nconsole\n as a requirement.\nFor example, the shell egg is defined by the following egg.yml file:\n\n\n egg.name: libs/shell \n egg.vers: 0.1\n egg.de
ps:\n - libs/os\n - libs/util\n egg.reqs:\n - console\n egg.identities:\n - SHELL \n\n\n\n\nThe project .yml file decides which version of the console egg should be included. \nIf project requires the full console capability it lists dependency \nlibs/console/full\n in its egg.yml file. \nOn the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but may have a dependency on an egg that has console capability. In that case you would use a console stub. Another example would be the bootloader project where we want to keep the size of the image small. It includes the \nlibs/os\n egg that can print out messages on a console (e.g. if there is a hard fault) and the \nlibs/util\n egg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub instead
and the egg.yml file for the project boot egg looks like the following:\n\n\n project.name: boot\n project.identities: bootloader\n project.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util \n\n\n\n\nConsole has 2 modes for transmit; blocking and non-blocking mode. Usually the non-blocking mode is the active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added based on these interrupts.\nBlocking mode is used when we don't want TX completion interrupts. This is used when system crashes, and we still want to output info related to that crash.\n\n\nData structures\n\n\nConsole interaction is intrinsically composed of two unidirectional systems. The console implementation uses two ring buffers containing input (receive) and output (transmit) characters, respectively. Read and write operations on the console_ring structure are managed by labeling the re
ad location indicator the \ncr_tail\n and the write location indicator the \ncr_head\n. The console ring length is variable and is specified as the \ncr_size\n member of the data structure. \ncr_buf\n is the pointer to the actual array of data contained.\n\n\nstruct console_ring {\n 32 uint8_t cr_head;\n 33 uint8_t cr_tail;\n 34 uint8_t cr_size;\n 35 uint8_t _pad;\n 36 uint8_t *cr_buf;\n 37 }\n\n\n\n\nstruct console_tty {\n 40 struct console_ring ct_tx;\n 41 uint8_t ct_tx_buf[CONSOLE_TX_BUF_SZ]; /* must be after console_ring */\n 42 struct console_ring ct_rx;\n 43 uint8_t ct_rx_buf[CONSOLE_RX_BUF_SZ]; /* must be after console_ring */\n 44 console_rx_cb ct_rx_cb; /* callback that input is ready */\n 45 console_write_char ct_write_char;\n 46 } console_tty\n\n\n\n\nList of Functions\n\n\nThe functions available in console are:\n\n\n\n\nconsole_printf\n\n\nconsole_add_char\n\n\nconsole_pull_char\n\n\nconsole_pull_char_head\n\n
\nconsole_queue_char\n\n\nconsole_blocking_tx\n\n\nconsole_blocking_mode\n\n\nconsole_write\n\n\nconsole_read\n\n\nconsole_tx_char\n\n\nconsole_rx_char\n\n\nconsole_init\n\n\n\n\nFunction Reference\n\n\n\n\n console_printf\n\n\n void \n console_printf(const char *fmt, ...)\n\n\n\n\nWrites a formatted message instead of raw output to the console. It first composes a C string containing text specified as arguments to the function or containing the elements in the variable argument list passed to it using snprintf or vsnprintf, respectively. It then uses function \nconsole_write\n to output the formatted data (messages) on the console.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfmt\n\n\nPointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console.\n\n\n\n\n\n\n...\n\n\nDepending on the format string, the function may expect either a sequence of additional arguments
to be used to replace a format specifier in the format string or a variable arguments list. va_list is a special type defined in \n in stdarg.h.\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nWhile \nconsole_printf\n, with its well understood formatting options in C, is more convenient and easy on the eyes than the raw output of \nconsole_write\n, the associated code size is considerably larger.\n\n\nExample\n\n\nExample #1:\n\n\nchar adv_data_buf[32];\n\nvoid\ntask()\n{ \n char adv_data_buf[32];\n\n console_printf(\n%s\n, adv_data_buf);\n}\n\n\n\n\nExample #2:\n\n\nstruct exception_frame {\n uint32_t r0;\n uint32_t r1;\n\nstruct trap_frame {\n struct exception_frame *ef;\n uint32_t r2;\n uint32_t r3;\n};\n\nvoid\ntask(struct trap_frame *tf)\n{\n console_printf(\n r0:%8.8x r1:%8.8x\n, tf-\nef-\nr0, tf-\nef-\nr1);\n console_printf(\n r8:%8.8x r9:%8.8x\n, tf-\nr2, tf-\nr3);\n}\n\n\n\n\n\n\n console_add_char\n\n\n static void\n console_add_
char(struct console_ring *cr, char ch)\n\n\n\n\nAdds a character to the console ring buffer. When you store an item in the buffer you store it at the head location, and the head advances to the next location.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*cr\n\n\nPointer to a console ring data structure whose \ncr_head\nvariable is to be set to the second argument in this function call\n\n\n\n\n\n\nch\n\n\nCharacter to be inserted to the ring\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nAdd a new line character to the output (transmit) buffer.\n\n\nvoid\ntask()\n{\n struct console_ring *tx = \nct-\nct_tx;\n\n console_add_char(tx, '\\n');\n}\n\n\n\n\n\n\n console_pull_char \n\n\n static uint8_t\n console_pull_char(struct con
sole_ring *cr)\n\n\n\n\nReads (remove) a byte from the console ring buffer. When you read (pull) an item, you read it at the current tail location, and the tail advances to the next position. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n*cr\n\n\nPointer to the console ring buffer from where a character is to be removed\n\n\n\n\n\n\n\n\nReturned values\n\n\nReturns the character pulled from the ring buffer.\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nRead the characters in the ring buffer into a string.\n\n\nvoid\ntask(struct console_ring *cr, char *str, int cnt)\n{ \n for (i = 0; i \n cnt; i++) {\n if (cr-\ncr_head == cr-\ncr_tail) {\n i = -1;\n break;\n }\n ch = console_pull_char(cr);\n *str++ = ch;\n }\n}\n\n\n
\n\n\n\n console_pull_char_head \n\n\n static void\n console_pull_char_head(struct console_ring *cr)\n\n\n\n\nRemoves the last character inserted into the ring buffer by moving back the head location and shrinking the ring size by 1. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ncr\n\n\nPointer to the console ring buffer from which the last inserted character must be deleted\n\n\n\n\n\n\n\n\nReturned values\n\n\nNone\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nIn order to see a character getting deleted when a user hits backspace while typying a command, the following needs to happen in sequence:\n\n\n\n\noutput a backspace (move cursor back one character)\n\n\noutput space (erasing whatever character there was before)\n\n\noutput backspace (move cursor back one character
)\n\n\nremove the previous character from incoming RX queue\n\n\n\n\nThe example below shows console_pull_char_head being used for the last step.\n\n\nvoid\ntask(uint8_t data)\n{\n struct console_tty *ct = (struct console_tty *)arg;\n struct console_ring *tx = \nct-\nct_tx;\n struct console_ring *rx = \nct-\nct_rx;\n\n switch (data) {\n case '\\b':\n console_add_char(tx, '\\b');\n console_add_char(tx, ' ');\n console_add_char(tx, '\\b');\n console_pull_char_head(rx);\n break;\n }\n}\n\n\n\n\n\n\n\n console_queue_char \n\n\n static void\n console_queue_char(char ch)\n\n\n\n\nManage the buffer queue before inserting a character into it. If the head of the output (transmit) console ring is right up to its tail, the queue needs to be drained first before any data can be added. Then it uses console_add_char function to add the character.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\
n\n\n\nch\n\n\nCharacter to be inserted to the queue\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nFunction blocks interrupts as a way of protecting against concurrent access to TX buffer.\n\n\nIf TX buffer is full, the function waits for TX buffer to drain. And the way it does it currently is by calling os_time_delay(). Therefore this function should only be called from within a task context, not from an interrupt handler. We might want to change this...\n\n\nExample\n\n\nInsert example\n\n\n\n\n\n\n console_blocking_tx \n\n\n static void\n console_blocking_tx(char ch)\n\n\n\n\nCalls the hal function hal_uart_blocking_tx to transmit a byte to the console over UART in a blocking mode until the entire character has been sent. Hence it must be called with interrupts disabled. It is used when printing diagnostic output from system crash. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nch\n\n\n8 bit c
haracter (data) to be transmitted\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of a console output queue being flushed.\n\n\nvoid\ntask(void)\n{\n struct console_tty *ct = \nconsole_tty;\n uint8_t byte;\n\n while (ct-\nct_tx.cr_head != ct-\nct_tx.cr_tail) {\n byte = console_pull_char(\nct-\nct_tx);\n console_blocking_tx(byte);\n }\n}\n\n\n\n\n\n\n console_blocking_mode \n\n\n void\n console_blocking_mode(void)\n\n\n\n\nCalls the console_blocking_tx function to flush the buffered console output (transmit) queue. The function OS_ENTER_CRITICAL() is called to disable interrupts and OS_EXIT_CRITICAL() is called to enable interrupts back again once the buffer is flushed.\n\n\nArguments\n\n\n
\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\n\n\nnone\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of calling \nconsole_blocking_mode\n and printing crash information from an assert to help debug.\n\n\nvoid\n_assert_func(const char *file, int line, const char *func, const char *e)\n{\n int sr;\n\n OS_ENTER_CRITICAL(sr);\n (void)sr;\n os_die_line = line;\n os_die_module = file;\n console_blocking_mode();\n console_printf(\nAssert %s; failed in %s:%d\\n\n, e ? e : \n, file, line);\n system_reset();\n}\n\n\n\n\n\n\n console_write \n\n\n void\n console_write(char *str, int cnt)\n\n\n\n\nTransmit characters to console display over serial port. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescript
ion\n\n\n\n\n\n\n\n\n\n\n*str\n\n\npointer to the character or packet to be transmitted\n\n\n\n\n\n\ncnt\n\n\nsize of the character or packet\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nHere is an example of the function being used in an echo command with a newline at the end.\n\n\nstatic int\nshell_echo_cmd(int argc, char **argv)\n{\n int i;\n\n for (i = 1; i \n argc; i++) {\n console_write(argv[i], strlen(argv[i]));\n console_write(\n \n, sizeof(\n \n)-1);\n }\n console_write(\n\\n\n, sizeof(\n\\n\n)-1);\n\n return (0);\n}\n\n\n\n\n\n\n console_read \n\n\n int\n console_read(char *str, int cnt)\n\n\n\n\nCalls hal function hal_uart_start_rx to start receiving input from console terminal over serial por
t.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_tx_char \n\n\n static int\n console_tx_char(void *arg)\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n
\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_rx_char \n\n\n static int\n console_rx_char(void *arg, uint8_t data)\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.\n\n\n\n\n console_init \n\n\n int\n console_init(console_rx_cb rx_cb)\n\n\n\n\nInitializes console receive buffer and calls hal funtions hal_uart_init_cbs and hal_uart_config to initialize serial port connection and configure it (e.g. baud rate, flow control etc.)\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain a
rgument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\nGive at least one example of usage.",
"title": "Console"
},
{
@@ -737,7 +737,7 @@
},
{
"location": "/modules/console/#description",
- "text": "In the Mynewt OS, the console library comes in two versions: full - containing the full implementation stub - containing stubs for the API If an egg or project requires the full console capability it lists that dependency in its egg.yml file. For example, the shell egg is defined by the following egg.yml file: egg.name: libs/shell \n egg.vers: 0.1\n egg.deps:\n - libs/console/full\n - libs/os\n egg.identities:\n - SHELL On the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but may have a dependency on an egg that has console capability. In that case you would use a console stub. Another example would be the bootloader project where we want to keep the size of the image small. It includes the libs/os egg that can print out messages on a console (e.g. if there is a hard fault) and the libs/util egg that uses full console (but only if SHELL is present to provide a CLI).
However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub instead and the egg.yml file for the project boot egg looks like the following: project.name: boot\n project.identities: bootloader\n project.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util",
+ "text": "In the Mynewt OS, the console library comes in two versions: full - containing the full implementation stub - containing stubs for the API Both of these have egg.yml file which states that they provide the console API. If an egg uses this API, it should list console as a requirement.\nFor example, the shell egg is defined by the following egg.yml file: egg.name: libs/shell \n egg.vers: 0.1\n egg.deps:\n - libs/os\n - libs/util\n egg.reqs:\n - console\n egg.identities:\n - SHELL The project .yml file decides which version of the console egg should be included. \nIf project requires the full console capability it lists dependency libs/console/full in its egg.yml file. \nOn the other hand, a project may not have a physical console (e.g. a UART port to connect a terminal to) but may have a dependency on an egg that has console capability. In that case you would use a console stub. Another example would be t
he bootloader project where we want to keep the size of the image small. It includes the libs/os egg that can print out messages on a console (e.g. if there is a hard fault) and the libs/util egg that uses full console (but only if SHELL is present to provide a CLI). However, we do not want to use any console I/O capability in this particular bootloader project to keep the size small. We simply use the console stub instead and the egg.yml file for the project boot egg looks like the following: project.name: boot\n project.identities: bootloader\n project.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util Console has 2 modes for transmit; blocking and non-blocking mode. Usually the non-blocking mode is the active one; the output buffer is drained by getting TX completion interrupts from hardware, and more data is added based on these interrupts.\nBlocking mode is used when we don't want TX completi
on interrupts. This is used when system crashes, and we still want to output info related to that crash.",
"title": "Description"
},
{
@@ -777,7 +777,7 @@
},
{
"location": "/modules/console/#console_queue_char",
- "text": "static void\n console_queue_char(char ch) Manage the buffer queue before inserting a character into it. If the head of the output (transmit) console ring is right up to its tail, the queue needs to be drained first before any data can be added. Then it uses console_add_char function to add the character. Arguments Arguments Description ch Character to be inserted to the queue Returned values List any values returned.\nError codes? Notes This function makes sure no interrupts are allowed while the transmit buffer is draining and the character is being added. Example Insert example",
+ "text": "static void\n console_queue_char(char ch) Manage the buffer queue before inserting a character into it. If the head of the output (transmit) console ring is right up to its tail, the queue needs to be drained first before any data can be added. Then it uses console_add_char function to add the character. Arguments Arguments Description ch Character to be inserted to the queue Returned values List any values returned.\nError codes? Notes Function blocks interrupts as a way of protecting against concurrent access to TX buffer. If TX buffer is full, the function waits for TX buffer to drain. And the way it does it currently is by calling os_time_delay(). Therefore this function should only be called from within a task context, not from an interrupt handler. We might want to change this... Example Insert example",
"title": " console_queue_char "
},
{
@@ -817,7 +817,7 @@
},
{
"location": "/modules/shell/",
- "text": "Shell\n\n\nThe shell is the program which puts up a prompt for a command, processes commands, and returns output. Interacting with the console of a device is done using a shell program.\n\n\nDescription\n\n\nA few commands to the console interface are currently available in the shell - \ntasks\n, \nlog\n, and \nstat stat\n. A $ prompt sign will be coming soon!\n\n\nCreate a sim target to check out these commands available in shell.\n\n\nuser@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim
successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=sim\nTarget blinky_sim successfully set compiler_def to sim\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005\n\n\n\n\n\nOpen up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set
device name to the serial port of the target. \n\n\nuser@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\nstat stat\n229881:s0: 1\n\n\n\n\n\nData structures\n\n\nReplace this with the list of data structures used, why, any neat features\n\n\nL
ist of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nshell_cmd_list_lock\n\n\nshell_cmd_list_unlock\n\n\nadd the rest\n\n\n\n\nFunction Reference\n\n\n\n\n shell_cmd_list_lock \n\n\n static int \n shell_cmd_list_lock(void)\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n shell_cmd_list_unlock \n\n\n \nInsert function callout here \n\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\
n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n next_one \n\n\n \nInsert function callout here \n\n\n\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nxx\n\n\nexplain argument xx\n\n\n\n\n\n\nyy\n\n\nexplain argument yy\n\n\n\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\n\n\nInsert the code snippet here",
+ "text": "Shell\n\n\nThe shell is the program which puts up a prompt for a command, processes commands, and returns output. Interacting with the console of a device is done using a shell program.\n\n\nDescription\n\n\nShell processes console input one line at a time. Eggs can register handlers for their commands. Shell parses the input, matches it against the set of registered commands, and then calls the handler it finds.\n\n\nA few commands are currently available in the shell - \ntasks\n, \nlog\n, and \nstat stat\n. A $ prompt sign will be coming soon!\n\n\nCreate a sim target to check out these commands available in shell.\n\n\nuser@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/d
ev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=sim\nTarget blinky_sim successfully set compiler_def to sim\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/lar
va$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005\n\n\n\n\n\nOpen up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target. \n\n\nuser@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags
: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\nstat stat\n229881:s0: 1\n\n\n\n\n\nData structures\n\n\nReplace this with the list of data structures used, why, any neat features\n\n\nList of Functions\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nshell_cmd_register\n\n\nadd the rest\n\n\n\n\nFunction Reference\n\n\n\n\n shell_cmd_register \n\n\n int \n shell_cmd_register(struct shell_cmd *sc, char *cmd, shell_cmd_func_t func)\n\n\n\n\nRegister a shell command. When shell reads a line of input which starts with \ncmd\n, it calls the handler \nfunc\n. Caller must allocate data structure \nsc\n. Shell internally links this to it's list of command handlers.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nsc\n\n\nPointer to data structure shell egg uses to store info about the registered command\n\n\n\n\n\n\ncmd\n\n\nCommand getting registered\n\n\n\n\n\n\nfunc\n\n\nFunction to call when command is received from console\n\n\n
\n\n\n\n\n\nReturned values\n\n\nList any values returned.\nError codes?\n\n\nNotes\n\n\nShell splits the arguments following the command into an array of character pointers, and passes these to registered handler. The function will be called in shell task's context, so the command handler should look out for possible issues due to concurrency.\n\n\nExample\n\n\nHere is FS registering command for 'ls'.\n\n\nstatic struct shell_cmd fs_ls_struct;\n\nstatic int\nfs_ls_cmd(int argc, char **argv)\n{\n /* XXX do some stuff */\n console_printf(\n%d files\\n\n, file_cnt);\n return 0;\n}\n\nvoid\nfs_cli_init(void)\n{\n int rc;\n\n rc = shell_cmd_register(\nfs_ls_struct, \nls\n, fs_ls_cmd);\n if (rc != 0) {\n return;\n }\n}",
"title": "Shell"
},
{
@@ -827,7 +827,7 @@
},
{
"location": "/modules/shell/#description",
- "text": "A few commands to the console interface are currently available in the shell - tasks , log , and stat stat . A $ prompt sign will be coming soon! Create a sim target to check out these commands available in shell. user@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=sim\nTarget blinky_sim successfully set compiler_def to sim\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\
nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005 Open up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target. user@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n
174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\nstat stat\n229881:s0: 1",
+ "text": "Shell processes console input one line at a time. Eggs can register handlers for their commands. Shell parses the input, matches it against the set of registered commands, and then calls the handler it finds. A few commands are currently available in the shell - tasks , log , and stat stat . A $ prompt sign will be coming soon! Create a sim target to check out these commands available in shell. user@~/dev/larva$ newt target create blinky_sim\nCreating target blinky_sim\nTarget blinky_sim successfully created!\nuser@~/dev/larva$ newt target set blinky_sim name=blinky_sim\nTarget blinky_sim successfully set name to blinky_sim\nuser@~/dev/larva$ newt target set blinky_sim arch=sim\nTarget blinky_sim successfully set arch to sim\nuser@~/dev/larva$ newt target set blinky_sim project=blinky\nTarget blinky_sim successfully set project to blinky\nuser@~/dev/larva$ newt target set blinky_sim bsp=hw/bsp/native\nTarget blinky_sim successfully set bsp to hw/bsp/native
\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=sim\nTarget blinky_sim successfully set compiler_def to sim\nuser@~/dev/larva$ newt target set blinky_sim compiler_def=debug\nTarget blinky_sim successfully set compiler_def to debug\nuser@~/dev/larva$ newt target set blinky_sim compiler=sim\nTarget blinky_sim successfully set compiler to sim\nuser@~/dev/larva$ newt target show\nblinky_sim\n arch: sim\n bsp: hw/bsp/native\n compiler: sim\n compiler_def: debug\n name: blinky_sim\n project: blinky\nuser@~/dev/larva$ newt target build blinky_sim\nBuilding target blinky_sim (project = blinky)\nCompiling case.c\nCompiling suite.c\nCompiling testutil.c\n..\n..\nBuilding project blinky\nLinking blinky.elf\nSuccessfully run!\n\nuser@~/dev/larva$ ./project/blinky/bin/blinky_sim/blinky.elf\nuart0 at /dev/ttys005 Open up a new terminal to run minicom, a text-based serial port control and terminal emulation program. Set device name to the serial port of the target.
user@~$ minicom -D /dev/ttys005\nWelcome to minicom 2.7\n\nOPTIONS: \nCompiled on Nov 24 2015, 16:14:21.\nPort /dev/ttys005, 11:32:17\n\nPress Meta-Z for help on special keys\n\nlog \n174578:[0] bla\n174578:[0] bab\n\ntasks\n217809:6 tasks: \n217809: shell (prio: 3, nw: 0, flags: 0x0, ssize: 0, cswcnt: 59, tot_run_time: 0ms)\n217840: idle (prio: 255, nw: 0, flags: 0x0, ssize: 0, cswcnt: 18763, tot_run_time: 217809ms)\n217878: uart_poller (prio: 0, nw: 217819, flags: 0x0, ssize: 0, cswcnt: 18667, tot_run_time: 0ms)\n217923: task1 (prio: 1, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n217953: os_sanity (prio: 254, nw: 218710, flags: 0x0, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n218010: task2 (prio: 2, nw: 217709, flags: 0x3, ssize: 0, cswcnt: 218, tot_run_time: 0ms)\n\nstat stat\n229881:s0: 1",
"title": "Description"
},
{
@@ -837,7 +837,7 @@
},
{
"location": "/modules/shell/#list-of-functions",
- "text": "The functions available in this OS feature are: shell_cmd_list_lock shell_cmd_list_unlock add the rest",
+ "text": "The functions available in this OS feature are: shell_cmd_register add the rest",
"title": "List of Functions"
},
{
@@ -846,19 +846,9 @@
"title": "Function Reference"
},
{
- "location": "/modules/shell/#shell_cmd_list_lock",
- "text": "static int \n shell_cmd_list_lock(void) Arguments Arguments Description xx explain argument xx yy explain argument yy Returned values List any values returned.\nError codes? Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements). Example Insert the code snippet here",
- "title": " shell_cmd_list_lock "
- },
- {
- "location": "/modules/shell/#shell_cmd_list_unlock",
- "text": "Insert function callout here Arguments Arguments Description xx explain argument xx yy explain argument yy Returned values List any values returned.\nError codes? Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements). Example Insert the code snippet here",
- "title": " shell_cmd_list_unlock "
- },
- {
- "location": "/modules/shell/#next_one",
- "text": "Insert function callout here Arguments Arguments Description xx explain argument xx yy explain argument yy Returned values List any values returned.\nError codes? Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements). Example Insert the code snippet here",
- "title": " next_one "
+ "location": "/modules/shell/#shell_cmd_register",
+ "text": "int \n shell_cmd_register(struct shell_cmd *sc, char *cmd, shell_cmd_func_t func) Register a shell command. When shell reads a line of input which starts with cmd , it calls the handler func . Caller must allocate data structure sc . Shell internally links this to it's list of command handlers. Arguments Arguments Description sc Pointer to data structure shell egg uses to store info about the registered command cmd Command getting registered func Function to call when command is received from console Returned values List any values returned.\nError codes? Notes Shell splits the arguments following the command into an array of character pointers, and passes these to registered handler. The function will be called in shell task's context, so the command handler should look out for possible issues due to concurrency. Example Here is FS registering command for 'ls'. static struct shell_cmd fs_ls_struct;\n\nstatic int\nfs_ls_cmd(i
nt argc, char **argv)\n{\n /* XXX do some stuff */\n console_printf( %d files\\n , file_cnt);\n return 0;\n}\n\nvoid\nfs_cli_init(void)\n{\n int rc;\n\n rc = shell_cmd_register( fs_ls_struct, ls , fs_ls_cmd);\n if (rc != 0) {\n return;\n }\n}",
+ "title": " shell_cmd_register "
},
{
"location": "/modules/bootloader/",
@@ -907,7 +897,7 @@
},
{
"location": "/modules/filesystem/",
- "text": "Filesystem\n\n\nMynewt provides a Flash File System abstraction layer (fs) to allow you to swap out the default Newtron File System (nffs) with a different file system of your choice. \n\n\nDescription\n\n\nThe default file system used in the Mynewt OS is the Newtron Flash File System (nffs). Hence the \nnffs\n egg description lists \nlibs/fs\n as a dependency. \n\n\negg.name: libs/nffs\negg.vers: 0.1\negg.identities: NFFS\negg.deps:\n - libs/os\n - libs/fs\n - libs/testutil\n - hw/hal\n\n\n\n\nIf the user wishes to use a different flash file system (say, \"ownffs\"), the directory containing \"ownffs\" code must include the \negg.yml\n file stating the dependency on \nlibs/fs\n listed as shown above. \"ownffs\" uses the \nlibs/fs\n API available in mynewt, thus minimizing changes to other parts of the project.\n\n\nNote that this generic file system (\nfs\n) API does not expose any file system detection, initialization, and formatting functions. The
se function calls remain specific to the chosen file system. For example, Project Slinky uses the default Newtron File System (nffs) and therefore calls nffs_init() to initialize the nffs memory and data structures before any other file system operations are attempted. As shown below, the egg for Project Slinky includes the \nlibs/imgmgr\n egg which in turn includes the \nlibs/bootutil\n egg. The egg description for \nlibs/bootutil\n specifies \nfs/nffs\n as a dependency.\n\n\n\n egg.name: project/slinky\n egg.vers: 0.1\n egg.deps:\n - libs/os\n - libs/console/full\n - libs/shell\n - libs/newtmgr\n - libs/imgmgr\n - sys/config\n - sys/log\n - sys/stats\n\n\n\n\n\n egg.name: libs/imgmgr\n egg.vers: 0.1\n egg.deps:\n - libs/newtmgr\n - libs/bootutil\n egg.deps.FS:\n - fs/fs\n egg.cflags.FS: -DFS_PRESENT\n\n\n\n\n\n egg.name: libs/bootutil\n egg.vers: 0.1 \n egg.deps: \n
- fs/nffs\n - libs/os \n - libs/testutil\n - hw/hal\n\n\n\n\nData Structures\n\n\nAPI\n\n\n struct fs_file;\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nfs_open\n\n\nfs_close\n\n\nfs_read\n\n\nfs_write\n\n\nfs_seek\n\n\nfs_getpos\n\n\nfs_filelen\n\n\nfs_unlink\n\n\nfs_rename\n\n\nfs_mkdir\n\n\nfs_opendir\n\n\nfs_readdir\n\n\nfs_closedir\n\n\nfs_dirent_name\n\n\nfs_dirent_is_dir\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\nfsutil_read_file\n\n\nfsutil_write_file\n\n\n\n\nAPI Reference\n\n\n\n\n fs_open \n\n\n int\n fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file);\n\n\n\n\nOpens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist.\n\n\nBy default (when nffs is the underlying filesystem used) the mode strings passed to fopen() map to nffs_open
()'s access flags as follows:\n\n\n \nr\n - NFFS_ACCESS_READ\n \nr+\n - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE\n \nw\n - NFFS_ACCESS_WRITE | NFFS_ACCESS_TRUNCATE\n \nw+\n - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE | NFFS_ACCESS_TRUNCATE\n \na\n - NFFS_ACCESS_WRITE | NFFS_ACCESS_APPEND\n \na+\n - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE | NFFS_ACCESS_APPEND\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nPointer to the file created at the path of the specified filename\n\n\n\n\n\n\naccess_flags\n\n\nFlags controlling file access; see above table\n\n\n\n\n\n\nout_file\n\n\nOn success, a pointer to the newly-created file handle gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requireme
nts).\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_close \n\n\n int\n fs_close(struct fs_file *file); \n\n\n\n\nCloses the specified file and invalidates the file handle. If the file has already been unlinked, and this is the last open handle to the file, this operation causes the file to be deleted from disk.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nAny special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements).\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_read \n\n\n int\n fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len);\n\n\n\n\nReads data from the specified file. If more data is requ
ested than remains in the file, all available data is retrieved. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the the file to read from\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to attempt to read\n\n\n\n\n\n\nout_data\n\n\nThe destination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThis type of short read results in a success return code.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_write \n\n\n int\n fs_write(struct fs_file *file, const void *data, int len);\n\n\n\n\nWrites the supplied data to the current offset of the specified file handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to wr
ite\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_seek \n\n\n int\n fs_seek(struct fs_file *file, uint32_t offset);\n\n\n\n\nPositions a file's read and write pointer at the specified offset. The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file). \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to reposition\n\n\n\n\n\n\noffset\n\n\nThe 0-based file offset to seek to\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_getpos \n\n\n uint32_t\n fs_getpos(const struct fs_file *file);\n\n\n\n\nRetrieves the current read and write position
of the specified open file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\nThe file offset, in bytes\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_filelen \n\n\n int\n fs_filelen(const struct fs_file *file, uint32_t *out_len);\n\n\n\n\n\nRetrieves the current length of the specified open file.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes in the file gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_unlink \n\n\n int\n fs_unlink(const char *filename);\n\n\n\n\n\nUnlinks the file or directory at the specified path. If the path refers to a directory, all the
directory's descendants are recursively unlinked. Any open file handles refering to an unlinked file remain valid, and can be read from and written to.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nThe path of the file or directory to unlink\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_rename \n\n\n int\n fs_rename(const char *from, const char *to);\n\n\n\n\n\nPerforms a rename and / or move of the specified source path to the specified destination. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfrom\n\n\nThe source path\n\n\n\n\n\n\nto\n\n\nThe destination path\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe source path can refer to either a file or a directory. All intermediate directories in the destination path must
already exist. If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory. If an object already exists at the specified destination path, this function causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_mkdir \n\n\n int\n fs_mkdir(const char *path);\n\n\n\n\n\nCreates the directory represented by the specified path. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure.\n\n\n\n\nNotes\n\n\nAll intermediate directories must already exist. The specified path must start with a '/' character.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_opendir \n\n\n\n int\n fs_opendir(const char *path, struct fs_dir **out_dir);\n\n\n\n\n\n
Opens the directory at the specified path. The directory's contents can be read with subsequent calls to fs_readdir(). When you are done with the directory handle, close it with fs_closedir(). \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\nout_dir\n\n\nOn success, points to the directory handle\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if the specified directory does not exist (no such file)\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\nUnlinking files from the directory while it is open may result in unpredictable behavior. New files can be created inside the directory.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_readdir \n\n\n int\n fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);\n\n\n\n\n\nReads the next entry in an open directory. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\n
dir\n\n\nThe directory handle to read from\n\n\n\n\n\n\nout_dirent\n\n\nOn success, points to the next child entry in the specified directory\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if there are no more entries in the parent directory\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_closedir \n\n\n int\n fs_closedir(struct fs_dir *dir);\n\n\n\n\n\nCloses the specified directory handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nPointer to the directory to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_name \n\n\n int\n fs_dirent_name(const struct fs_dirent *dirent, size_t max_len,\n char *out_name, uint8_t *out_name_len);\n\n\n\n\n\nRetrieves the filename of the specified directory entry. \n\n\nA
rguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\nmax_len\n\n\nSize of the \"out_name\" character buffer\n\n\n\n\n\n\nout_name\n\n\nOn success, the entry's filename is written here; always null-terminated\n\n\n\n\n\n\nout_name_len\n\n\nOn success, contains the actual length of the filename, NOT including the null-terminator\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe retrieved filename is always null-terminated. To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size (filename max length + 1) should be used.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_is_dir \n\n\n int\n fs_dirent_is_dir(const struct fs_dirent *dirent);\n\n\n\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArgumen
ts\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1: The entry is a directory\n\n\n0: The entry is a regular file.\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_read_file \n\n\n int\n fsutil_read_file(const char *path, uint32_t offset, uint32_t len, void *dst,\n uint32_t *out_len);\n\n\n\n\nCalls fs_open(), fs_read(), and fs_close() to open a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\noffset\n\n\nPosition of the file's read pointer\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to attempt to read\n\n\n\n\n\n\ndst\n\n\nDestination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of
bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_write_file \n\n\n int\n fsutil_write_file(const char *path, const void *data, uint32_t len);\n\n\n\n\nCalls fs_open(), fs_write(), and fs_close() to open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here",
+ "text": "Filesystem\n\n\nMynewt provides a Flash File System abstraction layer (fs) to allow you to swap out the default Newtron File System (nffs) with a different file system of your choice. \n\n\nDescription\n\n\nThe default file system used in the Mynewt OS is the Newtron Flash File System (nffs). Hence the \nnffs\n egg description lists \nlibs/fs\n as a dependency. \n\n\negg.name: libs/nffs\negg.vers: 0.1\negg.identities: NFFS\negg.deps:\n - libs/os\n - libs/fs\n - libs/testutil\n - hw/hal\n\n\n\n\nIf the user wishes to use a different flash file system (say, \"ownffs\"), the directory containing \"ownffs\" code must include the \negg.yml\n file stating the dependency on \nlibs/fs\n listed as shown above. \"ownffs\" uses the \nlibs/fs\n API available in mynewt, thus minimizing changes to other parts of the project.\n\n\nNote that this generic file system (\nfs\n) API does not expose any file system detection, initialization, and formatting functions. The
se function calls remain specific to the chosen file system. For example, Project Slinky uses the default Newtron File System (nffs) and therefore calls nffs_init() to initialize the nffs memory and data structures before any other file system operations are attempted. As shown below, the egg for Project Slinky includes the \nlibs/imgmgr\n egg which in turn includes the \nlibs/bootutil\n egg. The egg description for \nlibs/bootutil\n specifies \nfs/nffs\n as a dependency.\n\n\n\n egg.name: project/slinky\n egg.vers: 0.1\n egg.deps:\n - libs/os\n - libs/console/full\n - libs/shell\n - libs/newtmgr\n - libs/imgmgr\n - sys/config\n - sys/log\n - sys/stats\n\n\n\n\n\n egg.name: libs/imgmgr\n egg.vers: 0.1\n egg.deps:\n - libs/newtmgr\n - libs/bootutil\n egg.deps.FS:\n - fs/fs\n egg.cflags.FS: -DFS_PRESENT\n\n\n\n\n\n egg.name: libs/bootutil\n egg.vers: 0.1 \n egg.deps: \n
- fs/nffs\n - libs/os \n - libs/testutil\n - hw/hal\n\n\n\n\nData Structures\n\n\nAPI\n\n\n struct fs_file;\n\n\n\n\nThe functions available in this OS feature are:\n\n\n\n\nfs_open\n\n\nfs_close\n\n\nfs_read\n\n\nfs_write\n\n\nfs_seek\n\n\nfs_getpos\n\n\nfs_filelen\n\n\nfs_unlink\n\n\nfs_rename\n\n\nfs_mkdir\n\n\nfs_opendir\n\n\nfs_readdir\n\n\nfs_closedir\n\n\nfs_dirent_name\n\n\nfs_dirent_is_dir\n\n\n\n\nAdditional file system utilities that bundle some of the basic functions above are:\n\n\n\n\nfsutil_read_file\n\n\nfsutil_write_file\n\n\n\n\nAPI Reference\n\n\n\n\n fs_open \n\n\n int\n fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file);\n\n\n\n\nOpens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist.\n\n\nThe mode strings passed to fopen() map to fs_open()'s access flags as follows:\n\n\n \nr\n - FS_ACCESS_
READ\n \nr+\n - FS_ACCESS_READ | FS_ACCESS_WRITE\n \nw\n - FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n \nw+\n - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_TRUNCATE\n \na\n - FS_ACCESS_WRITE | FS_ACCESS_APPEND\n \na+\n - FS_ACCESS_READ | FS_ACCESS_WRITE | FS_ACCESS_APPEND\n\n\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfilename\n\n\nPointer to the file created at the path of the specified filename\n\n\n\n\n\n\naccess_flags\n\n\nFlags controlling file access; see above table\n\n\n\n\n\n\nout_file\n\n\nOn success, a pointer to the newly-created file handle gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThere is no concept of current working directory. Therefore all file names should start with '/'.\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_close \n\n\n int\n fs_close(struct fs_file *file)\n\n\n\n\nCloses the specified file an
d invalidates the file handle. If the file has already been unlinked, and this is the last open handle to the file, this operation causes the file to be deleted from disk.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nDon't use file handle after closing the file.\n\n\nExample\n\n\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_read \n\n\n int\n fs_read(struct fs_file *file, uint32_t len, void *out_data, uint32_t *out_len);\n\n\n\n\nReads data from the specified file. If more data is requested than remains in the file, all available data is retrieved. Function returns in \nout_len\n the actual number of bytes read (less or equal to \nlen\n).\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the the file to read from\n\n\n\n\n\n\nlen\n\n\nThe number
of bytes to attempt to read\n\n\n\n\n\n\nout_data\n\n\nThe destination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThis type of short read results in a success return code.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n\n fs_write \n\n\n int\n fs_write(struct fs_file *file, const void *data, int len);\n\n\n\n\nWrites the supplied data to the current offset of the specified file handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_see
k \n\n\n int\n fs_seek(struct fs_file *file, uint32_t offset);\n\n\n\n\nPositions a file's read and write pointer at the specified offset. The offset is expressed as the number of bytes from the start of the file (i.e., seeking to offset 0 places the pointer at the first byte in the file). \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to reposition\n\n\n\n\n\n\noffset\n\n\nThe 0-based file offset to seek to\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_getpos \n\n\n uint32_t\n fs_getpos(const struct fs_file *file);\n\n\n\n\nRetrieves the current read and write position of the specified open file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\nThe file offset, in bytes\n\n\n\n\n
Notes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_filelen \n\n\n int\n fs_filelen(const struct fs_file *file, uint32_t *out_len);\n\n\n\n\n\nRetrieves the current length of the specified open file.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfile\n\n\nPointer to the file to query\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes in the file gets written here\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_unlink \n\n\n int\n fs_unlink(const char *filename);\n\n\n\n\n\nUnlinks the file or directory at the specified path. If the path refers to a directory, all the directory's descendants are recursively unlinked. Any open file handles refering to an unlinked file remain valid, and can be read from and written to.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n
\n\n\n\nfilename\n\n\nThe path of the file or directory to unlink\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_rename \n\n\n int\n fs_rename(const char *from, const char *to);\n\n\n\n\n\nPerforms a rename and / or move of the specified source path to the specified destination. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\nfrom\n\n\nThe source path\n\n\n\n\n\n\nto\n\n\nThe destination path\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe source path can refer to either a file or a directory. All intermediate directories in the destination path must already exist. If the source path refers to a file, the destination path must contain a full filename path, rather than just the new parent directory. If an object already exists at the specified destination path, this func
tion causes it to be unlinked prior to the rename (i.e., the destination gets clobbered).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_mkdir \n\n\n int\n fs_mkdir(const char *path);\n\n\n\n\n\nCreates the directory represented by the specified path. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure.\n\n\n\n\nNotes\n\n\nAll intermediate directories must already exist. The specified path must start with a '/' character.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_opendir \n\n\n\n int\n fs_opendir(const char *path, struct fs_dir **out_dir);\n\n\n\n\n\nOpens the directory at the specified path. The directory's contents can be read with subsequent calls to fs_readdir(). When you are done with the directory handle, close it with fs_closedir(). \n\n\nArguments\n\n\n\n\n\n\n\n
\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory to create\n\n\n\n\n\n\nout_dir\n\n\nOn success, points to the directory handle\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if the specified directory does not exist (no such file)\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\nUnlinking files from the directory while it is open may result in unpredictable behavior. New files can be created inside the directory.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_readdir \n\n\n int\n fs_readdir(struct fs_dir *dir, struct fs_dirent **out_dirent);\n\n\n\n\n\nReads the next entry in an open directory. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nThe directory handle to read from\n\n\n\n\n\n\nout_dirent\n\n\nOn success, points to the next child entry in the specified directory\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nFS_ENOENT if there are n
o more entries in the parent directory\n\n\nOther nonzero on error.\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_closedir \n\n\n int\n fs_closedir(struct fs_dir *dir);\n\n\n\n\n\nCloses the specified directory handle. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndir\n\n\nPointer to the directory to close\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_name \n\n\n int\n fs_dirent_name(const struct fs_dirent *dirent, size_t max_len,\n char *out_name, uint8_t *out_name_len);\n\n\n\n\n\nRetrieves the filename of the specified directory entry. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\nmax_len\n\n\nSize of the \"out_name\" character buffer\n\n\n\n\n\n\nout_name\n\n\nOn su
ccess, the entry's filename is written here; always null-terminated\n\n\n\n\n\n\nout_name_len\n\n\nOn success, contains the actual length of the filename, NOT including the null-terminator\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThe retrieved filename is always null-terminated. To ensure enough space to hold the full filename plus a null-termintor, a destination buffer of size (filename max length + 1) should be used.\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fs_dirent_is_dir \n\n\n int\n fs_dirent_is_dir(const struct fs_dirent *dirent);\n\n\n\n\n\nTells you whether the specified directory entry is a sub-directory or a regular file. \n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\ndirent\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n1: The entry is a directory\n\n\n0: The entry is a regular file.\n\n\n\n\nNotes\n\n\n\n\nEx
ample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_read_file \n\n\n int\n fsutil_read_file(const char *path, uint32_t offset, uint32_t len, void *dst,\n uint32_t *out_len);\n\n\n\n\nCalls fs_open(), fs_read(), and fs_close() to open a file at the specified path, retrieve data from the file starting from the specified offset, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the directory entry to query\n\n\n\n\n\n\noffset\n\n\nPosition of the file's read pointer\n\n\n\n\n\n\nlen\n\n\nNumber of bytes to attempt to read\n\n\n\n\n\n\ndst\n\n\nDestination buffer to read into\n\n\n\n\n\n\nout_len\n\n\nOn success, the number of bytes actually read gets written here. Pass null if you don't care.\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\nThis is a convenience function. You can use it if the file
is small (caller has enough buffer space to hold all the file contents in memory).\n\n\nExample\n\n\n\n\nInsert the code snippet here\n\n\n\n\n\n\n\n fsutil_write_file \n\n\n int\n fsutil_write_file(const char *path, const void *data, uint32_t len);\n\n\n\n\nCalls fs_open(), fs_write(), and fs_close() to open a file at the specified path, write the supplied data to the current offset of the specified file handle, and close the file and invalidate the file handle.\n\n\nArguments\n\n\n\n\n\n\n\n\nArguments\n\n\nDescription\n\n\n\n\n\n\n\n\n\n\npath\n\n\nPointer to the file to write to\n\n\n\n\n\n\ndata\n\n\nThe data to write\n\n\n\n\n\n\nlen\n\n\nThe number of bytes to write\n\n\n\n\n\n\n\n\nReturned values\n\n\n\n\n0 on success\n\n\nnonzero on failure\n\n\n\n\nNotes\n\n\n\n\nExample\n\n\n\n\nInsert the code snippet here",
"title": "File System Abstraction"
},
{
@@ -937,17 +927,17 @@
},
{
"location": "/modules/filesystem/#fs_open",
- "text": "int\n fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file); Opens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist. By default (when nffs is the underlying filesystem used) the mode strings passed to fopen() map to nffs_open()'s access flags as follows: r - NFFS_ACCESS_READ\n r+ - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE\n w - NFFS_ACCESS_WRITE | NFFS_ACCESS_TRUNCATE\n w+ - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE | NFFS_ACCESS_TRUNCATE\n a - NFFS_ACCESS_WRITE | NFFS_ACCESS_APPEND\n a+ - NFFS_ACCESS_READ | NFFS_ACCESS_WRITE | NFFS_ACCESS_APPEND Arguments Arguments Description filename Pointer to the file created at the path of the specified filename access_flags Flags controlling file access; see above table out_file On success, a pointer to the newly-created file handle
gets written here Returned values 0 on success nonzero on failure Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nAny caveats to be careful about (e.g. high memory requirements). Example Insert the code snippet here",
+ "text": "int\n fs_open(const char *filename, uint8_t access_flags, struct fs_file **out_file); Opens a file at the specified path. The result of opening a nonexistent file depends on the access flags specified. All intermediate directories must already exist. T
<TRUNCATED>