Merge pull request #345 from joan2937/release-v76

Release v76

.gitignore

@@ -1,5 +1,6 @@
 *.o
 *.so
+*.so.*
 *.pyc
 pig2vcd
 pigpiod
@@ -11,5 +12,10 @@ __pycache__
 build
 dist
 *.egg-info
-wavepad_jitter.py
 
+# DOC files
+DOC/dbase/pigpio.sqlite.*
+DOC/tmp
+DOC/MAN/*
+!DOC/MAN/README*
+DOC/HTML/*.html

DOC/MAN/README

@@ -1,2 +1 @@
-Placeholder directory for man pages.
-
+Placeholder directory for man pages. 

DOC/src/defs/pigs.def

@@ -320,6 +320,7 @@ WVAG trips     :: Add generic pulses to waveform :: gpioWaveAddGeneric
 WVAS u b db sb o bvs :: Add serial data to waveform    :: gpioWaveAddSerial
 
 WVCRE          :: Create a waveform   :: gpioWaveCreate
+WVCAP          :: Create a waveform of fixed size  :: gpioWaveCreatePad
 WVDEL wid      :: Delete selected waveform :: gpioWaveDelete
 
 WVTX wid       :: Transmits waveform once       :: gpioWaveTxSend
@@ -2783,6 +2784,49 @@ $ pigs wvcre
 ERROR: attempt to create an empty waveform
 ...
 
+WVCAP ::
+
+Similar to [*WVCRE*], this command creates a waveform but pads the consumed
+resources to a fixed size, specified as a percent of total resource.
+Padded waves of equal size can be re-cycled efficiently allowing newly
+created waves to re-use the resources of deleted waves of the same dimension.
+
+Upon success a wave id (>=0) is returned.  On error a negative status
+code will be returned.
+
+The data provided by the [*WVAG*] and [*WVAS*] commands are
+consumed by this command.
+
+As many waveforms may be created as there is space available.
+The wave id is passed to [*WVTX*] or [*WVTXR*] to specify the
+waveform to transmit.
+
+Normal usage would be
+
+Step 1. [*WVCLR*] to clear all waveforms and added data.
+
+Step 2. [*WVAG*]/[*WVAS*] calls to supply the waveform data.
+
+Step 3. [*WVCAP*] to create a waveform of a uniform size.
+
+Step 4. [*WVTX*] or [*WVTXR*] with the id of the waveform to transmit.
+
+Repeat steps 2 - 4 as needed.
+
+Step 5. Any wave id can now be deleted and another wave of the same size
+        can be created in its place.
+
+...
+# Create a wave that consumes 50% of the total resource:
+
+$ pigs wvag 16 0 5000000 0 16 5000000
+2
+$ pigs wvcap 50
+0
+$ pigs wvtx 0
+11918
+...
+
 WVDEL ::
 
 This command deletes the waveform with id [*wid*].

command.c

@@ -201,7 +201,8 @@ cmdInfo_t cmdInfo[]=
    {PI_CMD_WVBSY, "WVBSY", 101, 2, 1}, // gpioWaveTxBusy
    {PI_CMD_WVCHA, "WVCHA", 197, 0, 0}, // gpioWaveChain
    {PI_CMD_WVCLR, "WVCLR", 101, 0, 1}, // gpioWaveClear
-   {PI_CMD_WVCRE, "WVCRE", 101, 2, 1}, // gpioWaveCreate
+   {PI_CMD_WVCRE, "WVCRE", 101, 2, 1}, // gpioWaveCreate 
+   {PI_CMD_WVCAP, "WVCAP", 112, 2, 1}, // gpioWaveCreatePad
    {PI_CMD_WVDEL, "WVDEL", 112, 0, 1}, // gpioWaveDelete
    {PI_CMD_WVGO,  "WVGO" , 101, 2, 0}, // gpioWaveTxStart
    {PI_CMD_WVGOR, "WVGOR", 101, 2, 0}, // gpioWaveTxStart
@@ -693,7 +694,7 @@ int cmdParse(
       case 112: /* BI2CC FC  GDC  GPW  I2CC  I2CRB
                    MG  MICS  MILS  MODEG  NC  NP  PADG PFG  PRG
                    PROCD  PROCP  PROCS  PRRG  R  READ  SLRC  SPIC
-                   WVDEL  WVSC  WVSM  WVSP  WVTX  WVTXR  BSPIC
+                   WVCAP WVDEL  WVSC  WVSM  WVSP  WVTX  WVTXR  BSPIC
 
                    One positive parameter.
                 */

pigpio.3

@@ -584,6 +584,8 @@ gpioWaveAddSerial          Adds serial data to the waveform
 .br
 gpioWaveCreate             Creates a waveform from added data
 .br
+gpioWaveCreatePad          Creates a waveform of fixed size from added data
+.br
 gpioWaveDelete             Deletes a waveform
 .br
 
@@ -2662,6 +2664,89 @@ specified delay between the pulse and the next.
 Returns the new waveform id if OK, otherwise PI_EMPTY_WAVEFORM,
 PI_NO_WAVEFORM_ID, PI_TOO_MANY_CBS, or PI_TOO_MANY_OOL.
 
+.IP "\fBint gpioWaveCreatePad(int pctCB, int pctBOOL, int pctTOOL)\fP"
+.IP "" 4
+Similar to \fBgpioWaveCreate\fP, 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.
+
+.br
+
+.br
+
+.EX
+pctCB: 0-100, the percent of all DMA control blocks to consume.
+.br
+pctBOOL: 0-100, percent On-Off-Level (OOL) buffer to consume for wave output.
+.br
+pctTOOL: 0-100, the percent of OOL buffer to consume for wave input (flags).
+.br
+
+.EE
+
+.br
+
+.br
+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.
+
+.br
+
+.br
+Waveform data provided by \fBgpioWaveAdd*\fP and \fBrawWaveAdd*\fP functions are
+consumed by this function.
+
+.br
+
+.br
+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.
+
+.br
+
+.br
+\fBExample\fP
+.br
+
+.EX
+  // get firstWaveChunk, somehow
+.br
+  gpioWaveAddGeneric(firstWaveChunk);
+.br
+  wid = gpioWaveCreatePad(50, 50, 0);
+.br
+  gpioWaveTxSend(wid, PI_WAVE_MODE_ONE_SHOT);
+.br
+  // get nextWaveChunk
+.br
+
+.br
+  while (nextWaveChunk) {
+.br
+     gpioWaveAddGeneric(nextWaveChunk);
+.br
+     nextWid = gpioWaveCreatePad(50, 50, 0);
+.br
+     gpioWaveTxSend(nextWid, PI_WAVE_MODE_ONE_SHOT_SYNC);
+.br
+     while(gpioWaveTxAt() == wid) time_sleep(0.1);
+.br
+     gpioWaveDelete(wid);
+.br
+     wid = nextWid;
+.br
+     // get nextWaveChunk
+.br
+  }
+.br
+
+.EE
+
+.br
+
+.br
+
 .IP "\fBint gpioWaveDelete(unsigned wave_id)\fP"
 .IP "" 4
 This function deletes the waveform with id wave_id.
@@ -9484,6 +9569,27 @@ An array of script parameters.
 
 .br
 
+.IP "\fBpctBOOL\fP: 0-100" 0
+percent On-Off-Level (OOL) buffer to consume for wave output.
+
+.br
+
+.br
+
+.IP "\fBpctCB\fP: 0-100" 0
+the percent of all DMA control blocks to consume.
+
+.br
+
+.br
+
+.IP "\fBpctTOOL\fP: 0-100" 0
+the percent of OOL buffer to consume for wave input (flags).
+
+.br
+
+.br
+
 .IP "\fBpi_i2c_msg_t\fP" 0
 
 .EX
@@ -10636,6 +10742,8 @@ A 16-bit word value.
 .br
 #define PI_CMD_PROCU 117
 .br
+#define PI_CMD_WVCAP 118
+.br
 
 .br