Skip to content

Fix inconsistencies in the documentation of some records #535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarkRivers merged 14 commits into from
Jul 16, 2025
Merged

Fix inconsistencies in the documentation of some records #535

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
26cea5d
Document the correct record name for compression size
henriquesimoes Jun 4, 2025
e98068a
Document NumPreAllocBuffers readback record
henriquesimoes Jun 4, 2025
abac9bc
Document the correct record name for actual temperature
henriquesimoes Jun 5, 2025
91e1edd
Document unique id and time stamp records
henriquesimoes Jun 5, 2025
3438dc3
Drop commented out XMLPath record from HDF5 plugin
henriquesimoes Jun 6, 2025
81fff8c
Document correct record names for write status
henriquesimoes Jun 6, 2025
890fec3
Document correct record name for HDF5 writing run time
henriquesimoes Jun 6, 2025
4091937
Document correct record name for NumExtraDims readback
henriquesimoes Jun 6, 2025
2ababaf
Document correct record name for SWMR mode readback
henriquesimoes Jun 6, 2025
96db85a
Document HDF5 dataset fill value record
henriquesimoes Jun 6, 2025
c046248
Deduplicate indexed record entries in the HDF5 docs
henriquesimoes Jun 6, 2025
3e1e738
Standardize the way numbered record names are documented
henriquesimoes Jul 1, 2025
59c6fa7
Document HDF5 plugin extra dimension name records
henriquesimoes Jun 6, 2025
a48a993
Document HDF5 plugin extra dimension chunk records
henriquesimoes Jun 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 0 additions & 11 deletions ADApp/Db/NDFileHDF5.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -813,17 +813,6 @@ record(bi, "$(P)$(R)DimAttDatasets_RBV")
field(SCAN, "I/O Intr")
}

# File path.
# % autosave 2
#record(waveform, "$(P)$(R)XMLPath")
#{
# field(PINI, "YES")
# field(DTYP, "asynOctetWrite")
# field(INP, "@asyn($(PORT),$(ADDR=0),$(TIMEOUT=1))HDF5_layoutDirectory")
# field(FTVL, "CHAR")
# field(NELM, "256")
#}

record(waveform, "$(P)$(R)XMLErrorMsg_RBV")
{
field(DTYP, "asynOctetRead")
Expand Down
2 changes: 1 addition & 1 deletion docs/ADCore/ADDriver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ possible.
- r/o
- Actual detector temperature
- TEMPERATURE_ACTUAL
- $(P)$(R)Temperature_Actual
- $(P)$(R)TemperatureActual
- ai
* -
-
Expand Down
52 changes: 44 additions & 8 deletions docs/ADCore/NDArray.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -409,6 +409,41 @@ loading ADBase.template.
- BAYER_PATTERN
- $(P)$(R)BayerPattern_RBV
- mbbi
* -
-
-
- **Unique ID and time stamps of the array**
* - NDUniqueId
- asynInt32
- r/o
- Unique ID number of array assigned by the EPICS driver.
- UNIQUE_ID
- $(P)$(R)UniqueId_RBV
- longin
* - NDTimeStamp
- asynFloat64
- r/o
- Time stamp of array.
- TIME_STAMP
- $(P)$(R)TimeStamp_RBV
- ai
* - NDEpicsTSSec
- asynInt32
- r/o
- Seconds past epoch time stamp of array assigned by the EPICS driver. It
is based on the EPICS epoch.
- EPICS_TS_SEC
- $(P)$(R)EpicsTSSec_RBV
- longin
* - NDEpicsTSNsec
- asynInt32
- r/o
- Nanoseconds time stamp fraction of the EPICS time stamp. It should be
composed with $(P)$(R)EpicsTSSec_RBV to get the final time stamp with
nanosecond resolution.
- EPICS_TS_NSEC
- $(P)$(R)EpicsTSNsec_RBV
- longin
Comment on lines +416 to +446
Copy link
Member

@ericonr ericonr Jul 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mentioned having to explain the meaning of each parameter in order to differentiate them. Could this documentation simply point to the (ported to rst version of the) areaDetectorTimeStampSupport page? See #537

Copy link
Member Author

@henriquesimoes henriquesimoes Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find it reasonable to deduplicate the explanation about such things. However, I did find the areaDetectorSupport page very IOC developer-oriented.

From my perspective, this documentation we are updating has a broader audience. End-users should be able to understand what a PV does without having to dig to much into details. Maybe that's a misconception of my part.

Well, if we are going to reference that page (or an adapted version of it), we still need to restore it. Are you planning to submit a PR for this? Or do you think we should include in the scope of this patch series?

Copy link
Member

@ericonr ericonr Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, I did find the areaDetectorSupport page very IOC developer-oriented.

Maybe driver developer oriented, even.

From my perspective, this documentation we are updating has a broader audience. End-users should be able to understand what a PV does without having to dig to much into details.

I think that's fair! Maybe you could simply use the shorter definitions from that page? I thought they were more concise:

$(P)$(R)EpicsTSSec_RBV contains the secPastEpoch field of the current NDArray.epicsTS timestamp
$(P)$(R)EpicsTSNsec_RBV contains the nsec fields of the current NDArray.epicsTS timestamp

Well, if we are going to reference that page (or an adapted version of it), we still need to restore it. Are you planning to submit a PR for this? Or do you think we should include in the scope of this patch series?

I opened an issue because I wasn't planning to submit a PR for now. If you include it in this patch series, I think it'd be nice, since it allows us to link it as "if you want to understand this feature further".

* -
-
-
Expand All @@ -430,13 +465,14 @@ loading ADBase.template.
* - N.A.
- N.A
- r/o
- Size of each array dimension, extracted from the $(P)$(R)Dimensions and $(P)$(R)Dimensions_RBV
- Size of each array dimension K in [0..9], extracted from the $(P)$(R)Dimensions and $(P)$(R)Dimensions_RBV
waveform records. Note that these are both longin record, i.e. readonly values using
subarray records. In the future longout records may be added to write to the individual
values in $(P)$(R)Dimensions.
- N.A.
- $(P)$(R)ArraySize[N] N=0-9
, (P)$(R)ArraySize[N]_RBV
- $(P)$(R)ArraySize<K>, $(P)$(R)ArraySize<K>_RBV

E.g. $(P)$(R)ArraySize0_RBV
- longin, longin
* - NDArraySizeX
- asynInt32
Expand Down Expand Up @@ -479,7 +515,7 @@ loading ADBase.template.
- Compressed size of the array data in bytes. Only meaningful if NDCodec is not empty
string.
- COMPRESSED_SIZE
- $(P)$(R)Compressed_RBV
- $(P)$(R)CompressedSize_RBV
- longin
* -
-
Expand Down Expand Up @@ -614,8 +650,8 @@ loading ADBase.template.
The value of this record must be set with caution, because too large a value could
use all memory on the system, resulting serious performance degradation.
- POOL_NUM_PRE_ALLOC_BUFFERS
- $(P)$(R)NumPreAllocBuffers
- longout
- $(P)$(R)NumPreAllocBuffers, $(P)$(R)NumPreAllocBuffers_RBV
- longout, longin
* - NDPoolPreAllocBuffers
- asynInt32
- r/w
Expand Down Expand Up @@ -773,15 +809,15 @@ loading ADBase.template.
- File write status. Gives status information on last file open or file write operation.
Values are WriteOK (0) and WriteError (1).
- WRITE_STATUS
- $(P)$(R)FileWriteStatus
- $(P)$(R)WriteStatus
- mbbi
* - NDFileWriteMessage
- asynOctet
- r/o
- File write error message. An error message string if the previous file open or file
write operation resulted in an error.
- WRITE_MESSAGE
- $(P)$(R)FileWriteMessage
- $(P)$(R)WriteMessage
- waveform
* - NDFileCapture
- asynInt32
Expand Down
184 changes: 67 additions & 117 deletions docs/ADCore/NDFileHDF5.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -662,6 +662,12 @@ Parameters and Records
- HDF5_dimAttDatasets
- $(P)$(R)DimAttDatasets, $(P)$(R)DimAttDatasets_RBV
- bo, bi
* - asynFloat64
- r/w
- Fill value for the dataset to be set in its creation property list.
- HDF5_fillValue
- $(P)$(R)FillValue, $(P)$(R)FillValue_RBV
- ao, ai
* -
-
- **SWMR**
Expand All @@ -677,7 +683,7 @@ Parameters and Records
- Turn on or off SWMR mode for the next acquisition (1 = On, 0 = Off). Turning on
will only work if SWMR mode is supported.
- HDF5_SWMRMode
- $(P)$(R)SWMRMode, $(P)$(R)SMWRMode_RBV
- $(P)$(R)SWMRMode, $(P)$(R)SWMRMode_RBV
- bo, bi
* - asynInt32
- r/o
Expand Down Expand Up @@ -723,67 +729,79 @@ Parameters and Records
- r/w
- Number of extra dimensions [0..9]
- HDF5_nExtraDims
- $(P)$(R)NumExtraDims, $(P)$(R)NumExtraDims
- $(P)$(R)NumExtraDims, $(P)$(R)NumExtraDims_RBV
- mbbo, mbbi
* - asynInt32
- r/w
- Size of extra dimension N (no. of frames per point)
- HDF5_extraDimSizeN
- $(P)$(R)ExtraDimSizeN, $(P)$(R)ExtraDimSizeN_RBV
-
* - asynOctet
- r/o
- HDF5_extraDimNameN
- Name of extra dimension N
- $(P)$(R)ExtraDimNameN_RBV
- stringin
* - asynInt32
- r/w
- Size of extra dimension X
- HDF5_extraDimSizeX
- $(P)$(R)ExtraDimSizeX, $(P)$(R)ExtraDimSizeX_RBV
- longout, longin
* - asynOctet
- r/o
- Name of extra dimension X
- HDF5_extraDimNameX
- $(P)$(R)ExtraDimNameX_RBV
- stringin
* - asynInt32
- r/w
- Size of extra dimension Y
- HDF5_extraDimSizeY
- $(P)$(R)ExtraDimSizeY, $(P)$(R)ExtraDimSizeY_RBV
- longout, longin
* - asynInt32
- r/w
- Size of extra dimension 3
- HDF5_extraDimSize3
- $(P)$(R)ExtraDimSize3, $(P)$(R)ExtraDimSize3_RBV
- longout, longin
* - asynInt32
- r/w
- Size of extra dimension 4
- HDF5_extraDimSize4
- $(P)$(R)ExtraDimSize4, $(P)$(R)ExtraDimSize4_RBV
- longout, longin
* - asynInt32
- r/w
- Size of extra dimension 5
- HDF5_extraDimSize5
- $(P)$(R)ExtraDimSize5, $(P)$(R)ExtraDimSize5_RBV
- Chunk of extra dimension X
- HDF5_extraDimChunkX
- $(P)$(R)ExtraDimChunkX, $(P)$(R)ExtraDimChunkX_RBV
- longout, longin
* - asynInt32
- r/w
- Size of extra dimension 6
- HDF5_extraDimSize6
- $(P)$(R)ExtraDimSize6, $(P)$(R)ExtraDimSize6_RBV
- Size of extra dimension Y
- HDF5_extraDimSizeY
- $(P)$(R)ExtraDimSizeY, $(P)$(R)ExtraDimSizeY_RBV
- longout, longin
* - asynOctet
- r/o
- Name of extra dimension Y
- HDF5_extraDimNameY
- $(P)$(R)ExtraDimNameY_RBV
- stringin
* - asynInt32
- r/w
- Size of extra dimension 7
- HDF5_extraDimSize7
- $(P)$(R)ExtraDimSize7, $(P)$(R)ExtraDimSize7_RBV
- Chunk of extra dimension Y
- HDF5_extraDimChunkY
- $(P)$(R)ExtraDimChunkY, $(P)$(R)ExtraDimChunkY_RBV
- longout, longin
* - asynInt32
- r/w
- Size of extra dimension 8
- HDF5_extraDimSize8
- $(P)$(R)ExtraDimSize8, $(P)$(R)ExtraDimSize8_RBV
- Size of the K'th extra dimension, for K in [3..9]
- HDF5_extraDimSize<K>
- $(P)$(R)ExtraDimSize<K>, $(P)$(R)ExtraDimSize<K>_RBV

E.g. $(P)$(R)ExtraDimSize3_RBV
- longout, longin
* - asynOctet
- r/o
- Name of the K'th extra dimension, for K in [3..9]
- HDF5_extraDimName<K>
- $(P)$(R)ExtraDimName<K>_RBV

E.g $(P)$(R)ExtraDimName8_RBV
- stringin
* - asynInt32
- r/w
- Size of extra dimension 9
- HDF5_extraDimSize9
- $(P)$(R)ExtraDimSize9, $(P)$(R)ExtraDimSize9_RBV
- Chunk of the K'th extra dimension, for K in [3..9]
- HDF5_extraDimChunk<K>
- $(P)$(R)ExtraDimChunk<K>, $(P)$(R)ExtraDimChunk<K>_RBV

E.g. $(P)$(R)ExtraDimChunk9
- longout, longin
* -
-
Expand Down Expand Up @@ -814,45 +832,11 @@ Parameters and Records
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 3rd index
- HDF5_posNameDim3
- $(P)$(R)PosNameDim3, $(P)$(R)PosNameDim3_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 4th index
- HDF5_posNameDim4
- $(P)$(R)PosNameDim4, $(P)$(R)PosNameDim4_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 5th index
- HDF5_posNameDim5
- $(P)$(R)PosNameDim5, $(P)$(R)PosNameDim5_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 6th index
- HDF5_posNameDim6
- $(P)$(R)PosNameDim6, $(P)$(R)PosNameDim6_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 7th index
- HDF5_posNameDim7
- $(P)$(R)PosNameDim7, $(P)$(R)PosNameDim7_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 8th index
- HDF5_posNameDim8
- $(P)$(R)PosNameDim8, $(P)$(R)PosNameDim8_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute name for the 9th index
- HDF5_posNameDim9
- $(P)$(R)PosNameDim9, $(P)$(R)PosNameDim9_RBV
- Specify the NDAttribute name for the K'th index, for K in [3..9]
- HDF5_posNameDim<K>
- $(P)$(R)PosNameDim<K>, $(P)$(R)PosNameDim<K>_RBV

E.g. $(P)$(R)PosNameDim5
- stringout, stringin
* -
-
Expand All @@ -863,59 +847,25 @@ Parameters and Records
- HDF5_posIndexDimN
- $(P)$(R)PosIndexDimN, $(P)$(R)PosIndexDimN_RBV
- stringout, stringin
* - asynOctet
* - asynOcte9
Comment on lines -866 to +850
Copy link
Member

@ericonr ericonr Jul 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo sneaked in

- r/w
- Specify the NDAttribute index for the X dimension
- HDF5_posIndexDimX
- $(P)$(R)posIndexDimX, $(P)$(R)posIndexDimX_RBV
- $(P)$(R)PosIndexDimX, $(P)$(R)PosIndexDimX_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the Y dimension
- HDF5_posIndexDimY
- $(P)$(R)posIndexDimY, $(P)$(R)posIndexDimY_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 3rd dimension
- HDF5_posIndexDim3
- $(P)$(R)posIndexDim3, $(P)$(R)posIndexDim3_RBV
- $(P)$(R)PosIndexDimY, $(P)$(R)PosIndexDimY_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 4th dimension
- HDF5_posIndexDim4
- $(P)$(R)posIndexDim4, $(P)$(R)posIndexDim4_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 5th dimension
- HDF5_posIndexDim5
- $(P)$(R)posIndexDim5, $(P)$(R)posIndexDim5_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 6th dimension
- HDF5_posIndexDim6
- $(P)$(R)posIndexDim6, $(P)$(R)posIndexDim6_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 7th dimension
- HDF5_posIndexDim7
- $(P)$(R)posIndexDim7, $(P)$(R)posIndexDim7_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 8th dimension
- HDF5_posIndexDim8
- $(P)$(R)posIndexDim8, $(P)$(R)posIndexDim8_RBV
- stringout, stringin
* - asynOctet
- r/w
- Specify the NDAttribute index for the 9th dimension
- HDF5_posIndexDim9
- $(P)$(R)posIndexDim9, $(P)$(R)posIndexDim9_RBV
- Specify the NDAttribute index for the K'th dimension, for K in [3..9]
- HDF5_posIndexDim<K>
- $(P)$(R)PosIndexDim<K>, $(P)$(R)PosIndexDim<K>_RBV

E.g. $(P)$(R)PosIndexDim9_RBV
- stringout, stringin
* -
-
Expand All @@ -924,7 +874,7 @@ Parameters and Records
- r/o
- Total runtime in seconds from first frame to file closed
- HDF5_totalRuntime
- $(P)$(R)Runtime
- $(P)$(R)RunTime
- ai
* - asynFloat64
- r/o
Expand Down
Loading
Loading