Merge tag 'v78' of https://github.com/joan2937/pigpio into debian

1 files changed, 280 insertions, 162 deletions

diff --git a/pigpio.h b/pigpio.h
index 8c79d2c..40d21fc 100644
--- a/pigpio.h
+++ b/pigpio.h
@@ -13,7 +13,6 @@ of the public at large and to the detriment of our heirs and
 successors. We intend this dedication to be an overt act of
 relinquishment in perpetuity of all present and future rights to this
 software under copyright law.
-
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
@@ -31,7 +30,7 @@ For more information, please refer to <http://unlicense.org/>
 #include <stdint.h>
 #include <pthread.h>
 
-#define PIGPIO_VERSION 68
+#define PIGPIO_VERSION 78
 
 /*TEXT
 
@@ -73,8 +72,6 @@ The PWM and servo pulses are timed using the DMA and PWM peripherals.
 
 This use was inspired by Richard Hirst's servoblaster kernel module.
 
-See [[https://github.com/richardghirst/PiBits/tree/master/ServoBlaster]]
-
 *Usage*
 
 Include <pigpio.h> in your source files.
@@ -109,6 +106,16 @@ return error PI_NOT_INITIALISED.
 If the library is initialised the [*gpioCfg**] functions will return
 error PI_INITIALISED.
 
+If you intend to rely on signals sent to your application, you should
+turn off the internal signal handling as shown in this example:
+
+. .
+int cfg = gpioCfgGetInternals();
+cfg |= PI_CFG_NOSIGHANDLER;  // (1<<10)
+gpioCfgSetInternals(cfg);
+int status = gpioInitialise();
+. .
+
 TEXT*/
 
 /*OVERVIEW
@@ -118,7 +125,7 @@ ESSENTIAL
 gpioInitialise             Initialise library
 gpioTerminate              Stop library
 
-BEGINNER
+BASIC
 
 gpioSetMode                Set a GPIO mode
 gpioGetMode                Get a GPIO mode
@@ -128,29 +135,29 @@ gpioSetPullUpDown          Set/clear GPIO pull up/down resistor
 gpioRead                   Read a GPIO
 gpioWrite                  Write a GPIO
 
+PWM_(overrides_servo_commands_on_same_GPIO)
+
 gpioPWM                    Start/stop PWM pulses on a GPIO
+gpioSetPWMfrequency        Configure PWM frequency for a GPIO
+gpioSetPWMrange            Configure PWM range for a GPIO
+
 gpioGetPWMdutycycle        Get dutycycle setting on a GPIO
+gpioGetPWMfrequency        Get configured PWM frequency for a GPIO
+gpioGetPWMrange            Get configured PWM range for a GPIO
 
-gpioServo                  Start/stop servo pulses on a GPIO
-gpioGetServoPulsewidth     Get pulsewidth setting on a GPIO
+gpioGetPWMrealRange        Get underlying PWM range for a GPIO
 
-gpioDelay                  Delay for a number of microseconds
+Servo_(overrides_PWM_commands_on_same_GPIO)
 
-gpioSetAlertFunc           Request a GPIO level change callback
+gpioServo                  Start/stop servo pulses on a GPIO
 
-gpioSetTimerFunc           Request a regular timed callback
+gpioGetServoPulsewidth     Get pulsewidth setting on a GPIO
 
 INTERMEDIATE
 
-gpioTrigger                Send a trigger pulse to a GPIO.
-
-gpioSetWatchdog            Set a watchdog on a GPIO.
-
-gpioSetPWMrange            Configure PWM range for a GPIO
-gpioGetPWMrange            Get configured PWM range for a GPIO
+gpioTrigger                Send a trigger pulse to a GPIO
 
-gpioSetPWMfrequency        Configure PWM frequency for a GPIO
-gpioGetPWMfrequency        Get configured PWM frequency for a GPIO
+gpioSetWatchdog            Set a watchdog on a GPIO
 
 gpioRead_Bits_0_31         Read all GPIO in bank 1
 gpioRead_Bits_32_53        Read all GPIO in bank 2
@@ -161,88 +168,65 @@ gpioWrite_Bits_32_53_Clear Clear selected GPIO in bank 2
 gpioWrite_Bits_0_31_Set    Set selected GPIO in bank 1
 gpioWrite_Bits_32_53_Set   Set selected GPIO in bank 2
 
-gpioStartThread            Start a new thread
-gpioStopThread             Stop a previously started thread
-
-ADVANCED
-
-gpioGetPWMrealRange        Get underlying PWM range for a GPIO
-
+gpioSetAlertFunc           Request a GPIO level change callback
 gpioSetAlertFuncEx         Request a GPIO change callback, extended
 
-gpioSetISRFunc             Request a GPIO interrupt callback
-gpioSetISRFuncEx           Request a GPIO interrupt callback, extended
-
-gpioSetSignalFunc          Request a signal callback
-gpioSetSignalFuncEx        Request a signal callback, extended
+gpioSetTimerFunc           Request a regular timed callback
+gpioSetTimerFuncEx         Request a regular timed callback, extended
 
-gpioSetGetSamplesFunc      Requests a GPIO samples callback
-gpioSetGetSamplesFuncEx    Requests a GPIO samples callback, extended
+gpioStartThread            Start a new thread
+gpioStopThread             Stop a previously started thread
 
-gpioSetTimerFuncEx         Request a regular timed callback, extended
+ADVANCED
 
 gpioNotifyOpen             Request a notification handle
-gpioNotifyOpenWithSize     Request a notification handle with sized pipe
+gpioNotifyClose            Close a notification
+gpioNotifyOpenWithSize     Request a notification with sized pipe
 gpioNotifyBegin            Start notifications for selected GPIO
 gpioNotifyPause            Pause notifications
-gpioNotifyClose            Close a notification
-
-gpioSerialReadOpen         Opens a GPIO for bit bang serial reads
-gpioSerialReadInvert       Configures normal/inverted for serial reads
-gpioSerialRead             Reads bit bang serial data from a GPIO
-gpioSerialReadClose        Closes a GPIO for bit bang serial reads
 
 gpioHardwareClock          Start hardware clock on supported GPIO
+
 gpioHardwarePWM            Start hardware PWM on supported GPIO
 
 gpioGlitchFilter           Set a glitch filter on a GPIO
 gpioNoiseFilter            Set a noise filter on a GPIO
 
-gpioGetPad                 Gets a pads drive strength
 gpioSetPad                 Sets a pads drive strength
+gpioGetPad                 Gets a pads drive strength
 
 shell                      Executes a shell command
 
-SCRIPTS
-
-gpioStoreScript            Store a script
-gpioRunScript              Run a stored script
-gpioUpdateScript           Set a scripts parameters
-gpioScriptStatus           Get script status and parameters
-gpioStopScript             Stop a running script
-gpioDeleteScript           Delete a stored script
-
-WAVES
-
-gpioWaveClear              Deletes all waveforms
+gpioSetISRFunc             Request a GPIO interrupt callback
+gpioSetISRFuncEx           Request a GPIO interrupt callback, extended
 
-gpioWaveAddNew             Starts a new waveform
-gpioWaveAddGeneric         Adds a series of pulses to the waveform
-gpioWaveAddSerial          Adds serial data to the waveform
+gpioSetSignalFunc          Request a signal callback
+gpioSetSignalFuncEx        Request a signal callback, extended
 
-gpioWaveCreate             Creates a waveform from added data
-gpioWaveDelete             Deletes a waveform
+gpioSetGetSamplesFunc      Requests a GPIO samples callback
+gpioSetGetSamplesFuncEx    Requests a GPIO samples callback, extended
 
-gpioWaveTxSend             Transmits a waveform
+Custom
 
-gpioWaveChain              Transmits a chain of waveforms
+gpioCustom1                User custom function 1
+gpioCustom2                User custom function 2
 
-gpioWaveTxAt               Returns the current transmitting waveform
+Events
 
-gpioWaveTxBusy             Checks to see if the waveform has ended
-gpioWaveTxStop             Aborts the current waveform
+eventMonitor               Sets the events to monitor
+eventSetFunc               Request an event callback
+eventSetFuncEx             Request an event callback, extended
 
-gpioWaveGetMicros          Length in microseconds of the current waveform
-gpioWaveGetHighMicros      Length of longest waveform so far
-gpioWaveGetMaxMicros       Absolute maximum allowed micros
+eventTrigger               Trigger an event
 
-gpioWaveGetPulses          Length in pulses of the current waveform
-gpioWaveGetHighPulses      Length of longest waveform so far
-gpioWaveGetMaxPulses       Absolute maximum allowed pulses
+Scripts
 
-gpioWaveGetCbs             Length in control blocks of the current waveform
-gpioWaveGetHighCbs         Length of longest waveform so far
-gpioWaveGetMaxCbs          Absolute maximum allowed control blocks
+gpioStoreScript            Store a script
+gpioRunScript              Run a stored script
+gpioUpdateScript           Set a scripts parameters
+gpioScriptStatus           Get script status and parameters
+gpioStopScript             Stop a running script
+gpioDeleteScript           Delete a stored script
 
 I2C
 
@@ -250,45 +234,40 @@ i2cOpen                    Opens an I2C device
 i2cClose                   Closes an I2C device
 
 i2cWriteQuick              SMBus write quick
-i2cWriteByte               SMBus write byte
+
 i2cReadByte                SMBus read byte
-i2cWriteByteData           SMBus write byte data
-i2cWriteWordData           SMBus write word data
+i2cWriteByte               SMBus write byte
+
 i2cReadByteData            SMBus read byte data
+i2cWriteByteData           SMBus write byte data
+
 i2cReadWordData            SMBus read word data
-i2cProcessCall             SMBus process call
-i2cWriteBlockData          SMBus write block data
+i2cWriteWordData           SMBus write word data
+
 i2cReadBlockData           SMBus read block data
-i2cBlockProcessCall        SMBus block process call
+i2cWriteBlockData          SMBus write block data
 
-i2cWriteI2CBlockData       SMBus write I2C block data
 i2cReadI2CBlockData        SMBus read I2C block data
+i2cWriteI2CBlockData       SMBus write I2C block data
 
 i2cReadDevice              Reads the raw I2C device
 i2cWriteDevice             Writes the raw I2C device
 
+i2cProcessCall             SMBus process call
+i2cBlockProcessCall        SMBus block process call
+
 i2cSwitchCombined          Sets or clears the combined flag
 
 i2cSegments                Performs multiple I2C transactions
 
 i2cZip                     Performs multiple I2C transactions
 
+I2C_BIT_BANG
+
 bbI2COpen                  Opens GPIO for bit banging I2C
 bbI2CClose                 Closes GPIO for bit banging I2C
-bbI2CZip                   Performs multiple bit banged I2C transactions
-
-SPI
-
-spiOpen                    Opens a SPI device
-spiClose                   Closes a SPI device
 
-spiRead                    Reads bytes from a SPI device
-spiWrite                   Writes bytes to a SPI device
-spiXfer                    Transfers bytes with a SPI device
-
-bbSPIOpen                  Opens GPIO for bit banging SPI
-bbSPIClose                 Closes GPIO for bit banging SPI
-bbSPIXfer                  Performs multiple bit banged SPI transactions
+bbI2CZip                   Performs bit banged I2C transactions
 
 I2C/SPI_SLAVE
 
@@ -301,50 +280,87 @@ serClose                   Closes a serial device
 
 serReadByte                Reads a byte from a serial device
 serWriteByte               Writes a byte to a serial device
+
 serRead                    Reads bytes from a serial device
 serWrite                   Writes bytes to a serial device
 
 serDataAvailable           Returns number of bytes ready to be read
 
+SERIAL_BIT_BANG_(read_only)
+
+gpioSerialReadOpen         Opens a GPIO for bit bang serial reads
+gpioSerialReadClose        Closes a GPIO for bit bang serial reads
+
+gpioSerialReadInvert       Configures normal/inverted for serial reads
+
+gpioSerialRead             Reads bit bang serial data from a GPIO
+
+SPI
+
+spiOpen                    Opens a SPI device
+spiClose                   Closes a SPI device
+
+spiRead                    Reads bytes from a SPI device
+spiWrite                   Writes bytes to a SPI device
+spiXfer                    Transfers bytes with a SPI device
+
+SPI_BIT_BANG
+
+bbSPIOpen                  Opens GPIO for bit banging SPI
+bbSPIClose                 Closes GPIO for bit banging SPI
+
+bbSPIXfer                  Performs bit banged SPI transactions
+
 FILES
 
 fileOpen                   Opens a file
 fileClose                  Closes a file
+
 fileRead                   Reads bytes from a file
 fileWrite                  Writes bytes to a file
+
 fileSeek                   Seeks to a position within a file
+
 fileList                   List files which match a pattern
 
-EVENTS
+WAVES
 
-eventMonitor               Sets the events to monitor
-eventSetFunc               Request an event callback
-eventSetFuncEx             Request an event callback, extended
-eventTrigger               Trigger an event
+gpioWaveClear              Deletes all waveforms
 
-CONFIGURATION
+gpioWaveAddNew             Starts a new waveform
+gpioWaveAddGeneric         Adds a series of pulses to the waveform
+gpioWaveAddSerial          Adds serial data to the waveform
 
-gpioCfgBufferSize          Configure the GPIO sample buffer size
-gpioCfgClock               Configure the GPIO sample rate
-gpioCfgDMAchannel          Configure the DMA channel (DEPRECATED)
-gpioCfgDMAchannels         Configure the DMA channels
-gpioCfgPermissions         Configure the GPIO access permissions
-gpioCfgInterfaces          Configure user interfaces
-gpioCfgSocketPort          Configure socket port
-gpioCfgMemAlloc            Configure DMA memory allocation mode
-gpioCfgNetAddr             Configure allowed network addresses
+gpioWaveCreate             Creates a waveform from added data
+gpioWaveCreatePad          Creates a waveform of fixed size from added data
+gpioWaveDelete             Deletes a waveform
 
-gpioCfgInternals           Configure miscellaneous internals (DEPRECATED)
-gpioCfgGetInternals        Get internal configuration settings
-gpioCfgSetInternals        Set internal configuration settings
+gpioWaveTxSend             Transmits a waveform
 
-CUSTOM
+gpioWaveChain              Transmits a chain of waveforms
 
-gpioCustom1                User custom function 1
-gpioCustom2                User custom function 2
+gpioWaveTxAt               Returns the current transmitting waveform
+
+gpioWaveTxBusy             Checks to see if the waveform has ended
+
+gpioWaveTxStop             Aborts the current waveform
+
+gpioWaveGetCbs             Length in CBs of the current waveform
+gpioWaveGetHighCbs         Length of longest waveform so far
+gpioWaveGetMaxCbs          Absolute maximum allowed CBs
+
+gpioWaveGetMicros          Length in micros of the current waveform
+gpioWaveGetHighMicros      Length of longest waveform so far
+gpioWaveGetMaxMicros       Absolute maximum allowed micros
+
+gpioWaveGetPulses          Length in pulses of the current waveform
+gpioWaveGetHighPulses      Length of longest waveform so far
+gpioWaveGetMaxPulses       Absolute maximum allowed pulses
 
 UTILITIES
 
+gpioDelay                  Delay for a number of microseconds
+
 gpioTick                   Get current tick (microseconds)
 
 gpioHardwareRevision       Get hardware revision
@@ -359,6 +375,21 @@ gpioSleep                  Sleep for specified time
 time_sleep                 Sleeps for a float number of seconds
 time_time                  Float number of seconds since the epoch
 
+CONFIGURATION
+
+gpioCfgBufferSize          Configure the GPIO sample buffer size
+gpioCfgClock               Configure the GPIO sample rate
+gpioCfgDMAchannel          Configure the DMA channel (DEPRECATED)
+gpioCfgDMAchannels         Configure the DMA channels
+gpioCfgPermissions         Configure the GPIO access permissions
+gpioCfgInterfaces          Configure user interfaces
+gpioCfgSocketPort          Configure socket port
+gpioCfgMemAlloc            Configure DMA memory allocation mode
+gpioCfgNetAddr             Configure allowed network addresses
+
+gpioCfgGetInternals        Get internal configuration settings
+gpioCfgSetInternals        Set internal configuration settings
+
 EXPERT
 
 rawWaveAddSPI              Not intended for general use
@@ -611,13 +642,16 @@ typedef void *(gpioThreadFunc_t) (void *);
 /* hardware PWM */
 
 #define PI_HW_PWM_MIN_FREQ 1
-#define PI_HW_PWM_MAX_FREQ 125000000
+#define PI_HW_PWM_MAX_FREQ      125000000
+#define PI_HW_PWM_MAX_FREQ_2711 187500000
 #define PI_HW_PWM_RANGE 1000000
 
 /* hardware clock */
 
-#define PI_HW_CLK_MIN_FREQ 4689
-#define PI_HW_CLK_MAX_FREQ 250000000
+#define PI_HW_CLK_MIN_FREQ       4689
+#define PI_HW_CLK_MIN_FREQ_2711 13184
+#define PI_HW_CLK_MAX_FREQ      250000000
+#define PI_HW_CLK_MAX_FREQ_2711 375000000
 
 #define PI_NOTIFY_SLOTS  32
 
@@ -678,7 +712,7 @@ typedef void *(gpioThreadFunc_t) (void *);
 /* Files, I2C, SPI, SER */
 
 #define PI_FILE_SLOTS 16
-#define PI_I2C_SLOTS  64
+#define PI_I2C_SLOTS  512
 #define PI_SPI_SLOTS  32
 #define PI_SER_SLOTS  16
 
@@ -773,6 +807,11 @@ typedef void *(gpioThreadFunc_t) (void *);
 #define BSC_MISO     20
 #define BSC_CE_N     21
 
+#define BSC_SDA_MOSI_2711 10
+#define BSC_SCL_SCLK_2711 11
+#define BSC_MISO_2711      9
+#define BSC_CE_N_2711      8
+
 /* Longest busy delay */
 
 #define PI_MAX_BUSY_DELAY 100
@@ -831,10 +870,10 @@ typedef void *(gpioThreadFunc_t) (void *);
 #define PI_CLOCK_PWM 0
 #define PI_CLOCK_PCM 1
 
-/* DMA channel: 0-14 */
+/* DMA channel: 0-15, 15 is unset */
 
 #define PI_MIN_DMA_CHANNEL 0
-#define PI_MAX_DMA_CHANNEL 14
+#define PI_MAX_DMA_CHANNEL 15
 
 /* port */
 
@@ -1415,6 +1454,12 @@ once per level change since the last time the thread was activated.
 i.e. The active alert functions will get all level changes but there
 will be a latency.
 
+If you want to track the level of more than one GPIO do so by
+maintaining the state in the callback.  Do not use [*gpioRead*].
+Remember the event that triggered the callback may have
+happened several milliseconds before and the GPIO may have
+changed level many times since then.
+
 The tick value is the time stamp of the sample in microseconds, see
 [*gpioTick*] for more details.
 
@@ -1953,6 +1998,49 @@ D*/
 
 
 /*F*/
+int gpioWaveCreatePad(int pctCB, int pctBOOL, int pctTOOL);
+/*D
+Similar to [*gpioWaveCreate*], this function creates a waveform but pads the consumed
+resources. Padded waves of equal dimension can be re-cycled efficiently allowing
+newly created waves to re-use the resources of deleted waves of the same dimension.
+
+. .
+pctCB: 0-100, the percent of all DMA control blocks to consume.
+pctBOOL: 0-100, percent On-Off-Level (OOL) buffer to consume for wave output.
+pctTOOL: 0-100, the percent of OOL buffer to consume for wave input (flags).
+. .
+
+Upon success a wave id greater than or equal to 0 is returned, otherwise
+PI_EMPTY_WAVEFORM, PI_TOO_MANY_CBS, PI_TOO_MANY_OOL, or PI_NO_WAVEFORM_ID.
+
+Waveform data provided by [*gpioWaveAdd**] and [*rawWaveAdd**] functions are
+consumed by this function.
+
+A usage would be the creation of two waves where one is filled while the other
+is being transmitted. Each wave is assigned 50% of the resources.
+This buffer structure allows the transmission of infinite wave sequences.
+
+...
+  // get firstWaveChunk, somehow
+  gpioWaveAddGeneric(firstWaveChunk);
+  wid = gpioWaveCreatePad(50, 50, 0);
+  gpioWaveTxSend(wid, PI_WAVE_MODE_ONE_SHOT);
+  // get nextWaveChunk
+
+  while (nextWaveChunk) {
+     gpioWaveAddGeneric(nextWaveChunk);
+     nextWid = gpioWaveCreatePad(50, 50, 0);
+     gpioWaveTxSend(nextWid, PI_WAVE_MODE_ONE_SHOT_SYNC);
+     while(gpioWaveTxAt() == wid) time_sleep(0.1);
+     gpioWaveDelete(wid);
+     wid = nextWid;
+     // get nextWaveChunk
+  }
+...
+
+D*/
+
+/*F*/
 int gpioWaveDelete(unsigned wave_id);
 /*D
 This function deletes the waveform with id wave_id.
@@ -2102,7 +2190,7 @@ D*/
 int gpioWaveTxAt(void);
 /*D
 This function returns the id of the waveform currently being
-transmitted.
+transmitted using [*gpioWaveTxSend*].  Chained waves are not supported.
 
 Returns the waveform id or one of the following special values:
 
@@ -2876,9 +2964,18 @@ D*/
 /*F*/
 int bscXfer(bsc_xfer_t *bsc_xfer);
 /*D
-This function provides a low-level interface to the
-SPI/I2C Slave peripheral.  This peripheral allows the
-Pi to act as a slave device on an I2C or SPI bus.
+This function provides a low-level interface to the SPI/I2C Slave
+peripheral on the BCM chip.
+
+This peripheral allows the Pi to act as a hardware slave device
+on an I2C or SPI bus.
+
+This is not a bit bang version and as such is OS timing
+independent. The bus timing is handled directly by the chip.
+
+The output process is simple. You simply append data to the FIFO
+buffer on the chip.  This works like a queue, you add data to the
+queue and the master removes it.
 
 I can't get SPI to work properly.  I tried with a
 control word of 0x303 and swapped MISO and MOSI.
@@ -2901,8 +2998,9 @@ typedef struct
 } bsc_xfer_t;
 . .
 
-To start a transfer set control (see below) and copy the bytes to
-be sent (if any) to txBuf and set the byte count in txCnt.
+To start a transfer set control (see below), copy the bytes to
+be added to the transmit FIFO (if any) to txBuf and set txCnt to
+the number of copied bytes.
 
 Upon return rxCnt will be set to the number of received bytes placed
 in rxBuf.
@@ -2910,11 +3008,19 @@ in rxBuf.
 Note that the control word sets the BSC mode.  The BSC will stay in
 that mode until a different control word is sent.
 
-The BSC peripheral uses GPIO 18 (SDA) and 19 (SCL) in I2C mode
-and GPIO 18 (MOSI), 19 (SCLK), 20 (MISO), and 21 (CE) in SPI mode.  You
-need to swap MISO/MOSI between master and slave.
+GPIO used for models other than those based on the BCM2711.
+
+    @ SDA @ SCL @ MOSI @ SCLK @ MISO @ CE
+I2C @ 18  @ 19  @ -    @ -    @ -    @ -
+SPI @ -   @ -   @ 18   @ 19   @ 20   @ 21
+
+GPIO used for models based on the BCM2711 (e.g. the Pi4B).
 
-When a zero control word is received GPIO 18-21 will be reset
+    @ SDA @ SCL @ MOSI @ SCLK @ MISO @ CE
+I2C @ 10  @ 11  @ -    @ -    @ -    @ -
+SPI @ -   @ -   @ 10   @ 11   @ 9    @ 8
+
+When a zero control word is received the used GPIO will be reset
 to INPUT mode.
 
 The returned function value is the status of the transfer (see below).
@@ -3980,7 +4086,7 @@ Frequencies above 30MHz are unlikely to work.
 
 . .
    gpio: see description
-clkfreq: 0 (off) or 4689-250000000 (250M)
+clkfreq: 0 (off) or 4689-250M (13184-375M for the BCM2711)
 . .
 
 Returns 0 if OK, otherwise PI_BAD_GPIO, PI_NOT_HCLK_GPIO,
@@ -4025,7 +4131,7 @@ main clock defaults to PCM but may be overridden by a call to
 
 . .
    gpio: see description
-PWMfreq: 0 (off) or 1-125000000 (125M)
+PWMfreq: 0 (off) or 1-125M (1-187.5M for the BCM2711)
 PWMduty: 0 (off) to 1000000 (1M)(fully on)
 . .
 
@@ -4052,12 +4158,12 @@ The GPIO must be one of the following.
 . .
 
 The actual number of steps beween off and fully on is the
-integral part of 250 million divided by PWMfreq.
+integral part of 250M/PWMfreq (375M/PWMfreq for the BCM2711).
 
-The actual frequency set is 250 million / steps.
+The actual frequency set is 250M/steps (375M/steps for the BCM2711).
 
-There will only be a million steps for a PWMfreq of 250.
-Lower frequencies will have more steps and higher
+There will only be a million steps for a PWMfreq of 250 (375 for
+the BCM2711). Lower frequencies will have more steps and higher
 frequencies will have fewer steps.  PWMduty is
 automatically scaled to take this into account.
 D*/
@@ -4745,8 +4851,7 @@ D*/
 
 
 /*F*/
-int gpioCfgDMAchannels(
-   unsigned primaryChannel, unsigned secondaryChannel);
+int gpioCfgDMAchannels(unsigned primaryChannel, unsigned secondaryChannel);
 /*D
 Configures pigpio to use the specified DMA channels.
 
@@ -4757,8 +4862,14 @@ This function is only effective if called before [*gpioInitialise*].
 secondaryChannel: 0-14
 . .
 
-The default setting is to use channel 14 for the primary channel and
-channel 6 for the secondary channel.
+The default setting depends on whether the Pi has a BCM2711 chip or
+not (currently only the Pi4B has a BCM2711).
+
+The default setting for a non-BCM2711 is to use channel 14 for the
+primary channel and channel 6 for the secondary channel.
+
+The default setting for a BCM2711 is to use channel 7 for the
+primary channel and channel 6 for the secondary channel.
 
 The secondary channel is only used for the transmission of waves.
 
@@ -4874,18 +4985,6 @@ D*/
 
 
 /*F*/
-int gpioCfgInternals(unsigned cfgWhat, unsigned cfgVal);
-/*D
-Used to tune internal settings.
-
-. .
-cfgWhat: see source code
- cfgVal: see source code
-. .
-D*/
-
-
-/*F*/
 uint32_t gpioCfgGetInternals(void);
 /*D
 This function returns the current library internal configuration
@@ -4901,6 +5000,7 @@ settings.
 . .
 cfgVal: see source code
 . .
+
 D*/
 
 
@@ -5305,13 +5405,14 @@ char::
 
 A single character, an 8 bit quantity able to store 0-255.
 
-clkfreq::4689-250M
+clkfreq::4689-250M (13184-375M for the BCM2711)
 
 The hardware clock frequency.
 
 . .
 PI_HW_CLK_MIN_FREQ 4689
 PI_HW_CLK_MAX_FREQ 250000000
+PI_HW_CLK_MAX_FREQ_2711 375000000
 . .
 
 count::
@@ -5331,10 +5432,10 @@ PI_MIN_WAVE_DATABITS 1
 PI_MAX_WAVE_DATABITS 32
 . .
 
-DMAchannel::0-14
+DMAchannel::0-15
 . .
 PI_MIN_DMA_CHANNEL 0
-PI_MAX_DMA_CHANNEL 14
+PI_MAX_DMA_CHANNEL 15
 . .
 
 double::
@@ -5701,6 +5802,15 @@ high and low levels.
 *param::
 An array of script parameters.
 
+pctBOOL:: 0-100
+percent On-Off-Level (OOL) buffer to consume for wave output.
+
+pctCB:: 0-100
+the percent of all DMA control blocks to consume.
+
+pctTOOL:: 0-100
+the percent of OOL buffer to consume for wave input (flags).
+
 pi_i2c_msg_t::
 . .
 typedef struct
@@ -5718,7 +5828,7 @@ The port used to bind to the pigpio socket.  Defaults to 8888.
 pos::
 The position of an item.
 
-primaryChannel:: 0-14
+primaryChannel:: 0-15
 The DMA channel used to time the sampling of GPIO and to time servo and
 PWM pulses.
 
@@ -5763,12 +5873,13 @@ The hardware PWM dutycycle.
 PI_HW_PWM_RANGE 1000000
 . .
 
-PWMfreq::5-250K
+PWMfreq::1-125M (1-187.5M for the BCM2711)
 The hardware PWM frequency.
 
 . .
 PI_HW_PWM_MIN_FREQ 1
 PI_HW_PWM_MAX_FREQ 125000000
+PI_HW_PWM_MAX_FREQ_2711 187500000
 . .
 
 range::25-40000
@@ -6211,6 +6322,7 @@ PARAMS*/
 #define PI_CMD_EVT   116
 
 #define PI_CMD_PROCU 117
+#define PI_CMD_WVCAP 118
 
 /*DEF_E*/
 
@@ -6301,11 +6413,11 @@ after this command is issued.
 #define PI_NO_HANDLE        -24 // no handle available
 #define PI_BAD_HANDLE       -25 // unknown handle
 #define PI_BAD_IF_FLAGS     -26 // ifFlags > 4
-#define PI_BAD_CHANNEL      -27 // DMA channel not 0-14
-#define PI_BAD_PRIM_CHANNEL -27 // DMA primary channel not 0-14
+#define PI_BAD_CHANNEL      -27 // DMA channel not 0-15
+#define PI_BAD_PRIM_CHANNEL -27 // DMA primary channel not 0-15
 #define PI_BAD_SOCKET_PORT  -28 // socket port not 1024-32000
 #define PI_BAD_FIFO_COMMAND -29 // unrecognized fifo command
-#define PI_BAD_SECO_CHANNEL -30 // DMA secondary channel not 0-6
+#define PI_BAD_SECO_CHANNEL -30 // DMA secondary channel not 0-15
 #define PI_NOT_INITIALISED  -31 // function called before gpioInitialise
 #define PI_INITIALISED      -32 // function called after gpioInitialise
 #define PI_BAD_WAVE_MODE    -33 // waveform mode not 0-3
@@ -6372,9 +6484,9 @@ after this command is issued.
 #define PI_NOT_SERVO_GPIO   -93 // GPIO is not in use for servo pulses
 #define PI_NOT_HCLK_GPIO    -94 // GPIO has no hardware clock
 #define PI_NOT_HPWM_GPIO    -95 // GPIO has no hardware PWM
-#define PI_BAD_HPWM_FREQ    -96 // hardware PWM frequency not 1-125M
+#define PI_BAD_HPWM_FREQ    -96 // invalid hardware PWM frequency
 #define PI_BAD_HPWM_DUTY    -97 // hardware PWM dutycycle not 0-1M
-#define PI_BAD_HCLK_FREQ    -98 // hardware clock frequency not 4689-250M
+#define PI_BAD_HCLK_FREQ    -98 // invalid hardware clock frequency
 #define PI_BAD_HCLK_PASS    -99 // need password to use hardware clock 1
 #define PI_HPWM_ILLEGAL    -100 // illegal, PWM in use for main clock
 #define PI_BAD_DATABITS    -101 // serial data bits not 1-32
@@ -6421,6 +6533,8 @@ after this command is issued.
 #define PI_NOT_SPI_GPIO    -142 // no bit bang SPI in progress on GPIO
 #define PI_BAD_EVENT_ID    -143 // bad event id
 #define PI_CMD_INTERRUPTED -144 // Used by Python
+#define PI_NOT_ON_BCM2711  -145 // not available on BCM2711
+#define PI_ONLY_ON_BCM2711 -146 // only available on BCM2711
 
 #define PI_PIGIF_ERR_0    -2000
 #define PI_PIGIF_ERR_99   -2099
@@ -6440,9 +6554,12 @@ after this command is issued.
 #define PI_DEFAULT_DMA_CHANNEL             14
 #define PI_DEFAULT_DMA_PRIMARY_CHANNEL     14
 #define PI_DEFAULT_DMA_SECONDARY_CHANNEL   6
+#define PI_DEFAULT_DMA_PRIMARY_CH_2711     7
+#define PI_DEFAULT_DMA_SECONDARY_CH_2711   6
+#define PI_DEFAULT_DMA_NOT_SET             15
 #define PI_DEFAULT_SOCKET_PORT             8888
 #define PI_DEFAULT_SOCKET_PORT_STR         "8888"
-#define PI_DEFAULT_SOCKET_ADDR_STR         "127.0.0.1"
+#define PI_DEFAULT_SOCKET_ADDR_STR         "localhost"
 #define PI_DEFAULT_UPDATE_MASK_UNKNOWN     0x0000000FFFFFFCLL
 #define PI_DEFAULT_UPDATE_MASK_B1          0x03E7CF93
 #define PI_DEFAULT_UPDATE_MASK_A_B2        0xFBC7CF9C
@@ -6450,6 +6567,7 @@ after this command is issued.
 #define PI_DEFAULT_UPDATE_MASK_ZERO        0x0080000FFFFFFCLL
 #define PI_DEFAULT_UPDATE_MASK_PI2B        0x0080480FFFFFFCLL
 #define PI_DEFAULT_UPDATE_MASK_PI3B        0x0000000FFFFFFCLL
+#define PI_DEFAULT_UPDATE_MASK_PI4B        0x0000000FFFFFFCLL
 #define PI_DEFAULT_UPDATE_MASK_COMPUTE     0x00FFFFFFFFFFFFLL
 #define PI_DEFAULT_MEM_ALLOC_MODE          PI_MEM_ALLOC_AUTO