aboutsummaryrefslogtreecommitdiffstats
path: root/notes
diff options
context:
space:
mode:
Diffstat (limited to 'notes')
-rw-r--r--notes/coding_standard.txt123
-rw-r--r--notes/native-pin-definitions.txt201
-rw-r--r--notes/pin-mapping.txt101
3 files changed, 389 insertions, 36 deletions
diff --git a/notes/coding_standard.txt b/notes/coding_standard.txt
index bab1e38..5cb96c3 100644
--- a/notes/coding_standard.txt
+++ b/notes/coding_standard.txt
@@ -1,21 +1,31 @@
-Source code standards for libmaple.
+libmaple Coding Standards
+=========================
-Do it like this unless there's a really good reason why not. You
-being a lazy bastard doesn't count as a good reason.
+Author: Marti Bolivar (mbolivar@leaflabs.com)
+
+LeafLabs team members are required to follow these when producing new
+code. Community contributors to libmaple are strongly encouraged to
+do so; following these rules will greatly increase the probability
+that your patches will be folded in.
+
+In general, do it like this unless there's a really good reason why
+not. You being lazy doesn't count as a good reason. Most, if not
+all, of these decisions are entirely arbitrary, but it's important for
+readability that we be consistent.
The file .dir-locals.el in the libmaple root directory already ensures
-that many of these standards are followed by default, if you use emacs
-(and not Windows, where it would need to be named _dir_locals.el, and
-no way, man). There's also some elisp scattered about this file which
+that many of these standards are followed by default in Emacs (but not
+on Windows, where it would need to be named _dir_locals.el, and no
+way, man). There's also some elisp scattered about this file which
will provide you additional help.
-Vim customizations to do the same thing would be nice!
+Vim customizations to do the same thing would be nice (hint, hint)!
License
-------
- Put an MIT license at the beginning of the file (look at any of our
- source files for an example). Copyright should go to either your or
+ source files for an example). Copyright should go to either you or
LeafLabs LLC.
Emacs: if you don't like seeing the license, you should use
@@ -31,8 +41,8 @@ License
(dolist (hook mbolivar-programming-mode-hooks)
(add-hook hook (lambda () (elide-head))))
-Whitespace
-----------
+Whitespace/Indentation
+----------------------
- 4 space indents. [Set in .dir-locals.el]
@@ -45,17 +55,28 @@ Whitespace
http://github.com/mbolivar/code-fascism
- I hear tell you can get something similar in vim; ask Perry, I
+ I hear tell you can get something similar in vim; ask around, I
guess.
- Files end in exactly one newline. [The presence of a newline at EOF
is already done by `c-require-final-newline' in recent versions of
- emacs.]
+ Emacs.]
-- Exactly two newlines separate source paragraphs.
+- Exactly two newlines separate source paragraphs (you do separate
+ your code into paragraphs, don't you?).
- The first line in a function is non-blank.
+- Don't indent C code within a conditionally-compiled extern "C"
+ block. Emacs does this by default, which can be very annoying; you
+ can turn this behavior off with
+
+ (defun c-mode-inextern-lang-hook ()
+ (setcdr (assq 'inextern-lang c-offsets-alist) '-))
+
+ (add-hook 'c-mode-hook c-mode-inextern-lang-hook)
+
+
Comments
--------
@@ -72,6 +93,7 @@ Comments
* the comment can end on the same line */
- Doxygen comments are newline comments that begin with /** instead.
+ It is not required that the "/**" appear on a line by itself.
- Single-line comments on the same line are // in c or c++.
@@ -94,9 +116,13 @@ Braces
Naming conventions
------------------
-So there's always a fight about upper and lower case vs. underscores.
-We'll handle this as follows. First, Dammit_Dont_Mix_Like_This,
-because It_Looks_Really_Ugly, ok?
+- There's always a fight about upper and lower case vs. underscores.
+ We'll handle this as follows.
+
+ First, Dammit_Dont_Mix_Like_This, because It_Looks_Really_Ugly, ok?
+ [There's been some debate about this, and some exceptions are
+ already grandfathered in, so in order to settle it, let's call this
+ a "recommendation" instead of "requirement".]
- Variables: Use underscores to separate words in C identifiers:
@@ -109,17 +135,24 @@ because It_Looks_Really_Ugly, ok?
this_is_not, and like I said, Dont_You_DareTryANYTHING_STUPID.
- Functions: C functions are all lowercase, and words are separated by
- underscores. C++ method names are camel cased.
+ underscores. C++ method names are camel cased (thisIsAnExample).
- Structs: pick a style from "Variables" or "Classes" depending on how
you mean it (since it might be either a simple record type, in which
case do like c variables, or you might be faking an object in c, in
- which case do like classes). If it's in a typedef, should also
- probably put _t at the end, but maybe you won't, and I don't really
- feel too strongly about it.
+ which case do like classes). If it's in a typedef, don't feel
+ obliged to put "_t" at the end of the name; we don't.
+
+- Macros and constants: all caps, separated by underscores. Variables
+ with the "const" qualifier aren't considered "constants" for the
+ purposes of this rule; i.e., case them according to the rules for
+ variables.
+
+- foo.h gets #ifdef'ed to _FOO_H_.
- Acronyms: The case of letters in an acronym is determined by the
- case of the first letter in the acronym. Examples:
+ case of the first letter in the acronym, which is determined by
+ following the above rules. Examples:
void usb_func() { ... }
@@ -128,21 +161,43 @@ because It_Looks_Really_Ugly, ok?
void initUSB();
};
- NEVER DO THIS:
+ Never do this:
class BadUsb { ... }; // say "GoodUSB" instead
-- Macros and constants: all caps, separated by underscores.
-
-- foo.h gets ifdef'ed to _FOO_H_.
-
Documentation
-------------
-- Document your code, bitches!
-
-- At least put a doxygen comment with a nonempty @brief for every
- source file you add. See the existing ones for examples.
+- Document your code. This should go without saying.
+
+- For complicated peripherals, it would be nice if you put longer-form
+ comments into this directory (notes/), with a comment in the
+ corresponding .h file referring to it. See libmaple/dac.h for an
+ example. That lets us keep the source files relatively clean while
+ still allowing new readers to have a starting point.
+
+- At least put a doxygen comment with a nonempty @brief for every .h
+ file you add. See the existing ones for examples. For now, it'd be
+ better if you didn't put a @brief into any .c[pp] files, since it
+ (currently) interferes with our documentation generator in a way
+ that I won't explain here (though you can look into the LeafLabs or
+ michaeljones breathe repos on github and potentially figure out
+ why).
+
+- Doxygen comments generally just belong on types, functions,
+ etc. that are part of the public user-facing API. This generally
+ means that if there's ReST documentation for it under docs/source/,
+ it needs Doxygen comments, and that ReST should use Breathe to pull
+ that Doxygen comment out. (For more info on this, see docs/README).
+
+ There are some exceptions to this rule since Breathe isn't totally
+ mature yet and Sphinx's C++ domain is still in flux. In these
+ cases, document the code "manually" in ReST.
+
+ This should be avoided if at all possible, since it creates a
+ maintenance burden of documenting things in two places at once, and
+ provides an opportunity for bad documentation to slip in, when the
+ code comments fall out of sync with the ReST docs.
General Formatting
------------------
@@ -157,8 +212,12 @@ General Formatting
http://www.helsinki.fi/~sjpaavol/programs/lineker.el
- Then put the file somewhere in your load-path, and
+ Then put the file somewhere in your load-path, and:
(require 'lineker)
- (dolist (hook programming-mode-hooks)
+ (dolist (hook '(c-mode-hook c++-mode-hook))
(add-hook hook (lambda () (lineker-mode 1))))
+
+ There are only a few exceptional situations. The most important one
+ is when specifying a lookup table like PIN_MAP where it'd be ugly to
+ split each entry over multiple lines.
diff --git a/notes/native-pin-definitions.txt b/notes/native-pin-definitions.txt
new file mode 100644
index 0000000..b871f89
--- /dev/null
+++ b/notes/native-pin-definitions.txt
@@ -0,0 +1,201 @@
+Maple Native (STM32F103ZE) pin definitions, by GPIO bank.
+
+Source: ST DOC ID 14611, Datasheet for STM32F103xC, STM32F103xD,
+STM32F103xE, Table 5, pp. 30--35.
+
+Some peripherals and extra functionality with less/no libmaple
+relevance (at time of writing) are given in "Other" following each
+bank's main table. Non-default alternate functions are not listed. If
+wirish will/does remap the pin's main function after reset, the main
+function is listed under "Other".
+
+This document was prepared carefully and is believed to be complete
+and correct, but the final arbiter of truth is the ST datasheet.
+
+*** NB: UART 4 and 5 are NOT USART (columns are labeled appropriately).
+
+---------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C USART SPI DAC 5v?
+---------------------------------------------------------------------------
+PA0 123in0 2ch1etr - - - 2cts - - -
+ 5ch1
+ 8etr
+PA1 123in1 5ch2 - - - 2rts - - -
+ 2ch2
+PA2 123in2 5ch3 - - - 2tx - - -
+ 2ch3
+PA3 123in3 5ch4 - - - 2rx - - -
+ 2ch4
+PA4 12in4 - - - - 2ck 1nss out1 -
+PA5 12in5 - - - - - 1sck out2 -
+PA6 12in6 8bkin - - - - 1miso - -
+ 3ch1
+PA7 12in7 8ch1n - - - - 1mosi - -
+ 3ch2
+PA8 - 1ch1 - - - 1ck - - Y
+PA9 - 1ch2 - - - 1tx - - Y
+PA10 - 1ch3 - - - 1rx - - Y
+PA11 - 1ch4 - - - 1cts - - Y
+PA12 - 1etr - - - 1rts - - Y
+PA13 - - - - - - - - Y
+PA14 - - - - - - - - Y
+PA15 - - - 3ws - - 3nss - Y
+
+Other:
+
+PA0: WKUP
+PA8: MCO
+PA11: USBDM, CAN_RX
+PA12: USBDP, CAN_TX
+PA13: JTMS-SWDIO (default)
+PA14: JTCK-SWCLK (default)
+PA15: JTDI (default)
+
+-------------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C USART SPI DAC 5v? SDIO
+-------------------------------------------------------------------------------
+PB0 12in8 3ch3 - - - - - - - -
+ 8ch2n
+PB1 12in9 3ch4 - - - - - - - -
+ 8ch3n
+PB2 - - - - - - - - Y -
+PB3 - - - 3ck - - 3sck - Y -
+PB4 - - - - - - 3miso - Y -
+PB5 - - - 3sd 1smba - 3mosi - - -
+PB6 - 4ch1 - - 1scl - - - Y -
+PB7 - 4ch2 NADV - 1sda - - - Y -
+PB8 - 4ch3 - - - - - - Y D4
+PB9 - 4ch4 - - - - - - Y D5
+PB10 - - - - 2scl 3tx - - Y -
+PB11 - - - - 2sda 3rx - - Y -
+PB12 - 1bkin - 2ws 2smba 3ck 2nss - Y -
+PB13 - 1ch1n - 2ck - 3cts 2sck - Y -
+PB14 - 1ch2n - - - 3rts 2miso - Y -
+PB15 - 1ch3n - 2sd - - 2mosi - Y -
+
+Other:
+
+PB2: BOOT1
+PB3: JTDO (default)
+PB4: NJTRST (default)
+
+-------------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C UART SPI DAC 5v? SDIO
+-------------------------------------------------------------------------------
+PC0 123in10 - - - - - - - - -
+PC1 123in11 - - - - - - - - -
+PC2 123in12 - - - - - - - - -
+PC3 123in13 - - - - - - - - -
+PC4 12in14 - - - - - - - - -
+PC5 12in15 - - - - - - - - -
+PC6 - 8ch1 - 2mck - - - - Y D6
+PC7 - 8ch2 - 3mck - - - - Y D7
+PC8 - 8ch3 - - - - - - Y D0
+PC9 - 8ch4 - - - - - - Y D1
+PC10 - - - - - 4tx - - Y D2
+PC11 - - - - - 4rx - - Y D3
+PC12 - - - - - 5tx - - Y CK
+PC13 - - - - - - - - - -
+PC14 - - - - - - - - - -
+PC15 - - - - - - - - - -
+
+Other:
+
+PC13: TAMPER_RTC
+PC14: OSC32_IN
+PC15: OSC32_OUT
+
+-------------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C UART SPI DAC 5v? SDIO
+-------------------------------------------------------------------------------
+PD0 - - D2 - - - - - Y -
+PD1 - - D3 - - - - - Y -
+PD2 - 3etr - - - 5rx - - Y CMD
+PD3 - - CLK - - - - - Y -
+PD4 - - NOE - - - - - Y -
+PD5 - - NWE - - - - - Y -
+PD6 - - NWAIT - - - - - Y -
+PD7 - - NE1 - - - - - Y -
+ NCE2
+PD8 - - D13 - - - - - Y -
+PD9 - - D14 - - - - - Y -
+PD10 - - D15 - - - - - Y -
+PD11 - - A16 - - - - - Y -
+PD12 - - A17 - - - - - Y -
+PD13 - - A18 - - - - - Y -
+PD14 - - D0 - - - - - Y -
+PD15 - - D1 - - - - - Y -
+
+Other:
+
+PD0: OSC_IN (default)
+PD1: OSC_OUT (default)
+
+---------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C USART SPI DAC 5v?
+---------------------------------------------------------------------------
+PE0 - 4etr NBL0 - - - - - Y
+PE1 - - NBL1 - - - - - Y
+PE2 - - A23 - - - - - Y
+PE3 - - A19 - - - - - Y
+PE4 - - A20 - - - - - Y
+PE5 - - A21 - - - - - Y
+PE6 - - A22 - - - - - Y
+PE7 - - D4 - - - - - Y
+PE8 - - D5 - - - - - Y
+PE9 - - D6 - - - - - Y
+PE10 - - D7 - - - - - Y
+PE11 - - D8 - - - - - Y
+PE12 - - D9 - - - - - Y
+PE13 - - D10 - - - - - Y
+PE14 - - D11 - - - - - Y
+PE15 - - D12 - - - - - Y
+
+Other:
+PE2: TRACECK
+PE3: TRACED0
+PE4: TRACED1
+PE5: TRACED2
+PE6: TRACED3
+
+---------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C USART SPI DAC 5v?
+---------------------------------------------------------------------------
+PF0 - - A0 - - - - - Y
+PF1 - - A1 - - - - - Y
+PF2 - - A2 - - - - - Y
+PF3 - - A3 - - - - - Y
+PF4 - - A4 - - - - - Y
+PF5 - - A5 - - - - - Y
+PF6 3in4 - NIORD - - - - - -
+PF7 3in5 - NREG - - - - - -
+PF8 3in6 - NIOWR - - - - - -
+PF9 3in7 - CD - - - - - -
+PF10 3in8 - INTR - - - - - -
+PF11 - - NIOS16 - - - - - Y
+PF12 - - A6 - - - - - Y
+PF13 - - A7 - - - - - Y
+PF14 - - A8 - - - - - Y
+PF15 - - A9 - - - - - Y
+
+---------------------------------------------------------------------------
+STM32 ADC Timer FSMC I2S I2C USART SPI DAC 5v?
+---------------------------------------------------------------------------
+PG0 - - A10 - - - - - Y
+PG1 - - A11 - - - - - Y
+PG2 - - A12 - - - - - Y
+PG3 - - A13 - - - - - Y
+PG4 - - A14 - - - - - Y
+PG5 - - A15 - - - - - Y
+PG6 - - INT2 - - - - - Y
+PG7 - - INT3 - - - - - Y
+PG8 - - - - - - - - Y
+PG9 - - NE2 - - - - - Y
+ NCE3
+PG10 - - NCE4_1 - - - - - Y
+ NE3
+PG11 - - NCE4_2 - - - - - Y
+PG12 - - NE4 - - - - - Y
+PG13 - - A24 - - - - - Y
+PG14 - - A25 - - - - - Y
+PG15 - - - - - - - - Y
diff --git a/notes/pin-mapping.txt b/notes/pin-mapping.txt
index 67a675c..24402ed 100644
--- a/notes/pin-mapping.txt
+++ b/notes/pin-mapping.txt
@@ -1,3 +1,11 @@
+The pin maps in this document are included for informational purposes
+only. The final arbiters of truth are the PIN_MAP definitions in
+../wirish/boards.h and the STM32 datasheets.
+
+====
+Maple
+====
+
Reserved Pins: Function
PA11 USBDM
PA12 USBDP
@@ -13,8 +21,12 @@ PC12 DISC
PD0 OSC_IN
PD1 OSC_OUT
+Alternate function remaps:
+
+None?
+
-------------------------------------------------------------------------------
-Pin STM32 PIN ADC Timer I2C UART SPI F/T
+Pin STM32 PIN ADC Timer I2C UART SPI 5v?
-------------------------------------------------------------------------------
D0 PA3 ADC3 TIM2_CH4 - USART2_RX - -
D1 PA2 ADC2 TIM2_CH3 - USART2_TX - -
@@ -64,7 +76,88 @@ D37 PC8 - - - - - Y
Note: former pin D38 (PC9) is now attached to the BUT button and there is a
GND connection where D38 was.
-todo:
-adc pin check
-jtag pins for gpio
+TODO:
+- [?] JTAG pins for GPIO
+
+==========
+Maple Mini
+==========
+
+Reserved pins:
+
+Pin Function
+--- --------
+PA11 USBDM
+PA12 USBDP
+PB8 BUT button
+PB9 DISC
+PD0 OSC_IN
+PD1 OSC_OUT
+
+Alternate function remaps:
+
+Pin Default Remap
+--- ------- -----
+PB4 JNTRST GPIO
+PB3 JTDO GPIO
+PA15 JTDI GPIO
+PA14 JTCK GPIO
+PA13 JTMS GPIO
+
+-------------------------------------------------------------------------------
+Pin STM32 PIN ADC Timer I2C USART SPI 5v?
+-------------------------------------------------------------------------------
+D0 PB11 - - I2C2_SDA USART3_RX - Y
+D1 PB10 - - I2C2_SCL USART3_TX - Y
+D2 PB2 - - - - - Y
+D3 PB0 ADC8 TIM3_CH3 - - - -
+D4 PA7 ADC7 TIM3_CH2 - - SPI1_MOSI -
+D5 PA6 ADC6 TIM3_CH1 - - SPI1_MISO -
+D6 PA5 ADC5 - - - SPI1_SCK -
+D7 PA4 ADC4 - - USART2_CK SPI1_NSS -
+D8 PA3 ADC3 TIM2_CH4 - USART2_RX - -
+D9 PA2 ADC2 TIM2_CH3 - USART2_TX - -
+D10 PA1 ADC1 TIM2_CH2 - USART2_RTS - -
+D11 PA0 ADC0 TIM2_CH1_ETR - USART2_CTS - -
+D12 PC15 - - - - - -
+D13 PC14 - - - - - -
+D14 PC13 - - - - - -
+D15 PB7 - TIM4_CH2 I2C1_SDA - - Y
+D16 PB6 - TIM4_CH1 I2C1_SCL - - Y
+D17 PB5 - - I2C1_SMBA - - -
+D18 PB4 - - - - - Y
+D19 PB3 - - - - - Y
+D20 PA15 - - - - - Y
+D21 PA14 - - - - - Y
+D22 PA13 - - - - - Y
+# D23 is USBDP, but supports:
+ PA12 - - - - - Y
+# D24 is USBDM, but supports:
+ PA11 - - - - - Y
+D25 PA10 - TIM1_CH3 - USART1_RX - Y
+D26 PA9 - TIM1_CH2 - USART1_TX - Y
+D27 PA8 - TIM1_CH1 - USART1_CK - Y
+D28 PB15 - TIM1_CH3N - - SPI2_MOSI Y
+D29 PB14 - TIM1_CH2N - USART3_RTS SPI2_MISO Y
+D30 PB13 - TIM1_CH1N - USART3_CTS SPI2_SCK Y
+D31 PB12 - TIM1_BKIN I2C2_SMBAL USART3_CK SPI2_NSS Y
+D32 PB8 0 TIM4_CH3 - - - Y
+D33 PB1 ADC9 TIM3_CH4 - - - -
+
+TODO:
+- [?] JTAG pins for GPIO
+
+============
+Maple Native
+============
+
+Reserved pins:
+
+TODO
+
+Alternate function remaps:
+
+TODO
+The pin map on Maple Native is in flux. However, the bank/port pin
+definitions are available in notes/native-pin-definitions.txt.
generated by cgit v1.2.3 (git 2.39.1) at 2025-10-31 04:45:51 +0000