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 2015/12/24 01:16:55 UTC
incubator-mynewt-site git commit: fixed format errors in console.md
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/asf-site 7036cd784 -> 89cf7065d
fixed format errors in console.md
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/89cf7065
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/89cf7065
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/89cf7065
Branch: refs/heads/asf-site
Commit: 89cf7065d524d3d222e42f8a38f935479e9a0cb5
Parents: 7036cd7
Author: aditihilbert <ad...@runtime.io>
Authored: Wed Dec 23 16:16:48 2015 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Wed Dec 23 16:16:48 2015 -0800
----------------------------------------------------------------------
index.html | 2 +-
mkdocs/search_index.json | 4 +-
modules/console/index.html | 361 +++++++++++++++++++++-------------------
3 files changed, 192 insertions(+), 175 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/89cf7065/index.html
----------------------------------------------------------------------
diff --git a/index.html b/index.html
index 7d7a758..61cb9c9 100644
--- a/index.html
+++ b/index.html
@@ -497,5 +497,5 @@
<!--
MkDocs version : 0.14.0
-Build Date UTC : 2015-12-24 00:02:46.237254
+Build Date UTC : 2015-12-24 00:16:06.846472
-->
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/89cf7065/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json
index cdeef8c..d0b11a9 100644
--- a/mkdocs/search_index.json
+++ b/mkdocs/search_index.json
@@ -497,7 +497,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\negg.name: libs/shell \negg.vers: 0.1\negg.deps:\n - libs/console/full\n - libs/os\negg.identities:\n -
SHELL\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\nproject.name: boot\nproject.identities: bootloader\nproject.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util\n\n\n\nData structures\n\n\nConsole interaction is intrinsically compos
ed 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 r
eady */\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\nfunction 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 t
o 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 function 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\nExamp
le\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 function 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 in the ring buffer into a string.\n\n\nvo
id\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 function 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 de
leted 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 function 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 charac
ter 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 function 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\nArgu
ments\n\n\n\n\n\n\n\n\n\n\nch\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### \nfont color=\n#2980b9\n function console_blocking_mode \n/font\n\n\n\n\n\n\nvoid\n console_blocking_mode(void)\n\n\n Calls 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#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| none | none |\n\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nHere is an example of calling `console_blocking_mode` and printing crash information from an assert to help debug.\n\n\n\n\n\nvoid\n_assert_func(const char \nfile, int line, const char \nfunc, const char *e)\n{\n int sr;\n\n\nOS_ENTER_CRITICAL(sr);\n(void)sr;\nos_die_line = line;\nos_die_module = file;\nconsole_blocking_mode();\nconsole_printf(\"Assert %s; failed in %s:%d\\n\", e ? e : \"\", file, line);\nsystem_reset();\n\n\n\n}\n\n\n\n### \nfont color=\n#2980b9\nfunction console_write \n/font\n\n\n\n\n\n\nvoid\n console_write(char *str, int cnt)\n\n\nTransmit charac
ters to console display over serial port. \n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| *str | pointer to the character or packet to be transmitted |\n| cnt | size of the character or packet |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nHere is an example of the function being used in an echo command with a newline at the end.\n\n\n\n\n\nstatic int\nshell_echo_cmd(int argc, char **argv)\n{\n int i;\n\n\nfor (i = 1; i \n argc; i++) {\n console_write(argv[i], strlen(argv[i]));\n console_write(\" \", sizeof(\" \")-1);\n}\nconsole_write(\"\\n\", sizeof(\"\\n\")-1);\n\nreturn (0);\n\n\n\n}\n\n\n\n\n### \nfont color=\n#2980b9\n function console_read \n/font\n\n\n\n\n\n\nint\n console_read(char *str
, int cnt)\n\n\n Calls hal function hal_uart_start_rx to start receiving input from console terminal over serial port.\n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx |\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nGive at least one example of usage.\n\n\n### \nfont color=\n#2980b9\n function console_tx_char \n/font\n\n\n ``` \n static int\n console_tx_char(void *arg)\n ```\n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx |\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \n\nAny special feature/special benefit that we wa
nt 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#### Example\n\nGive at least one example of usage.\n\n\n### \nfont color=\n#2980b9\n function console_rx_char \n/font\n\n\n\n\n\n\nstatic int\n console_rx_char(void *arg, uint8_t data)\n\n\n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx |\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nGive at least one example of usage.\n\n\n### \nfont color=\n#2980b9\n function console_init \n/font\n\n\n\n\n\n\nint\n console_init(console_rx_cb rx_cb)\n```\n\n\nInitializes console receive buffer and calls hal funtions hal_uar
t_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\n\n\n\n\n\n\n\n\nxx\n\n\n\n\n\n\nyy\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\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\negg.name: libs/shell \negg.vers: 0.1\negg.deps:\n - libs/console/full\n - libs/os\negg.identities:\n -
SHELL\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\nproject.name: boot\nproject.identities: bootloader\nproject.eggs:\n - libs/os\n - libs/bootutil\n - libs/nffs\n - libs/console/stub\n - libs/util\n\n\n\nData structures\n\n\nConsole interaction is intrinsically compos
ed 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 r
eady */\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\nfunction 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 t
o 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 function 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\nExamp
le\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 function 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 in the ring buffer into a string.\n\n\nvo
id\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 function 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 de
leted 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 function 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 charac
ter 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 function 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\nArgu
ments\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 function 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 in
terrupts 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\nfunction console_write \n\n\n void\n console_write(char *str, int cnt)\n\n\n\n\nTransmit characters to console displa
y 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\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 function console_read \n\n\n int\n console_read(char *str, int cnt)\n\n\n\n\nCalls hal func
tion 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 function 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 function 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 function 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.",
"title": "Console"
},
{
@@ -522,7 +522,7 @@
},
{
"location": "/modules/console/#function-reference",
- "text": "function console_printf void \n console_printf(const char *fmt, ...) Writes 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 console_write to output the formatted data (messages) on the console. Arguments Arguments Description fmt Pointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console. ... Depending 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 in stdarg.h. Returned values None Notes While console_printf , with its well understood formatting options
in C, is more convenient and easy on the eyes than the raw output of console_write , the associated code size is considerably larger. Example Example #1: char adv_data_buf[32];\n\nvoid\ntask()\n{ \n char adv_data_buf[32];\n\n console_printf( %s , adv_data_buf);\n} Example #2: struct 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( r0:%8.8x r1:%8.8x , tf- ef- r0, tf- ef- r1);\n console_printf( r8:%8.8x r9:%8.8x , tf- r2, tf- r3);\n} function console_add_char static void\n console_add_char(struct console_ring *cr, char ch) Adds 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. Arguments Arguments Description *cr Pointer to a console ring data structure whose cr_head variable is to
be set to the second argument in this function call ch Character to be inserted to the ring Returned values None 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 Add a new line character to the output (transmit) buffer. void\ntask()\n{\n struct console_ring *tx = ct- ct_tx;\n\n console_add_char(tx, '\\n');\n} function console_pull_char static uint8_t\n console_pull_char(struct console_ring *cr) Reads (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. Arguments Arguments Description *cr Pointer to the console ring buffer from where a character is to be removed Returned values Returns the character pulled from the ring buffer. 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 Read the characters in the ring buffer into a string. void\ntask(struct console_ring *cr, char *str, int cnt)\n{ \n for (i = 0; i cnt; i++) {\n if (cr- cr_head == cr- cr_tail) {\n i = -1;\n break;\n }\n ch = console_pull_char(cr);\n *str++ = ch;\n }\n} function console_pull_char_head static void\n console_pull_char_head(struct console_ring *cr) Removes the last character inserted into the ring buffer by moving back the head location and shrinking the ring size by 1. Arguments Arguments Description cr Pointer to the console ring buffer from which the last inserted character must be deleted Returned values None Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nA
ny caveats to be careful about (e.g. high memory requirements). Example In order to see a character getting deleted when a user hits backspace while typying a command, the following needs to happen in sequence: output a backspace (move cursor back one character) output space (erasing whatever character there was before) output backspace (move cursor back one character) remove the previous character from incoming RX queue The example below shows console_pull_char_head being used for the last step. void\ntask(uint8_t data)\n{\n struct console_tty *ct = (struct console_tty *)arg;\n struct console_ring *tx = ct- ct_tx;\n struct console_ring *rx = ct- ct_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} function console_queue_char static void\n console_queue_char(char c
h) 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 function console_blocking_tx static void\n console_blocking_tx(char ch) Calls 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. Arguments Arguments ch 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 Here is an example of a console output queue being flushed. void\ntask(void)\n{\n struct console_tty *ct = console_tty;\n uint8_t byte;\n\n while (ct- ct_tx.cr_head != ct- ct_tx.cr_tail) {\n byte = console_pull_char( ct- ct_tx);\n console_blocking_tx(byte);\n }\n}\n\n-----------\n\n### font color= #2980b9 function console_blocking_mode /font void\n console_blocking_mode(void) Calls 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#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| none | none |\n\n\n#### Re
turned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nHere is an example of calling `console_blocking_mode` and printing crash information from an assert to help debug. void\n_assert_func(const char file, int line, const char func, const char *e)\n{\n int sr; OS_ENTER_CRITICAL(sr);\n(void)sr;\nos_die_line = line;\nos_die_module = file;\nconsole_blocking_mode();\nconsole_printf(\"Assert %s; failed in %s:%d\\n\", e ? e : \"\", file, line);\nsystem_reset(); } \n### font color= #2980b9 function console_write /font void\n console_write(char *str, int cnt) Transmit characters to console display over serial port. \n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| *str | pointer to the character or packet to be transmitte
d |\n| cnt | size of the character or packet |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nHere is an example of the function being used in an echo command with a newline at the end. static int\nshell_echo_cmd(int argc, char **argv)\n{\n int i; for (i = 1; i argc; i++) {\n console_write(argv[i], strlen(argv[i]));\n console_write(\" \", sizeof(\" \")-1);\n}\nconsole_write(\"\\n\", sizeof(\"\\n\")-1);\n\nreturn (0); } \n\n### font color= #2980b9 function console_read /font int\n console_read(char *str, int cnt) Calls hal function hal_uart_start_rx to start receiving input from console terminal over serial port.\n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx
|\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nGive at least one example of usage.\n\n\n### font color= #2980b9 function console_tx_char /font \n\n ``` \n static int\n console_tx_char(void *arg)\n ```\n\n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx |\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nGive at least one example of usage.\n\n\n### font color= #2980b9 functi
on console_rx_char /font static int\n console_rx_char(void *arg, uint8_t data) \n#### Arguments\n\n| Arguments | Description |\n|-------------------------|\n| xx | explain argument xx |\n| yy | explain argument yy |\n\n#### Returned values\n\nList any values returned.\nError codes?\n\n#### Notes \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#### Example\n\nGive at least one example of usage.\n\n\n### font color= #2980b9 function console_init /font int\n console_init(console_rx_cb rx_cb)\n``` Initializes 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.) Arguments Arguments xx 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 Give at least one example of usage.",
+ "text": "function console_printf void \n console_printf(const char *fmt, ...) Writes 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 console_write to output the formatted data (messages) on the console. Arguments Arguments Description fmt Pointer to C string that contains a format string that follows the same specifications as format in printf. The string is printed to console. ... Depending 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 in stdarg.h. Returned values None Notes While console_printf , with its well understood formatting options
in C, is more convenient and easy on the eyes than the raw output of console_write , the associated code size is considerably larger. Example Example #1: char adv_data_buf[32];\n\nvoid\ntask()\n{ \n char adv_data_buf[32];\n\n console_printf( %s , adv_data_buf);\n} Example #2: struct 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( r0:%8.8x r1:%8.8x , tf- ef- r0, tf- ef- r1);\n console_printf( r8:%8.8x r9:%8.8x , tf- r2, tf- r3);\n} function console_add_char static void\n console_add_char(struct console_ring *cr, char ch) Adds 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. Arguments Arguments Description *cr Pointer to a console ring data structure whose cr_head variable is to
be set to the second argument in this function call ch Character to be inserted to the ring Returned values None 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 Add a new line character to the output (transmit) buffer. void\ntask()\n{\n struct console_ring *tx = ct- ct_tx;\n\n console_add_char(tx, '\\n');\n} function console_pull_char static uint8_t\n console_pull_char(struct console_ring *cr) Reads (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. Arguments Arguments Description *cr Pointer to the console ring buffer from where a character is to be removed Returned values Returns the character pulled from the ring buffer. 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 Read the characters in the ring buffer into a string. void\ntask(struct console_ring *cr, char *str, int cnt)\n{ \n for (i = 0; i cnt; i++) {\n if (cr- cr_head == cr- cr_tail) {\n i = -1;\n break;\n }\n ch = console_pull_char(cr);\n *str++ = ch;\n }\n} function console_pull_char_head static void\n console_pull_char_head(struct console_ring *cr) Removes the last character inserted into the ring buffer by moving back the head location and shrinking the ring size by 1. Arguments Arguments Description cr Pointer to the console ring buffer from which the last inserted character must be deleted Returned values None Notes Any special feature/special benefit that we want to tout. \nDoes it need to be used with some other specific functions?\nA
ny caveats to be careful about (e.g. high memory requirements). Example In order to see a character getting deleted when a user hits backspace while typying a command, the following needs to happen in sequence: output a backspace (move cursor back one character) output space (erasing whatever character there was before) output backspace (move cursor back one character) remove the previous character from incoming RX queue The example below shows console_pull_char_head being used for the last step. void\ntask(uint8_t data)\n{\n struct console_tty *ct = (struct console_tty *)arg;\n struct console_ring *tx = ct- ct_tx;\n struct console_ring *rx = ct- ct_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} function console_queue_char static void\n console_queue_char(char c
h) 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 function console_blocking_tx static void\n console_blocking_tx(char ch) Calls 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. Arguments Arguments Description ch 8 bit character (data) to be tran
smitted 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 Here is an example of a console output queue being flushed. void\ntask(void)\n{\n struct console_tty *ct = console_tty;\n uint8_t byte;\n\n while (ct- ct_tx.cr_head != ct- ct_tx.cr_tail) {\n byte = console_pull_char( ct- ct_tx);\n console_blocking_tx(byte);\n }\n} function console_blocking_mode void\n console_blocking_mode(void) Calls 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. Arguments Arguments none 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 Here is an example of calling console_blocking_mode and printing crash information from an assert to help debug. void\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( Assert %s; failed in %s:%d\\n , e ? e : , file, line);\n system_reset();\n} function console_write void\n console_write(char *str, int cnt) Transmit characters to console display over serial port. Arguments Arguments Description *str pointer to the character or packet to be transmitted cnt size of the character or packet Returned values List any values returned.\nError codes? Notes Any special feat
ure/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 Here is an example of the function being used in an echo command with a newline at the end. static int\nshell_echo_cmd(int argc, char **argv)\n{\n int i;\n\n for (i = 1; i argc; i++) {\n console_write(argv[i], strlen(argv[i]));\n console_write( , sizeof( )-1);\n }\n console_write( \\n , sizeof( \\n )-1);\n\n return (0);\n} function console_read int\n console_read(char *str, int cnt) Calls hal function hal_uart_start_rx to start receiving input from console terminal over serial port. 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?\n
Any caveats to be careful about (e.g. high memory requirements). Example Give at least one example of usage. function console_tx_char static int\n console_tx_char(void *arg) 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 Give at least one example of usage. function console_rx_char static int\n console_rx_char(void *arg, uint8_t data) 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 Give at least one example of usage. function console_init int\n console_init(console_rx_cb rx_cb) Initializes 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.) 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 Give at least one example of usage.",
"title": "Function Reference"
},
{
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/89cf7065/modules/console/index.html
----------------------------------------------------------------------
diff --git a/modules/console/index.html b/modules/console/index.html
index dfed2c6..9f53b76 100644
--- a/modules/console/index.html
+++ b/modules/console/index.html
@@ -666,11 +666,13 @@ Error codes?</p>
<thead>
<tr>
<th>Arguments</th>
+<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>ch</td>
+<td>8 bit character (data) to be transmitted</td>
</tr>
</tbody>
</table>
@@ -694,226 +696,241 @@ task(void)
console_blocking_tx(byte);
}
}
-
------------
-
-### <font color="#2980b9"> function console_blocking_mode </font>
-
</code></pre>
-<p>void
- console_blocking_mode(void)</p>
-<pre><code> Calls 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.
-
-#### Arguments
-
-| Arguments | Description |
-|-------------------------|
-| none | none |
-
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-Here is an example of calling `console_blocking_mode` and printing crash information from an assert to help debug.
-
+<hr />
+<h3 id="function-console_blocking_mode"><font color="#2980b9"> function console_blocking_mode </font><a class="headerlink" href="#function-console_blocking_mode" title="Permanent link">¶</a></h3>
+<pre><code> void
+ console_blocking_mode(void)
</code></pre>
-<p>void
-_assert_func(const char <em>file, int line, const char </em>func, const char *e)
+<p>Calls 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.</p>
+<h4 id="arguments_6">Arguments<a class="headerlink" href="#arguments_6" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>none</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values_6">Returned values<a class="headerlink" href="#returned-values_6" title="Permanent link">¶</a></h4>
+<p>List any values returned.
+Error codes?</p>
+<h4 id="notes_6">Notes<a class="headerlink" href="#notes_6" title="Permanent link">¶</a></h4>
+<p>Any special feature/special benefit that we want to tout.
+Does it need to be used with some other specific functions?
+Any caveats to be careful about (e.g. high memory requirements).</p>
+<h4 id="example_6">Example<a class="headerlink" href="#example_6" title="Permanent link">¶</a></h4>
+<p>Here is an example of calling <code>console_blocking_mode</code> and printing crash information from an assert to help debug.</p>
+<pre><code>void
+_assert_func(const char *file, int line, const char *func, const char *e)
{
- int sr;</p>
-<pre><code>OS_ENTER_CRITICAL(sr);
-(void)sr;
-os_die_line = line;
-os_die_module = file;
-console_blocking_mode();
-console_printf("Assert %s; failed in %s:%d\n", e ? e : "", file, line);
-system_reset();
+ int sr;
+
+ OS_ENTER_CRITICAL(sr);
+ (void)sr;
+ os_die_line = line;
+ os_die_module = file;
+ console_blocking_mode();
+ console_printf("Assert %s; failed in %s:%d\n", e ? e : "", file, line);
+ system_reset();
+}
</code></pre>
-<p>}</p>
-<pre><code>
-### <font color="#2980b9">function console_write </font>
+<hr />
+<h3 id="function-console_write"><font color="#2980b9">function console_write </font><a class="headerlink" href="#function-console_write" title="Permanent link">¶</a></h3>
+<pre><code> void
+ console_write(char *str, int cnt)
</code></pre>
-<p>void
- console_write(char *str, int cnt)</p>
-<pre><code>Transmit characters to console display over serial port.
-
-#### Arguments
-
-| Arguments | Description |
-|-------------------------|
-| *str | pointer to the character or packet to be transmitted |
-| cnt | size of the character or packet |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
+<p>Transmit characters to console display over serial port. </p>
+<h4 id="arguments_7">Arguments<a class="headerlink" href="#arguments_7" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>*str</td>
+<td>pointer to the character or packet to be transmitted</td>
+</tr>
+<tr>
+<td>cnt</td>
+<td>size of the character or packet</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values_7">Returned values<a class="headerlink" href="#returned-values_7" title="Permanent link">¶</a></h4>
+<p>List any values returned.
+Error codes?</p>
+<h4 id="notes_7">Notes<a class="headerlink" href="#notes_7" title="Permanent link">¶</a></h4>
+<p>Any special feature/special benefit that we want to tout.
Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-Here is an example of the function being used in an echo command with a newline at the end.
-
-</code></pre>
-
-<p>static int
+Any caveats to be careful about (e.g. high memory requirements).</p>
+<h4 id="example_7">Example<a class="headerlink" href="#example_7" title="Permanent link">¶</a></h4>
+<p>Here is an example of the function being used in an echo command with a newline at the end.</p>
+<pre><code>static int
shell_echo_cmd(int argc, char **argv)
{
- int i;</p>
-<pre><code>for (i = 1; i < argc; i++) {
- console_write(argv[i], strlen(argv[i]));
- console_write(" ", sizeof(" ")-1);
-}
-console_write("\n", sizeof("\n")-1);
-
-return (0);
-</code></pre>
-<p>}</p>
-<pre><code>
+ int i;
-### <font color="#2980b9"> function console_read </font>
+ for (i = 1; i < argc; i++) {
+ console_write(argv[i], strlen(argv[i]));
+ console_write(" ", sizeof(" ")-1);
+ }
+ console_write("\n", sizeof("\n")-1);
+ return (0);
+}
</code></pre>
-<p>int
- console_read(char *str, int cnt)</p>
-<pre><code> Calls hal function hal_uart_start_rx to start receiving input from console terminal over serial port.
-
-#### Arguments
-
-| Arguments | Description |
-|-------------------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
+<hr />
+<h3 id="function-console_read"><font color="#2980b9"> function console_read </font><a class="headerlink" href="#function-console_read" title="Permanent link">¶</a></h3>
+<pre><code> int
+ console_read(char *str, int cnt)
+</code></pre>
-Any special feature/special benefit that we want to tout.
+<p>Calls hal function hal_uart_start_rx to start receiving input from console terminal over serial port.</p>
+<h4 id="arguments_8">Arguments<a class="headerlink" href="#arguments_8" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>xx</td>
+<td>explain argument xx</td>
+</tr>
+<tr>
+<td>yy</td>
+<td>explain argument yy</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values_8">Returned values<a class="headerlink" href="#returned-values_8" title="Permanent link">¶</a></h4>
+<p>List any values returned.
+Error codes?</p>
+<h4 id="notes_8">Notes<a class="headerlink" href="#notes_8" title="Permanent link">¶</a></h4>
+<p>Any special feature/special benefit that we want to tout.
Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-Give at least one example of usage.
-
-
-### <font color="#2980b9"> function console_tx_char </font>
-
- ```
- static int
+Any caveats to be careful about (e.g. high memory requirements).</p>
+<h4 id="example_8">Example<a class="headerlink" href="#example_8" title="Permanent link">¶</a></h4>
+<p>Give at least one example of usage.</p>
+<hr />
+<h3 id="function-console_tx_char"><font color="#2980b9"> function console_tx_char </font><a class="headerlink" href="#function-console_tx_char" title="Permanent link">¶</a></h3>
+<pre><code> static int
console_tx_char(void *arg)
- ```
-
-#### Arguments
-
-| Arguments | Description |
-|-------------------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
+</code></pre>
-Any special feature/special benefit that we want to tout.
+<h4 id="arguments_9">Arguments<a class="headerlink" href="#arguments_9" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>xx</td>
+<td>explain argument xx</td>
+</tr>
+<tr>
+<td>yy</td>
+<td>explain argument yy</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values_9">Returned values<a class="headerlink" href="#returned-values_9" title="Permanent link">¶</a></h4>
+<p>List any values returned.
+Error codes?</p>
+<h4 id="notes_9">Notes<a class="headerlink" href="#notes_9" title="Permanent link">¶</a></h4>
+<p>Any special feature/special benefit that we want to tout.
Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-Give at least one example of usage.
-
-
-### <font color="#2980b9"> function console_rx_char </font>
-
+Any caveats to be careful about (e.g. high memory requirements).</p>
+<h4 id="example_9">Example<a class="headerlink" href="#example_9" title="Permanent link">¶</a></h4>
+<p>Give at least one example of usage.</p>
+<hr />
+<h3 id="function-console_rx_char"><font color="#2980b9"> function console_rx_char </font><a class="headerlink" href="#function-console_rx_char" title="Permanent link">¶</a></h3>
+<pre><code> static int
+ console_rx_char(void *arg, uint8_t data)
</code></pre>
-<p>static int
- console_rx_char(void *arg, uint8_t data)</p>
-<pre><code>
-#### Arguments
-
-| Arguments | Description |
-|-------------------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
+<h4 id="arguments_10">Arguments<a class="headerlink" href="#arguments_10" title="Permanent link">¶</a></h4>
+<table>
+<thead>
+<tr>
+<th>Arguments</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>xx</td>
+<td>explain argument xx</td>
+</tr>
+<tr>
+<td>yy</td>
+<td>explain argument yy</td>
+</tr>
+</tbody>
+</table>
+<h4 id="returned-values_10">Returned values<a class="headerlink" href="#returned-values_10" title="Permanent link">¶</a></h4>
+<p>List any values returned.
+Error codes?</p>
+<h4 id="notes_10">Notes<a class="headerlink" href="#notes_10" title="Permanent link">¶</a></h4>
+<p>Any special feature/special benefit that we want to tout.
Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-Give at least one example of usage.
-
-
-### <font color="#2980b9"> function console_init </font>
-
+Any caveats to be careful about (e.g. high memory requirements).</p>
+<h4 id="example_10">Example<a class="headerlink" href="#example_10" title="Permanent link">¶</a></h4>
+<p>Give at least one example of usage.</p>
+<hr />
+<h3 id="function-console_init"><font color="#2980b9"> function console_init </font><a class="headerlink" href="#function-console_init" title="Permanent link">¶</a></h3>
+<pre><code> int
+ console_init(console_rx_cb rx_cb)
</code></pre>
-<p>int
- console_init(console_rx_cb rx_cb)
-```</p>
<p>Initializes 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.)</p>
-<h4 id="arguments_6">Arguments<a class="headerlink" href="#arguments_6" title="Permanent link">¶</a></h4>
+<h4 id="arguments_11">Arguments<a class="headerlink" href="#arguments_11" title="Permanent link">¶</a></h4>
<table>
<thead>
<tr>
<th>Arguments</th>
+<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>xx</td>
+<td>explain argument xx</td>
</tr>
<tr>
<td>yy</td>
+<td>explain argument yy</td>
</tr>
</tbody>
</table>
-<h4 id="returned-values_6">Returned values<a class="headerlink" href="#returned-values_6" title="Permanent link">¶</a></h4>
+<h4 id="returned-values_11">Returned values<a class="headerlink" href="#returned-values_11" title="Permanent link">¶</a></h4>
<p>List any values returned.
Error codes?</p>
-<h4 id="notes_6">Notes<a class="headerlink" href="#notes_6" title="Permanent link">¶</a></h4>
+<h4 id="notes_11">Notes<a class="headerlink" href="#notes_11" title="Permanent link">¶</a></h4>
<p>Any special feature/special benefit that we want to tout.
Does it need to be used with some other specific functions?
Any caveats to be careful about (e.g. high memory requirements).</p>
-<h4 id="example_6">Example<a class="headerlink" href="#example_6" title="Permanent link">¶</a></h4>
+<h4 id="example_11">Example<a class="headerlink" href="#example_11" title="Permanent link">¶</a></h4>
<p>Give at least one example of usage.</p>
+<hr />
</div>
</div>