From 88a0ebaf905daf8ba310474ee36ecbec21282512 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Sat, 25 Jan 2014 08:56:40 -0600 Subject: Improve documentation of naming conventions --- nuttx/Documentation/NuttxPortingGuide.html | 223 +++++++++++++++++------------ nuttx/include/nuttx/arch.h | 57 +++++++- 2 files changed, 190 insertions(+), 90 deletions(-) diff --git a/nuttx/Documentation/NuttxPortingGuide.html b/nuttx/Documentation/NuttxPortingGuide.html index 57f138388..04f122858 100644 --- a/nuttx/Documentation/NuttxPortingGuide.html +++ b/nuttx/Documentation/NuttxPortingGuide.html @@ -12,7 +12,7 @@

NuttX RTOS Porting Guide

-

Last Updated: September 28, 2013

+

Last Updated: January 25, 2013

@@ -72,44 +72,45 @@ 4.0 Architecture APIs 5.0 NuttX File System
@@ -1631,8 +1632,52 @@ The system can be re-made subsequently by just typing make. other header files.

-

4.1 APIs Exported by Architecture-Specific Logic to NuttX

-

4.1.1 up_initialize()

+

4.1 Naming and Header File Conventions

+ + + +

4.2 APIs Exported by Architecture-Specific Logic to NuttX

+

4.2.1 up_initialize()

Prototype: void up_initialize(void);

@@ -1653,7 +1698,7 @@ The system can be re-made subsequently by just typing make. services are available.

-

4.1.2 up_idle()

+

4.2.2 up_idle()

Prototype: void up_idle(void);

Description. @@ -1667,7 +1712,7 @@ The system can be re-made subsequently by just typing make. this is where power management operations might be performed.

-

4.1.3 up_initial_state()

+

4.2.3 up_initial_state()

Prototype: void up_initial_state(FAR struct tcb_s *tcb);

Description. @@ -1690,7 +1735,7 @@ The system can be re-made subsequently by just typing make. then all threads should have kernel-mode privileges.

-

4.1.4 up_create_stack()

+

4.2.4 up_create_stack()

Prototype: STATUS up_create_stack(FAR struct tcb_s *tcb, size_t stack_size, uint8_t ttype);

Description. @@ -1742,7 +1787,7 @@ The system can be re-made subsequently by just typing make. -

4.1.5 up_use_stack()

+

4.2.5 up_use_stack()

Prototype: STATUS up_use_stack(FAR struct tcb_s *tcb, FAR void *stack, size_t stack_size);

@@ -1781,7 +1826,7 @@ The system can be re-made subsequently by just typing make.

-

4.1.6 up_stack_frame()

+

4.2.6 up_stack_frame()

Prototype: FAR void *up_stack_frame(FAR struct tcb_s *tcb, size_t frame_size);

@@ -1831,7 +1876,7 @@ The system can be re-made subsequently by just typing make. The alignment of the returned value is the same as the alignment of the stack itself

-

4.1.7 up_release_stack()

+

4.2.7 up_release_stack()

Prototype: void up_release_stack(FAR struct tcb_s *dtcb);

Description. @@ -1870,7 +1915,7 @@ The system can be re-made subsequently by just typing make. -

4.1.8 up_unblock_task()

+

4.2.8 up_unblock_task()

Prototype: void up_unblock_task(FAR struct tcb_s *tcb);

Description. @@ -1893,7 +1938,7 @@ The system can be re-made subsequently by just typing make. -

4.1.9 up_block_task()

+

4.2.9 up_block_task()

Prototype: void up_block_task(FAR struct tcb_s *tcb, tstate_t task_state);

Description. @@ -1919,7 +1964,7 @@ The system can be re-made subsequently by just typing make. -

4.1.10 up_release_pending()

+

4.2.10 up_release_pending()

Prototype: void up_release_pending(void);

Description. @@ -1936,7 +1981,7 @@ The system can be re-made subsequently by just typing make. function is called.

-

4.1.11 up_reprioritize_rtr()

+

4.2.11 up_reprioritize_rtr()

Prototype: void up_reprioritize_rtr(FAR struct tcb_s *tcb, uint8_t priority);

Description. @@ -1971,7 +2016,7 @@ The system can be re-made subsequently by just typing make. -

4.1.12 _exit()

+

4.2.12 _exit()

Prototype: void _exit(int status) noreturn_function;

Description. @@ -1985,7 +2030,7 @@ The system can be re-made subsequently by just typing make. before performing scheduling operations.

-

4.1.13 up_assert()

+

4.2.13 up_assert()

Prototype:
void up_assert(FAR const uint8_t *filename, int linenum);

@@ -1994,7 +2039,7 @@ The system can be re-made subsequently by just typing make. Assertions may be handled in an architecture-specific way.

-

4.1.14 up_schedule_sigaction()

+

4.2.14 up_schedule_sigaction()

Prototype: void up_schedule_sigaction(FAR struct tcb_s *tcb, sig_deliver_t sigdeliver);

@@ -2041,7 +2086,7 @@ The system can be re-made subsequently by just typing make. is defined.

-

4.1.15 up_allocate_heap()

+

4.2.15 up_allocate_heap()

Prototype: void up_allocate_heap(FAR void **heap_start, size_t *heap_size);

Description. @@ -2052,14 +2097,14 @@ The system can be re-made subsequently by just typing make. If a protected kernel-space heap is provided, the kernel heap must be allocated (and protected) by an analogous up_allocate_kheap().

-

4.1.16 up_interrupt_context()

+

4.2.16 up_interrupt_context()

Prototype: bool up_interrupt_context(void)

Description. Return true if we are currently executing in the interrupt handler context.

-

4.1.17 up_disable_irq()

+

4.2.17 up_disable_irq()

Prototype:

-

4.3.3 Common LED interfaces

+

4.5.3 Common LED interfaces

The <arch-name>/src/common/up_internal.h probably has definitions @@ -2679,9 +2724,9 @@ else /* Defined in board/up_leds.c */ #ifdef CONFIG_ARCH_LEDS -extern void board_led_initialize(void); -extern void board_led_on(int led); -extern void board_led_off(int led); +void board_led_initialize(void); +void board_led_on(int led); +void board_led_off(int led); #else # define board_led_initialize() # define board_led_on(led) diff --git a/nuttx/include/nuttx/arch.h b/nuttx/include/nuttx/arch.h index 8a9047e80..13336ae8b 100644 --- a/nuttx/include/nuttx/arch.h +++ b/nuttx/include/nuttx/arch.h @@ -1,7 +1,7 @@ /**************************************************************************** * include/nuttx/arch.h * - * Copyright (C) 2007-2013 Gregory Nutt. All rights reserved. + * Copyright (C) 2007-2014 Gregory Nutt. All rights reserved. * Author: Gregory Nutt * * Redistribution and use in source and binary forms, with or without @@ -36,6 +36,61 @@ #ifndef __INCLUDE_NUTTX_ARCH_H #define __INCLUDE_NUTTX_ARCH_H +/* This header file contains function prototypes for the interfaces between + * (1) the nuttx core-code, (2) the microprocessor specific logic that + * resides under the arch/ sub-directory, and (3) the board-specific logic + * that resides under configs/ + * + * Naming conventions: + * + * 1. Common Microprocessor Interfaces. + * + * Any interface that is common across all microprocessors should be + * prefixed with up_ and prototyped in this header file. These + * definitions provide the common interface between NuttX and the + * architecture-specific implementation in arch/ + * + * NOTE: up_ is supposed to stand for microprocessor; the u is like the + * Greek letter micron: µ. So it would be µP which is a common shortening + * of the word microprocessor. + * + * 2. Microprocessor-Specific Interfaces. + * + * An interface which is unique to a certain microprocessor should be + * prefixed with the name of the microprocessor, for example stm32_, + * and be prototyped in some header file in the arch/ directories. + * + * There is also a arch//include//chip.h header file + * that can be used to communicate other microprocessor-specific + * information between the board logic and even application logic. + * Application logic may, for example, need to know specific capabilities + * of the chip. Prototypes in that chip.h header file should follow the + * microprocessor specific naming convention. + * + * 3. Common Board Interfaces. + * + * Any interface that is common across all boards should be prefixed + * with board_ and should be prototyped in this header file. These + * board_ definitions provide the interface between the board-level + * logic and the architecture-specific logic. + * + * There is also a configs//include/board.h header file that + * can be used to communicate other board-specific information between + * the architecture logic and even application logic. Any definitions + * which are common between a single architecture and several boards + * should go in this board.h header file; this file is reserved for + * board-related definitions common to all architectures. + * + * 4. Board-Specific Interfaces. + * + * Any interface which is unique to a board should be prefixed with + * the board name, for example stm32f4discovery_. Sometimes the board + * name is too long so stm32_ would be okay too. These should be + * prototyped in configs//src/.h and should not be used + * outside of that board directory since board-specific definitions + * have no meaning outside of the board directory. + */ + /**************************************************************************** * Included Files ****************************************************************************/ -- cgit v1.2.3