diff --git a/Documentation/components/binfmt.rst b/Documentation/components/binfmt.rst index 1267153d37..8fb237c338 100644 --- a/Documentation/components/binfmt.rst +++ b/Documentation/components/binfmt.rst @@ -206,21 +206,10 @@ Basic module management :return: This is a NuttX internal function so it follows the convention that 0 (``OK``) is returned on success and a negated ``errno`` is returned on failure. - -.. c:function:: int exec(FAR const char *filename, FAR const char **argv, FAR const struct symtab_s *exports, int nexports) - This is a convenience function that wraps :c:func:`load_module` and - :c:func:`exec_module` into one call. - - :param filename: Full path to the binary to be loaded. - :param argv: Argument list. - :param exports: Table of exported symbols. - :param exports: The number of symbols in exports. - - :return: - This is an end-user function, so it follows the normal convention: - Returns 0 (``OK``) on success. On failure, it returns -1 (ERROR) - with ``errno`` set appropriately. +.. tip:: + The function :c:func:`exec` is a convenience function that wraps + :c:func:`load_module` and :c:func:`exec_module` into one call. ``PATH`` traversal logic ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/components/nxflat.rst b/Documentation/components/nxflat.rst index 0a494e9b83..115a14fb79 100644 --- a/Documentation/components/nxflat.rst +++ b/Documentation/components/nxflat.rst @@ -320,75 +320,8 @@ because these segments overlap. object to create the final, NXFLAT module ``hello`` by executing ``ldnxflat``. -Binary Loader APIs -================== - -**Relevant Header Files:** - - - The interface to the binary loader is described in the header file - ```include/nuttx/binfmt/binfmt.h``. - A brief summary of the APIs prototyped in that header file are listed - below. - - NXFLAT APIs needed to register NXFLAT as a binary loader appear in - the header file - ``include/nuttx/binfmt/nxflat.h``. - - The format of an NXFLAT object itself is described in the header - file: - ``include/nuttx/binfmt/nxflat.h``. - -**binfmt Registration** These first interfaces are used only by a binary -loader module, such as NXFLAT itself. NXFLAT (or any future binary -loader) calls ``register_binfmt()`` to incorporate itself into the -system. In this way, the binary loader logic is dynamically extensible -to support any kind of loader. Normal application code should not be -concerned with these interfaces. - -.. c:function:: int register_binfmt(FAR struct binfmt_s *binfmt) - - Register a loader for a binary format - - :return: This is a NuttX internal function so it follows the - convention that 0 (``OK``) is returned on success and a - negated errno is returned on failure. - -.. c:function:: int unregister_binfmt(FAR struct binfmt_s *binfmt) - - Register a loader for a binary format - - :return: This is a NuttX internal function so it follows the - convention that 0 (``OK``) is returned on success and a - negated errno is returned on failure. - -**Binary Loader Interfaces**. The remaining APIs are called by user -applications to maintain modules in the file system. - -.. c:function:: int load_module(FAR struct binary_s *bin) - - Load a module into memory, bind it to an exported symbol take, - and prep the module for execution. - - :return: This is a NuttX internal function so it follows the - convention that 0 (``OK``) is returned on success and a - negated errno is returned on failure. - -.. c:function:: int unload_module(FAR struct binary_s *bin) - - Unload a (non-executing) module from memory. If the module - has been started (via :c:func:`exec_module`), calling this - will be fatal. - - :return: This is a NuttX internal function so it follows the - convention that 0 (``OK``) is returned on success and a - negated errno is returned on failure. - -.. c:function:: int exec_module(FAR const struct binary_s *bin) - - Execute a module that has been loaded into memory by - :c:func:`load_module`. - - :return: This is a NuttX internal function so it follows the - convention that 0 (``OK``) is returned on success and a - negated errno is returned on failure. +**binfmt Registration** NXFLAT calls :c:func:`register_binfmt` to +incorporate itself into the system. Appendix A: No GOT Operation ============================ diff --git a/Documentation/components/nxgraphics/nx.rst b/Documentation/components/nxgraphics/nx.rst index 49f33c7d0f..0206a4d338 100644 --- a/Documentation/components/nxgraphics/nx.rst +++ b/Documentation/components/nxgraphics/nx.rst @@ -69,13 +69,21 @@ start this daemon. There are two ways that this can be done: board startup logic can run automatically during the early system if ``CONFIG_BOARD_LATE_INITIALIZE`` is defined in the configuration. Or, the board startup logic can execute under control of the application - by calling the ``boardctl(BOARDIOC_INIT, arg)`` OS interface. + by calling :c:func:`boardctl` as: + + .. code-block:: c + + boardctl(BOARDIOC_INIT, arg) The board initialization logic will run in either case and the simple call to ``nxmu_start()`` will start the NX server. -#. The NX server may also be started later by the application via the - ``boardctl(BOARDIOC_NX_START, arg)`` +#. The NX server may also be started later by the application via + :c:func:`boardctl` as: + + .. code-block:: c + + boardctl(BOARDIOC_NX_START, arg) .. c:function:: int nxmu_start(int display, int plane); @@ -91,35 +99,6 @@ start this daemon. There are two ways that this can be done: A negated ``errno`` value is returned on failure. The ``errno`` value indicates the nature of the failure. -.. c:function:: void boardctl(...) - - Generic NuttX interface that among - many of it functions, may also be used to start the NX server. - - In a small embedded system, there will typically be a much greater - interaction between application and low-level board features. The - canonically correct to implement such interactions is by implementing a - character driver and performing the interactions via low level - ``ioctl()`` calls. This, however, may not be practical in many cases and - will lead to "correct" but awkward implementations. - - ``boardctl()`` is non-standard OS interface to alleviate the problem. It - basically circumvents the normal device driver ioctl interlace and - allows the application to perform direction IOCTL-like calls to the - board-specific logic. In it is especially useful for setting up board - operational and test configurations. - - When called with the ``cmd`` of ``BOARDIOC_NX_START``, then the - ``boardctl()`` will call ``nxmu_start`` indirectly on behalf of the - application. In this case the ``arg`` parameter is ignored. - - :param cmd: Identifies the board command to be executed - :param arg: The argument that accompanies the command. The nature of the argument - is determined by the specific command. - - :return: On success zero (``OKERROR``) is returned on failure - with the ``errno`` variable set to indicate the nature of the failure. - NX Server Callbacks =================== diff --git a/Documentation/components/paging.rst b/Documentation/components/paging.rst index 92d9c608f5..ecede3a5e3 100644 --- a/Documentation/components/paging.rst +++ b/Documentation/components/paging.rst @@ -371,25 +371,9 @@ Most standard, architecture-specific functions are declared in ``include/nuttx/arch.h``. However, for the case of this paging logic, the architecture specific functions are declared in ``include/nuttx/page.h``. Standard, architecture-specific functions that -should already be provided in the architecture port. The following are -used by the common paging logic: - -.. c:function:: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state) - - The currently executing task at the head of the ready to run list - must be stopped. Save its context and move it to the inactive list - specified by task_state. This function is called by the on-demand - paging logic in order to block the task that requires the page fill, - and to - -.. c:function:: void up_unblock_task(FAR struct tcb_s *tcb) - - A task is currently in an inactive task list but has been prepped to - execute. Move the TCB to the ready-to-run list, restore its context, - and start execution. This function will be called - -New, additional functions that must be implemented just for on-demand -paging support: +should already be provided in the architecture port are :c:func:`up_block_task` +and :c:func:`up_unblock_task`. New, additional functions that must be +implemented just for on-demand paging support are: .. c:function:: int up_checkmapping(FAR struct tcb_s *tcb) diff --git a/Documentation/reference/os/arch.rst b/Documentation/reference/os/arch.rst index c9829f3814..3b94233272 100644 --- a/Documentation/reference/os/arch.rst +++ b/Documentation/reference/os/arch.rst @@ -161,17 +161,17 @@ APIs Exported by Architecture-Specific Logic to NuttX .. c:function:: void up_unblock_task(FAR struct tcb_s *tcb) -A task is currently in an inactive task list but -has been prepped to execute. Move the TCB to the ready-to-run -list, restore its context, and start execution. + A task is currently in an inactive task list but + has been prepped to execute. Move the TCB to the ready-to-run + list, restore its context, and start execution. -This function is called only from the NuttX scheduling logic. -Interrupts will always be disabled when this function is called. + This function is called only from the NuttX scheduling logic. + Interrupts will always be disabled when this function is called. -:param tcb: Refers to the tcb to be unblocked. This tcb is in one - of the waiting tasks lists. It must be moved to the - ready-to-run list and, if it is the highest priority ready to - run tasks, executed. + :param tcb: Refers to the tcb to be unblocked. This tcb is in one + of the waiting tasks lists. It must be moved to the + ready-to-run list and, if it is the highest priority ready to + run tasks, executed. .. c:function:: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state) diff --git a/Documentation/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst index 4ac1c93000..6e47244613 100644 --- a/Documentation/reference/user/01_task_control.rst +++ b/Documentation/reference/user/01_task_control.rst @@ -873,15 +873,3 @@ Functions :param policy: The new value of the *spawn-stacksize* attribute. :return: On success, this function returns 0; on failure it will return an error number from ```` - -.. c:function:: int posix_spawn_file_actions_init(FAR posix_spawn_file_actions_t *file_actions); - - The ``posix_spawn_file_actions_init()`` function - initializes the object referenced by ``file_actions`` to an empty set of - file actions for subsequent use in a call to ``posix_spawn()`` or - ``posix_spawnp()``. - - :param file_actions: The address of the ``posix_spawn_file_actions_t`` - to be initialized. - :return: On success, this function returns 0; on failure it - will return an error number from ````. diff --git a/Documentation/reference/user/structures.rst b/Documentation/reference/user/structures.rst index 375b2e3090..ef05ee6273 100644 --- a/Documentation/reference/user/structures.rst +++ b/Documentation/reference/user/structures.rst @@ -106,6 +106,8 @@ NuttX and a MoBY application: size_t mq_curmsgs; /* Number of messages currently in queue */ }; +.. note that this gives a warning due to https://github.com/sphinx-doc/sphinx/issues/7819 + .. c:struct:: sigaction The following structure defines the action to take for given signal: